Travailler avec les événements

Événements de Domaine

Les événements de domaine représentent des faits importants survenus dans le contexte de l'application. Ils sont générés et consommés en interne dans le système, permettant la propagation des changements d'état de manière découplée, c'est-à-dire sans que les objets aient besoin de se connaître directement.

Quand utiliser un Événement de Domaine ?

• Chaque fois qu'une opération génère un changement significatif dans le domaine et qu'il est nécessaire de notifier ou d'activer d'autres parties du système.
• Pour maintenir le modèle de domaine cohésif, permettant à différents processus d'être déclenchés sans créer de dépendances directes entre les modules ou services.

Dans Lino, créer un nouvel événement de domaine est simple. Vous pouvez exécuter :

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>

L'assistant CLI demandera :

• Service – Le service dans lequel l'événement sera créé.
• Module – Le module dans lequel l'événement sera créé (uniquement pour les services modulaires).
• Entité – L'entité dans laquelle l'événement sera créé/associé.
• Type d'événement – Événement de domaine ou événement d'intégration.
• Nom de l'événement – Nom utilisé dans le domaine, associé à l'entité.

Exemple

En créant l'événement de domaine UserCreated associé à l'entité User, le système crée automatiquement un événement nommé UserCreatedDomainEvent. Ce nom indique clairement à toute partie du système consommant l'événement que l'action de création de l'utilisateur a déjà été effectuée.

Structure générée par Lino :

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

Technical flow in Lino

1. The aggregate registers an IDomainEvent with RegisterDomainEvent.
2. The command handler saves through IUnitOfWork, preferably SaveChangesInTransactionAsync when events are involved.
3. The Unit of Work persists changes and publishes events through MediatR.
4. A domain handler can register an integration event in IOutbox.

Events are not commands; use past-tense names such as UserCreatedDomainEvent.

Gestionnaires d'Événements de Domaine

Un Domain Event Handler est une classe responsable de réagir à un Événement de Domaine, exécutant des actions liées à l'état interne de l'application, toujours dans le même contexte transactionnel.

L'objectif principal de ces gestionnaires est de maintenir le système cohésif et découplé, permettant l'application de règles supplémentaires sans surcharger la logique centrale de l'entité ou de l'agrégat.

Par exemple, après la création d'un User, il peut être nécessaire de mettre à jour les statistiques, générer un journal interne ou notifier un autre agrégat. Ces actions ont du sens dans le domaine et peuvent se produire de manière synchrone, garantissant une cohérence immédiate.

Cependant, les opérations qui dépendent de ressources externes — telles que l'envoi d'e-mails ou les appels à des API tierces — ne doivent pas être exécutées directement à partir des événements de domaine, car cela lierait la transaction à des tâches lentes ou instables. Dans ces cas, le domaine peut générer un événement d'intégration (enregistré dans l'Outbox), qui sera traité ultérieurement de manière asynchrone et résiliente.

Caractéristiques principales :

• Réagit à un événement mais ne le modifie jamais.
• Exécute uniquement des opérations in-process liées à la cohérence du domaine.
• Garantit que tout s'exécute dans la même transaction.

Pour créer un nouveau gestionnaire d'événements de domaine, il suffit d'exécuter la commande :

lino event-handler new

L'assistant CLI demandera :

• Service – Service dans lequel le gestionnaire d'événements sera créé.
• Module – Module dans lequel le gestionnaire d'événements sera créé (uniquement dans les services modulaires).
• Entité – Entité dans laquelle le gestionnaire d'événements sera créé.
• Type d'événement – Événement de domaine ou événement d'intégration.
• Événement – Événement qui sera consommé.
• Nom du gestionnaire d'événements – Nom utilisé qui sera associé à l'entité et à l'événement de domaine.

Exemple

En créant le gestionnaire d'événements de domaine UserCreated associé à l'entité User et à l'événement UserCreatedDomainEvent, le système crée automatiquement un gestionnaire d'événements nommé UserCreatedDomainEventHandler.

Structure générée par Lino :

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

Technical responsibilities

• Implements IDomainEventHandler and reacts inside the application boundary.
• Runs internal consistency, logging, tracing, or integration registration work.
• Uses IOutbox.RegisterIntegrationEvent for reliable messages.
• Keeps the business change and OutboxMessage in the same transaction.

Événements d'Intégration

Les événements d'intégration sont des messages indiquant qu'un événement important s'est produit et doivent être partagés avec des systèmes externes ou d'autres microservices.

Contrairement aux événements de domaine, l'objectif ici est la communication entre systèmes et la synchronisation des états.

Quand créer un Événement d'Intégration :

• Lorsque un changement dans votre système doit être reflété dans un autre système.
• Lorsque votre microservice doit publier des changements afin que d'autres microservices puissent réagir.

Principales différences entre les Domain Events et les Integration Events :

Dans Lino, créer un nouvel événement d'intégration est simple. Vous pouvez exécuter :

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

Le assistant CLI demandera :

• Service – Le service dans lequel l'événement sera créé.
• Module – Le module dans lequel l'événement sera créé (uniquement pour les services modulaires).
• Entité – L'entité dans laquelle l'événement sera créé / associé.
• Type d'événement – Événement de domaine ou événement d'intégration.
• Nom de l'événement – Nom utilisé pour l'événement d'intégration, associé à l'entité.

Exemple

En créant l'événement d'intégration UserCreated associé à l'entité User, le système crée automatiquement un événement nommé UserCreatedIntegrationEvent. Ce nom indique clairement à toute partie du système consommant l'événement que l'action de création de l'utilisateur a déjà été effectuée.

Structure générée par Lino :

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

Reliable publication

An integration event implements IIntegrationEvent and crosses boundaries between modules, services, or systems. The application registers the event in IOutbox, the Unit of Work persists an OutboxMessage, and a Hangfire worker later publishes it through MassTransit/RabbitMQ.

Gestionnaires d'Événements d'Intégration

Un Integration Event Handler est une classe responsable de consommer un Événement d'Intégration, généralement publié par un autre service ou contexte, puis d'exécuter des actions spécifiques dans son propre domaine.

Ces handlers reçoivent les événements via des mécanismes de messagerie (comme RabbitMQ, Kafka, Azure Service Bus, etc.), généralement en combinaison avec le pattern Outbox, qui garantit une livraison fiable et un traitement asynchrone.

Par exemple, lorsqu'un événement UserCreated est publié par un service d'Identité, le handler correspondant dans un autre contexte peut réagir en envoyant un e-mail de bienvenue ou en appelant des APIs externes. Ces opérations peuvent être plus lentes ou sujettes à des erreurs, mais comme elles sont traitées en dehors de la transaction principale, elles ne compromettent pas la cohérence interne de l'application.

Caractéristiques principales :

• Réagit aux événements représentant des faits métier pertinents pour d'autres contextes.
• Exécute des opérations pouvant être lentes ou externes (ex. : envoi d'e-mails, appels à des APIs).
• Est traité de manière asynchrone et résiliente, souvent avec des tentatives de reprise et de la surveillance.
• Garantit que les échecs externes n'affectent pas la transaction d'origine du domaine.
• Facilite l'intégration entre les bounded contexts et les systèmes distribués.

Pour créer un nouveau gestionnaire d'événements d'intégration, il suffit d'exécuter la commande :

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>

L'assistant CLI demandera :

• Service – Le service dans lequel le gestionnaire d'événements sera créé.
• Module – Le module dans lequel le gestionnaire d'événements sera créé (uniquement pour les services modulaires).
• Entité – L'entité dans laquelle le gestionnaire d'événements sera créé.
• Type d'événement – Événement de domaine ou événement d'intégration.
• Service – Le service dans lequel existe l'événement à consommer.
• Module – Le module dans lequel existe l'événement à consommer (uniquement pour les services modulaires).
• Entité – L'entité dans laquelle existe l'événement à consommer.
• Événement – L'événement qui sera consommé.
• Nom du gestionnaire d'événement – Nom utilisé qui sera associé à l'entité et à l'événement d'intégration.

Exemple

En créant le gestionnaire d'événement d'intégration SendEmailOnUserCreated associé à l'entité User et à l'événement UserCreatedIntegrationEvent, le système crée automatiquement un gestionnaire d'événement nommé SendEmailOnUserCreatedIntegrationEventHandler.

Structure générée par Lino :

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

Operational guidance

• Implements IIntegrationEventHandler and consumes messages with MassTransit.
• Does not read the producer database directly.
• Updates local state, projections, or shadow entities.
• Should be idempotent because retries and duplicate messages can happen.

Shadow Entities

Une shadow entity est une copie locale, minimale et contrôlée de données dont le propriétaire se trouve dans un autre module ou service. Elle existe pour réduire le couplage lorsque le consommateur doit consulter, valider ou afficher des données de référence sans accéder directement à la base de données du producteur.

Les Shadow Entities sont utiles lorsque la cohérence éventuelle est acceptable. Le producteur publie un événement d'intégration, le message est persisté dans l'Outbox, le worker le publie sur le bus et le consommateur met à jour sa copie locale au moyen d'un integration event handler.

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

La commande est aussi accessible avec l'alias lino shadow new. Dans le flux interactif, Lino demande le service ou module cible, l'entité source et les propriétés à copier. Cela évite de recréer manuellement le type d'identifiant, le caractère obligatoire, la longueur des strings et les références de base, ce qui réduit les incohérences entre source et consommateur.

La shadow entity n'est pas une réplique complète. Dans l'exemple d'un module Catalog consommant des données de Tenancy et Security, le catalogue peut ne conserver que Tenant.Id, Tenant.Slug, User.Id, User.Email et User.TenantId. L'entité utilisateur originale contient toujours hash, confirmation, tokens, dates et autres champs internes qui n'appartiennent pas au contexte du catalogue.

Quand l'utiliser

• Lorsque le consommateur a besoin de quelques champs d'une entité appartenant à un autre contexte.
• Lorsque la règle accepte un léger délai entre le changement chez le producteur et la mise à jour chez le consommateur.
• Lorsqu'une lecture directe de la base du producteur créerait un couplage inapproprié entre modules ou services.
• Lorsque des grids, filtres, validations locales ou projections ont besoin de données de référence externes.

Quand l'éviter

• Lorsque la règle exige une donnée mise à jour immédiatement et n'accepte pas la cohérence éventuelle.
• Lorsque la copie locale deviendrait une réplique complète de l'aggregate original.
• Lorsque le consommateur commence à dépendre d'invariants qui appartiennent au producteur.

Flux recommandé

1. Modélisez la shadow entity avec uniquement les champs nécessaires au consommateur.
2. Créez ou sélectionnez l'integration event publié par le producteur.
3. Créez un integration event handler dans le consommateur.
4. Implémentez un upsert idempotent avec la clé du producteur ou un identifiant naturel.
5. Ajoutez assez de logs pour diagnostiquer retries, messages dupliqués et échecs permanents.

Synchronisation Orientée Événements

Le flux complet combine domaine, application, Unit of Work, Outbox, worker, bus et consommateur. L'objectif est d'éviter les appels directs fragiles entre modules ou services et de permettre retry, audit et retraitement lorsque la publication ou la consommation échoue.

1. Un aggregate change et enregistre un événement de domaine.
2. La Unit of Work enregistre le changement dans une transaction.
3. Un domain handler réagit au fait et enregistre un événement d'intégration dans IOutbox.
4. La Unit of Work persiste les données métier et OutboxMessage dans la même transaction.
5. Un worker Hangfire lit l'Outbox et publie sur le bus via MassTransit/RabbitMQ.
6. Le consommateur reçoit le message via un IIntegrationEventHandler.
7. Le consommateur met à jour son modèle local, shadow entity, projection, e-mail, intégration externe ou autre flux asynchrone.

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

Règles de conception

• Placez les invariants dans le domaine; utilisez les événements pour les réactions, pas pour cacher des règles obligatoires.
• Enregistrez les integration events dans la même transaction que le changement métier.
• Gardez les contrats d'intégration petits, versionnables et stables.
• Implémentez des consumers idempotents, car retries et messages dupliqués peuvent se produire.
• Surveillez les échecs de worker et les messages bloqués dans l'Outbox.