CoreEvents.Client 1.0.4

CoreEvents.Client

Client-SDK für CoreEvents – einen SignalR-basierten EventBus. Dieses Paket stellt eine einfache, DI‑freundliche API zum Abonnieren und Veröffentlichen von Events bereit und verbindet sich automatisch beim Starten Ihrer ASP.NET Core App.

• .NET: net9.0
• Transport: SignalR Hub unter /eventhub
• Authentifizierung: HTTP-Header X-API-Key
• Automatischer Reconnect ist aktiviert

Installation

dotnet add package CoreEvents.Client

Schnellstart

1) Registrierung in Program.cs

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddCoreEventBus(options =>
{
    options.ClientId = "orders-api";            // optional, für Source-Kennzeichnung
    options.Host = builder.Configuration["CoreEvents:Host"] ?? "localhost";
    options.Port = int.Parse(builder.Configuration["CoreEvents:Port"] ?? "5001");
    options.UseTls = true;                       // https oder http
    options.ApiKey = builder.Configuration["CoreEvents:ApiKey"] ?? "dev-key";
});

var app = builder.Build();

Die Extension AddCoreEventBus(...)

• registriert ICoreEventsClient für DI,
• richtet eine BackgroundService-Verbindung ein, die sich beim App‑Start automatisch mit dem EventHub verbindet.

2) Abonnieren eines Channels

Sie können an einer geeigneten Stelle nach App‑Start abonnieren, z. B. im ApplicationStarted-Callback oder in einem eigenen IHostedService.

// Nach app.Build():
app.Lifetime.ApplicationStarted.Register(() =>
{
    _ = Task.Run(async () =>
    {
        var client = app.Services.GetRequiredService<ICoreEventsClient>();

        await client.SubscribeAsync("orders.created", async envelope =>
        {
            // envelope.Payload ist ein string; ggf. in Ihr Modell deserialisieren
            Console.WriteLine($"[orders.created] EventId={envelope.EventId} Payload={envelope.Payload}");
            await Task.CompletedTask;
        });
    });
});

Alternativ: Implementieren Sie einen eigenen BackgroundService/IHostedService, injizieren Sie ICoreEventsClient und rufen Sie dort SubscribeAsync auf.

3) Events veröffentlichen

[ApiController]
[Route("api/orders")]
public class OrdersController(ICoreEventsClient events) : ControllerBase
{
    [HttpPost]
    public async Task<IActionResult> Create([FromBody] CreateOrderDto dto)
    {
        // ... Order anlegen ...

        var envelope = new EventEnvelope
        {
            EventId = Guid.NewGuid().ToString("N"),
            TimeStamp = DateTime.UtcNow,
            Channel = "orders.created",
            EventType = "order",
            Payload = JsonSerializer.Serialize(dto) // string payload
            // Source wird automatisch aus Options.ClientId gesetzt (oder "Unknown")
        };

        await events.PublishAsync(envelope);
        return Accepted();
    }
}

API-Überblick

Schnittstelle ICoreEventsClient:

public interface ICoreEventsClient
{
    Task ConnectAsync(CancellationToken cancellationToken = default);
    Task DisconnectAsync(CancellationToken cancellationToken = default);
    Task SubscribeAsync(string channel, Func<EventEnvelope, Task> handler, CancellationToken cancellationToken = default);
    Task UnsubscribeAsync(string channel, CancellationToken cancellationToken = default);
    Task PublishAsync(EventEnvelope envelope, CancellationToken cancellationToken = default);
}

Events werden als EventEnvelope übertragen:

public class EventEnvelope
{
    public string EventId { get; set; }
    public DateTime TimeStamp { get; set; }
    public string Channel { get; set; }
    public string Source { get; set; }          // wird beim Publish mit Options.ClientId gefüllt
    public string? EventType { get; set; }
    public string Payload { get; set; }         // freie Nutzlast als string (z. B. JSON)
}

Optionen

Konfigurierbar über CoreEventsOptions (bei AddCoreEventBus(...)):

• ClientId (string): Kennung des Clients; wird als Source im Event gesetzt.
• Host (string): Hostname oder IP des EventHub-Servers.
• Port (int): Port des EventHub-Servers.
• UseTls (bool): true für HTTPS, false für HTTP.
• ApiKey (string): API-Schlüssel, der als Header X-API-Key gesendet wird.

Beispiel via appsettings.json:

{
  "CoreEvents": {
    "ClientId": "orders-api",
    "Host": "events.example.com",
    "Port": 443,
    "UseTls": true,
    "ApiKey": "<Ihr-API-Key>"
  }
}

Und Einbindung in Program.cs:

builder.Services.AddCoreEventBus(opt => builder.Configuration.GetSection("CoreEvents").Bind(opt));

Laufzeitverhalten

• Verbindungsmanagement: Automatischer Reconnect ist aktiviert. Beim Verbindungsverlust wird erneut verbunden; Logs informieren über Statuswechsel.
• Authentifizierungsfehler: Der Server kann ein AuthError-Event senden. In diesem Fall wird geloggt und die Verbindung gestoppt.
• Hintergrunddienst: EventBusBackgroundService stellt beim App‑Start die Verbindung her und trennt beim Shutdown.

Voraussetzungen

• Server stellt einen SignalR Hub unter /eventhub bereit.
• Der Header X-API-Key muss mit dem vom Server erwarteten Schlüssel übereinstimmen.

Tipps & Troubleshooting

• Keine Events? Prüfen Sie:
  • Stimmt der Channel exakt überein (Groß-/Kleinschreibung beachten, sofern serverseitig relevant)?
  • Verbindungs- und Auth-Logs in Ihrer Anwendung (Kategorie CoreEvents.*).
  • Firewall/Proxy und ob UseTls und Port korrekt sind.
• Mehrere Handler für denselben Channel sind möglich; sie werden nacheinander aufgerufen. Fehler in einem Handler werden geloggt, blockieren aber die anderen nicht.

Lizenz & Support

Dieses Paket ist Teil des CoreScheduler/CoreEvents Projekts. Für Fragen, Feedback oder Probleme bitte ein Issue im entsprechenden Repository erstellen.