Arbeiten mit Events

Domänenereignisse

Domänenereignisse stellen wichtige Fakten dar, die im Kontext der Anwendung aufgetreten sind. Sie werden intern im System erzeugt und konsumiert, wodurch Zustandsänderungen entkoppelt propagiert werden können, das heißt, die Objekte müssen sich nicht direkt kennen.

Wann sollte ein Domänenereignis verwendet werden?

• Immer dann, wenn eine Operation eine signifikante Änderung im Domänenmodell erzeugt und es notwendig ist, andere Teile des Systems zu benachrichtigen oder auszulösen.
• Um das Domänenmodell kohärent zu halten und es zu ermöglichen, dass verschiedene Prozesse ausgelöst werden, ohne direkte Abhängigkeiten zwischen Modulen oder Services zu erzeugen.

In Lino ist das Erstellen eines neuen Domänenereignisses einfach. Sie können ausführen:

lino event new
lino event new --name <EventName> --service <ServiceName> --module <ModuleName> --entity <EntityName>
lino event edit --service <ServiceName> --module <ModuleName> --entity <EntityName>
lino event list --service <ServiceName> --module <ModuleName> --entity <EntityName>

Der CLI-Assistent wird Folgendes abfragen:

• Service – Der Service, in dem das Ereignis erstellt wird.
• Modul – Das Modul, in dem das Ereignis erstellt wird (nur in modularen Services).
• Entität – Die Entität, in der das Ereignis erstellt/assoziiert wird.
• Ereignistyp – Domänenereignis oder Integrationsereignis.
• Ereignisname – Im Domänenkontext verwendeter Name, der mit der Entität verknüpft wird.

Beispiel

Beim Erstellen des Domänenereignisses UserCreated, das mit der Entität User verknüpft ist, erstellt das System automatisch ein Ereignis mit dem Namen UserCreatedDomainEvent. Dieser Name macht für jeden Teil des Systems, der das Ereignis konsumiert, deutlich, dass die Benutzererstellung bereits abgeschlossen ist.

Von Lino generierte Struktur:

<ProjectName>/
└── src/
    └── Services/
        └── <ServiceName>/
            └── Domain/
                ├── <ProjectName>.<ServiceName>.Domain.csproj
                └── Aggregates/
                    └── Users/
                        ├── User.cs
                        ├── Errors/
                        ├── Events/
                        │   └── UserCreatedDomainEvent.cs
                        ├── Repositories/
                        └── Resources/

Technischer Ablauf in Lino

1. Das aggregate registriert ein IDomainEvent über RegisterDomainEvent.
2. Der command handler speichert über IUnitOfWork, bevorzugt mit SaveChangesInTransactionAsync wenn Events beteiligt sind.
3. Die Unit of Work persistiert Änderungen und veröffentlicht Events über MediatR.
4. Ein domain handler kann ein integration event in IOutbox registrieren.

Events sind keine Commands; verwenden Sie Vergangenheitsnamen wie UserCreatedDomainEvent.

Domänen-Ereignis-Handler

Ein Domain Event Handler ist eine Klasse, die dafür verantwortlich ist, auf ein Domänen-Ereignis zu reagieren und Aktionen im Zusammenhang mit dem internen Zustand der Anwendung auszuführen, immer innerhalb desselben Transaktionskontexts.

Der Hauptzweck dieser Handler besteht darin, das System kohärent und entkoppelt zu halten, sodass zusätzliche Regeln angewendet werden können, ohne die zentrale Logik der Entität oder des Aggregats zu überlasten.

Zum Beispiel kann es nach der Erstellung eines User erforderlich sein, Statistiken zu aktualisieren, ein internes Protokoll zu erstellen oder ein anderes Aggregat zu benachrichtigen. Diese Aktionen machen im Kontext der Domäne Sinn und können synchron erfolgen, wodurch sofortige Konsistenz gewährleistet wird.

Operationen, die jedoch von externen Ressourcen abhängen – wie das Versenden von E-Mails oder das Aufrufen von Drittanbieter-APIs – sollten nicht direkt aus Domänenereignissen ausgeführt werden, da dies die Transaktion an langsame oder instabile Aufgaben binden würde. In solchen Fällen kann die Domäne ein Integrationsereignis erzeugen (im Outbox-Mechanismus protokolliert), das später asynchron und resilient verarbeitet wird.

Hauptmerkmale:

• Reagiert auf ein Ereignis, ändert es jedoch niemals.
• Führt nur In-Process-Operationen aus, die mit der Konsistenz der Domäne zusammenhängen.
• Stellt sicher, dass alles innerhalb derselben Transaktion ausgeführt wird.

Um einen neuen Domänen-Ereignis-Handler zu erstellen, führen Sie einfach den Befehl aus:

lino event-handler new

Der CLI-Assistent wird Folgendes abfragen:

• Service – Der Service, in dem der Ereignis-Handler erstellt wird.
• Modul – Das Modul, in dem der Ereignis-Handler erstellt wird (nur in modularen Services).
• Entität – Die Entität, in der der Ereignis-Handler erstellt wird.
• Ereignistyp – Domänenereignis oder Integrationsereignis.
• Ereignis – Das zu konsumierende Ereignis.
• Name des Ereignis-Handlers – Der Name, der mit der Entität und dem Domänenereignis verknüpft wird.

Beispiel

Beim Erstellen des Domänen-Ereignis-Handlers UserCreated, der mit der Entität User und dem Ereignis UserCreatedDomainEvent verknüpft ist, erstellt das System automatisch einen Ereignis-Handler mit dem Namen UserCreatedDomainEventHandler.

Von Lino generierte Struktur:

<ProjectName>/
└── src/
    └── Services/
        └── <ServiceName>/
            └── Application/
                ├── <ProjectName>.<ServiceName>.Application.csproj
                └── UseCases/
                    └── Users/
                        ├── Commands/
                        ├── EventHandlers/
                        │   └── Domain/
                        │       └── UserCreatedDomainEventHandler.cs
                        ├── Logging/
                        ├── Queries/
                        └── Resources/

Technische Verantwortlichkeiten

• Implementiert IDomainEventHandler und reagiert innerhalb der Anwendung.
• Führt interne Konsistenz, logging, tracing oder Integrationsregistrierung aus.
• Verwendet IOutbox.RegisterIntegrationEvent für zuverlässige Nachrichten.
• Hält Business-Änderung und OutboxMessage in derselben Transaktion.

Integrationsereignisse

Integrationsereignisse sind Nachrichten, die darauf hinweisen, dass etwas Wichtiges passiert ist, und die mit externen Systemen oder anderen Microservices geteilt werden müssen.

Im Gegensatz zu Domänenereignissen besteht hier das Ziel in der Kommunikation zwischen Systemen und der Synchronisation von Zuständen.

Wann ein Integrationsereignis erstellen:

• Wenn eine Änderung in Ihrem System in einem anderen System widergespiegelt werden muss.
• Wenn Ihr Microservice Änderungen veröffentlichen muss, damit andere Microservices darauf reagieren können.

Hauptunterschiede zwischen Domain Events und Integration Events:

In Lino ist das Erstellen eines neuen Integrationsereignisses einfach. Sie können ausführen:

lino event new
lino event new --name <EventName> --service <ServiceName> --module <ModuleName> --entity <EntityName>
lino event list --service <ServiceName> --module <ModuleName> --entity <EntityName>

Der CLI-Assistent fragt nach:

• Service – Der Service, in dem das Ereignis erstellt wird.
• Modul – Das Modul, in dem das Ereignis erstellt wird (nur für modulare Services).
• Entität – Die Entität, in der das Ereignis erstellt / zugeordnet wird.
• Ereignistyp – Domänenereignis oder Integrationsereignis.
• Ereignisname – Name, der für das Integrationsereignis verwendet wird und mit der Entität verknüpft ist.

Beispiel

Wenn das Integrationsereignis UserCreated mit der Entität User erstellt wird, erstellt das System automatisch ein Ereignis mit dem Namen UserCreatedIntegrationEvent. Dieser Name macht für jeden Teil des Systems, der das Ereignis konsumiert, deutlich, dass die Benutzererstellung bereits abgeschlossen ist.

Von Lino generierte Struktur:

<ProjectName>/
└── src/
    └── Services/
        └── <ServiceName>/
            └── Integration.Events/
                ├── <ProjectName>.<ServiceName>.Integration.Events.csproj
                └── Users/
                    └── UserCreatedIntegrationEvent.cs

Zuverlässige Veröffentlichung

Ein integration event implementiert IIntegrationEvent und überschreitet Modul-, Service- oder Systemgrenzen. Die Anwendung registriert das Event in IOutbox, die Unit of Work speichert ein OutboxMessage, und ein Hangfire worker veröffentlicht später über MassTransit/RabbitMQ.

Integrations-Event-Handler

Ein Integration Event Handler ist eine Klasse, die dafür verantwortlich ist, ein Integrationsereignis zu konsumieren, das normalerweise von einem anderen Service oder Kontext veröffentlicht wird, und anschließend spezifische Aktionen in der eigenen Domäne auszuführen.

Diese Handler empfangen Ereignisse über Messaging-Systeme (wie RabbitMQ, Kafka, Azure Service Bus usw.), meist in Kombination mit dem Outbox-Pattern, das eine zuverlässige Zustellung und asynchrone Verarbeitung sicherstellt.

Zum Beispiel kann, wenn ein UserCreated-Ereignis von einem Identity-Service veröffentlicht wird, der entsprechende Handler in einem anderen Kontext reagieren, indem er eine Willkommens-E-Mail sendet oder externe APIs aufruft. Diese Vorgänge können langsamer oder fehleranfällig sein, beeinträchtigen jedoch die interne Konsistenz der Anwendung nicht, da sie außerhalb der Haupttransaktion behandelt werden.

Hauptmerkmale:

• Reagiert auf Ereignisse, die geschäftlich relevante Fakten für andere Kontexte darstellen.
• Führt Vorgänge aus, die langsam oder extern sein können (z. B. E-Mail-Versand, API-Aufrufe).
• Wird asynchron und resilient verarbeitet, oft mit Wiederholungen und Monitoring.
• Stellt sicher, dass externe Fehler die ursprüngliche Domänentransaktion nicht beeinflussen.
• Erleichtert die Integration zwischen Bounded Contexts und verteilten Systemen.

Um einen neuen Integrations-Event-Handler zu erstellen, führen Sie einfach folgenden Befehl aus:

lino event-handler new
lino event-handler new --name <EventHandlerName> --service <ServiceName> --module <ModuleName> --entity <EntityName>
lino event-handler list --service <ServiceName> --module <ModuleName> --entity <EntityName>

Der CLI-Assistent fragt Folgendes ab:

• Service – Der Service, in dem der Event-Handler erstellt wird.
• Modul – Das Modul, in dem der Event-Handler erstellt wird (nur in modularen Services).
• Entität – Die Entität, in der der Event-Handler erstellt wird.
• Ereignistyp – Domänenereignis oder Integrationsereignis.
• Service – Der Service, in dem das zu konsumierende Ereignis existiert.
• Modul – Das Modul, in dem das zu konsumierende Ereignis existiert (nur in modularen Services).
• Entität – Die Entität, in der das zu konsumierende Ereignis existiert.
• Ereignis – Das zu konsumierende Ereignis.
• Name des Event-Handlers – Name, der mit der Entität und dem Integrationsereignis verknüpft wird.

Beispiel

Beim Erstellen des Integrations-Event-Handlers SendEmailOnUserCreated, der mit der Entität User und dem Ereignis UserCreatedIntegrationEvent verknüpft ist, erstellt das System automatisch einen Event-Handler mit dem Namen SendEmailOnUserCreatedIntegrationEventHandler.

Von Lino generierte Struktur:

<ProjectName>/
└── src/
    └── Services/
        └── <ServiceName>/
            └── Application/
                ├── <ProjectName>.<ServiceName>.Application.csproj
                └── UseCases/
                    └── Users/
                        ├── Commands/
                        ├── EventHandlers/
                        │   └── Integration/
                        │       └── SendEmailOnUserCreatedIntegrationEventHandler.cs
                        ├── Logging/
                        ├── Queries/
                        └── Resources/

Operative Hinweise

• Implementiert IIntegrationEventHandler und konsumiert MassTransit Nachrichten.
• Liest nicht direkt die Datenbank des Producers.
• Aktualisiert lokalen Zustand, Projektionen oder shadow entities.
• Sollte idempotent sein, weil retries und doppelte Nachrichten möglich sind.

Shadow Entities

Eine shadow entity ist eine lokale, minimale und kontrollierte Kopie von Daten, deren Owner in einem anderen Modul oder Service liegt. Sie reduziert Kopplung, wenn der Consumer Referenzdaten abfragen, validieren oder anzeigen muss, ohne direkt auf die Producer-Datenbank zuzugreifen.

Shadow Entities sind nützlich, wenn eventual consistency akzeptabel ist. Der Producer veröffentlicht ein Integration Event, die Nachricht wird in der Outbox persistiert, der worker veröffentlicht sie auf dem Bus, und der Consumer aktualisiert seine lokale Kopie über einen integration event handler.

lino shadow-entity new
lino event new
lino event-handler new

Der Befehl ist auch über den Alias lino shadow new verfügbar. Im interaktiven Ablauf fragt Lino nach Ziel-Service oder Ziel-Modul, Source Entity und den zu kopierenden Properties. Dadurch müssen Identifier-Typ, Pflichtfeldstatus, string-Länge und grundlegende Referenzen nicht manuell neu erstellt werden, was Inkonsistenzen zwischen Source und Consumer reduziert.

Die shadow entity ist keine vollständige Replik. Im Beispiel eines Catalog-Moduls, das Daten aus Tenancy und Security konsumiert, kann der Catalog nur Tenant.Id, Tenant.Slug, User.Id, User.Email und User.TenantId speichern. Die ursprüngliche User-Entity enthält weiterhin Hash, Bestätigung, Tokens, Datumswerte und andere interne Felder, die nicht zum Catalog-Kontext gehören.

Wann verwenden

• Wenn der Consumer wenige Felder einer Entity benötigt, die zu einem anderen Kontext gehört.
• Wenn die Regel eine kurze Verzögerung zwischen Producer-Änderung und Consumer-Aktualisierung akzeptiert.
• Wenn direktes Lesen aus der Producer-Datenbank eine unzulässige Kopplung zwischen Modulen oder Services erzeugen würde.
• Wenn grids, Filter, lokale Validierungen oder Projektionen externe Referenzdaten benötigen.

Wann vermeiden

• Wenn die Regel sofort aktuelle Daten verlangt und keine eventual consistency akzeptiert.
• Wenn die lokale Kopie zu einer vollständigen Replik des ursprünglichen aggregate würde.
• Wenn der Consumer beginnt, von Invarianten abzuhängen, die dem Producer gehören.

Empfohlener Ablauf

1. Modelliere die shadow entity nur mit den Feldern, die der Consumer benötigt.
2. Erstelle oder wähle das vom Producer veröffentlichte integration event aus.
3. Erstelle einen integration event handler im Consumer.
4. Implementiere einen idempotenten upsert mit dem Producer-Schlüssel oder einem natürlichen Identifier.
5. Protokolliere genug Informationen, um retries, doppelte Nachrichten und permanente Fehler zu diagnostizieren.

Event-driven Synchronisierung

Der vollständige Ablauf kombiniert Domain, Application, Unit of Work, Outbox, worker, bus und Consumer. Ziel ist es, fragile direkte Aufrufe zwischen Modulen oder Services zu vermeiden und retry, Auditing und Reprocessing zu ermöglichen, wenn Veröffentlichung oder Verarbeitung fehlschlägt.

1. Ein aggregate ändert sich und registriert ein Domain Event.
2. Die Unit of Work speichert die Änderung innerhalb einer Transaktion.
3. Ein domain handler reagiert auf den Fakt und registriert ein Integration Event in IOutbox.
4. Die Unit of Work persistiert Business-Daten und OutboxMessage in derselben Transaktion.
5. Ein Hangfire worker liest die Outbox und veröffentlicht über MassTransit/RabbitMQ auf dem bus.
6. Der Consumer empfängt die Nachricht über einen IIntegrationEventHandler.
7. Der Consumer aktualisiert sein lokales Modell, shadow entity, Projektion, E-Mail, externe Integration oder einen anderen asynchronen Ablauf.

Domain change -> Domain Event -> Domain Handler -> Integration Event -> Outbox -> Worker -> Event Bus -> Consumer -> Local model

Designregeln

• Lege Invarianten in die Domain; verwende Events für Reaktionen, nicht um verpflichtende Regeln zu verstecken.
• Registriere integration events in derselben Transaktion wie die Business-Änderung.
• Halte Integrationsverträge klein, versionierbar und stabil.
• Implementiere idempotente consumers, weil retries und doppelte Nachrichten auftreten können.
• Überwache worker-Fehler und Nachrichten, die in der Outbox hängen bleiben.