klod68/domain-event-dispatch

---

name: domain-event-dispatch description: "Use when raising and handling domain events within a bounded context, decoupling domain logic from side-effect infrastructure (notifications, audit, read-model projections), or when multiple independent reactions to the same domain change are directly calling services from the entity or use case handler. Covers in-process dispatch via MediatR INotification, a manual IDomainEventDispatcher with IServiceProvider, and EF Core SaveChanges integration to dispatch events after the transaction commits. Domain: Domain-Driven Design, Architecture. Level: Intermediate. Tags: domain-events, ddd, mediatr, event-dispatch, decoupling."

Domain Event Dispatch

Problem

When a domain operation occurs (order placed, user registered, inventory depleted), other parts of the system need to react: send a notification, update a read model, trigger a workflow. Directly calling those side-effect services from the domain entity or use case handler violates SRP and creates tight coupling.

Solution: In-Process Domain Events

Domain entities raise events. A dispatcher (MediatR or custom) publishes them to handlers. All handlers execute within the same transaction boundary.

Domain Event Base

/// <summary>Marker interface for domain events.</summary>
public interface IDomainEvent
{
    DateTime OccurredAtUtc { get; }
}

public abstract record DomainEventBase : IDomainEvent
{
    public DateTime OccurredAtUtc { get; init; } = DateTime.UtcNow;
}

Entity Raises Events

public abstract class Entity
{
    private readonly List<IDomainEvent> _domainEvents = [];

    public IReadOnlyList<IDomainEvent> DomainEvents => _domainEvents.AsReadOnly();

    protected void Raise(IDomainEvent domainEvent)
    {
        ArgumentNullException.ThrowIfNull(domainEvent);
        _domainEvents.Add(domainEvent);
    }

    public void ClearDomainEvents() => _domainEvents.Clear();
}

Concrete Event

public sealed record OrderPlaced(Guid OrderId, decimal Total) : DomainEventBase;

Raising from Entity

public class Order : Entity
{
    public void Place()
    {
        Status = OrderStatus.Placed;
        Raise(new OrderPlaced(Id, Total));
    }
}

Dispatch: Option A — MediatR

// Event inherits INotification:
public sealed record OrderPlaced(Guid OrderId, decimal Total)
    : DomainEventBase, INotification;

// Handler:
internal sealed class SendOrderConfirmation : INotificationHandler<OrderPlaced>
{
    public async Task Handle(OrderPlaced notification, CancellationToken ct)
    {
        // Send email, push notification, etc.
    }
}

Dispatch: Option B — Manual Dispatcher

public interface IDomainEventDispatcher
{
    Task DispatchAsync(IEnumerable<IDomainEvent> events, CancellationToken ct);
}

internal sealed class DomainEventDispatcher : IDomainEventDispatcher
{
    private readonly IServiceProvider _serviceProvider;

    public DomainEventDispatcher(IServiceProvider serviceProvider)
    {
        ArgumentNullException.ThrowIfNull(serviceProvider);
        _serviceProvider = serviceProvider;
    }

    public async Task DispatchAsync(IEnumerable<IDomainEvent> events, CancellationToken ct)
    {
        foreach (var domainEvent in events)
        {
            var handlerType = typeof(IDomainEventHandler<>).MakeGenericType(domainEvent.GetType());
            var handlers = _serviceProvider.GetServices(handlerType);

            foreach (var handler in handlers)
            {
                await ((dynamic)handler!).HandleAsync((dynamic)domainEvent, ct);
            }
        }
    }
}

public interface IDomainEventHandler<in TEvent> where TEvent : IDomainEvent
{
    Task HandleAsync(TEvent domainEvent, CancellationToken ct);
}

EF Core Integration: Dispatch on SaveChanges

public override async Task<int> SaveChangesAsync(CancellationToken ct = default)
{
    var entities = ChangeTracker.Entries<Entity>()
        .Where(e => e.Entity.DomainEvents.Count > 0)
        .Select(e => e.Entity)
        .ToList();

    var events = entities.SelectMany(e => e.DomainEvents).ToList();
    entities.ForEach(e => e.ClearDomainEvents());

    var result = await base.SaveChangesAsync(ct);

    // Dispatch AFTER save — ensures the data is committed
    await _dispatcher.DispatchAsync(events, ct);

    return result;
}

When to Use

• Side effects of domain operations (notifications, audit, projections)
• Decoupling domain logic from infrastructure concerns
• Multiple independent reactions to the same domain change

When NOT to Use

• Cross-service communication (use outbox pattern + message broker instead)
• Events that must survive process crashes (use outbox or event sourcing)
• Simple CRUD without domain logic (events add unnecessary complexity)

Gotchas

1. Transaction boundary: Events dispatched in SaveChangesAsync run in the same transaction. If a handler fails, the entire transaction rolls back. Design handlers to be idempotent or move them after commit.
2. Ordering: Handlers execute sequentially by default in MediatR. Do not rely on handler execution order.
3. No cross-service: Domain events are in-process only. For cross-service events, raise a domain event that writes to the outbox.
4. Event immutability: Events are facts — never modify them after raising. Use record types.

Related Skills

• Outbox Pattern (for cross-service event publishing)
• Background Hosted Service (async event processing)
• CQRS Handler (commands raise events, queries read projections)