Domain Events — Decouple Side Effects From Your Core Logic

// ❌ Fat handler — tight coupling, hard to test, hard to extend
public async Task Handle(ConfirmOrderCommand cmd, CancellationToken ct)
{
    var order = await _orders.GetByIdAsync(cmd.OrderId, ct);
    order.Confirm();

    // Now what? Email? Stock? Warehouse? Audit?
    await _emailService.SendConfirmationAsync(order.Customer.Email, order);
    await _stockService.ReserveStockAsync(order.Lines, ct);
    await _warehouseService.NotifyAsync(order, ct);
    await _auditService.LogAsync("OrderConfirmed", order.Id, ct);

    await _uow.SaveChangesAsync(ct);
}

// OrderFlow.Domain/Abstractions/IDomainEvent.cs
public interface IDomainEvent : INotification { }

// OrderFlow.Domain/Abstractions/AggregateRoot.cs
public abstract class AggregateRoot
{
    private readonly List<IDomainEvent> _domainEvents = [];

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

    protected void RaiseDomainEvent(IDomainEvent domainEvent) =>
        _domainEvents.Add(domainEvent);

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

// OrderFlow.Domain/Events/OrderConfirmedEvent.cs
public record OrderConfirmedEvent(
    Guid   OrderId,
    Guid   CustomerId,
    string CustomerEmail,
    string OrderNumber,
    decimal Total,
    DateTime ConfirmedAt) : IDomainEvent;

// OrderFlow.Domain/Events/OrderCancelledEvent.cs
public record OrderCancelledEvent(
    Guid   OrderId,
    string OrderNumber,
    string Reason) : IDomainEvent;

// OrderFlow.Domain/Events/StockLevelChangedEvent.cs
public record StockLevelChangedEvent(
    Guid   ProductId,
    string Sku,
    int    OldLevel,
    int    NewLevel) : IDomainEvent;

// OrderFlow.Domain/Entities/Order.cs
public class Order : AggregateRoot
{
    // ... properties ...

    public void Confirm()
    {
        if (Status != OrderStatus.Draft)
            throw new InvalidOperationException($"Order is {Status}, not Draft.");
        if (_lines.Count == 0)
            throw new InvalidOperationException("Cannot confirm an empty order.");

        Status      = OrderStatus.Confirmed;
        ConfirmedAt = DateTime.UtcNow;

        // Raise the event — handlers decide what to do with it
        RaiseDomainEvent(new OrderConfirmedEvent(
            OrderId:       Id,
            CustomerId:    CustomerId,
            CustomerEmail: Customer.Email,
            OrderNumber:   OrderNumber,
            Total:         Total,
            ConfirmedAt:   ConfirmedAt.Value));
    }

    public void Cancel(string reason = "")
    {
        if (Status is OrderStatus.Shipped or OrderStatus.Delivered)
            throw new InvalidOperationException("Cannot cancel a shipped order.");

        Status = OrderStatus.Cancelled;

        RaiseDomainEvent(new OrderCancelledEvent(Id, OrderNumber, reason));
    }
}

// OrderFlow.Infrastructure/Persistence/AppDbContext.cs
public class AppDbContext(
    DbContextOptions<AppDbContext> options,
    IPublisher publisher) : IdentityDbContext<AppUser, IdentityRole<Guid>, Guid>(options), IUnitOfWork
{
    public override async Task<int> SaveChangesAsync(CancellationToken ct = default)
    {
        // 1. Persist to database
        var result = await base.SaveChangesAsync(ct);

        // 2. Collect all raised domain events from tracked aggregates
        var domainEvents = ChangeTracker
            .Entries<AggregateRoot>()
            .SelectMany(e => e.Entity.DomainEvents)
            .ToList();

        // 3. Clear events before dispatching (prevent double-dispatch)
        ChangeTracker
            .Entries<AggregateRoot>()
            .ToList()
            .ForEach(e => e.Entity.ClearDomainEvents());

        // 4. Dispatch — MediatR publishes to all registered INotificationHandler<T>
        foreach (var domainEvent in domainEvents)
            await publisher.Publish(domainEvent, ct);

        return result;
    }
}

// OrderFlow.Application/Orders/Events/SendOrderConfirmationEmailHandler.cs
public class SendOrderConfirmationEmailHandler(
    IEmailService emailService,
    ILogger<SendOrderConfirmationEmailHandler> logger)
    : INotificationHandler<OrderConfirmedEvent>
{
    public async Task Handle(OrderConfirmedEvent notification, CancellationToken ct)
    {
        logger.LogInformation("Sending confirmation email for order {OrderNumber}",
            notification.OrderNumber);

        await emailService.SendAsync(new EmailMessage(
            To:      notification.CustomerEmail,
            Subject: $"Order #{notification.OrderNumber} Confirmed",
            Body:    $"Your order of £{notification.Total:N2} has been confirmed."));
    }
}

// OrderFlow.Application/Orders/Events/ReserveStockOnOrderConfirmedHandler.cs
public class ReserveStockOnOrderConfirmedHandler(
    IOrderRepository   orderRepo,
    IProductRepository productRepo,
    IUnitOfWork        uow,
    ILogger<ReserveStockOnOrderConfirmedHandler> logger)
    : INotificationHandler<OrderConfirmedEvent>
{
    public async Task Handle(OrderConfirmedEvent notification, CancellationToken ct)
    {
        var order = await orderRepo.GetByIdAsync(notification.OrderId, ct);
        if (order is null) return;

        foreach (var line in order.Lines)
        {
            var product = await productRepo.GetByIdAsync(line.ProductId, ct);
            if (product is null)
            {
                logger.LogWarning("Product {ProductId} not found during stock reservation", line.ProductId);
                continue;
            }

            product.AdjustStock(-line.Quantity);   // reduce stock
        }

        await uow.SaveChangesAsync(ct);
    }
}

// OrderFlow.Application/Orders/Events/AuditOrderConfirmedHandler.cs
public class AuditOrderConfirmedHandler(
    IAuditService auditService)
    : INotificationHandler<OrderConfirmedEvent>
{
    public async Task Handle(OrderConfirmedEvent notification, CancellationToken ct) =>
        await auditService.LogAsync(new AuditEntry(
            Event:     "OrderConfirmed",
            EntityId:  notification.OrderId.ToString(),
            UserId:    notification.CustomerId.ToString(),
            OccuredAt: notification.ConfirmedAt));
}

// OrderFlow.Application/Orders/Commands/ConfirmOrderCommandHandler.cs
public class ConfirmOrderCommandHandler(
    IOrderRepository orderRepo,
    IUnitOfWork      uow) : IRequestHandler<ConfirmOrderCommand>
{
    public async Task Handle(ConfirmOrderCommand cmd, CancellationToken ct)
    {
        var order = await orderRepo.GetByIdAsync(cmd.OrderId, ct)
            ?? throw new KeyNotFoundException($"Order {cmd.OrderId} not found.");

        order.Confirm();     // raises OrderConfirmedEvent

        orderRepo.Update(order);
        await uow.SaveChangesAsync(ct);
        // Events are dispatched automatically by AppDbContext.SaveChangesAsync
    }
}

SaveChanges  → ✅ Order.Status = Confirmed
Dispatch event →
  - StockReservation  → ✅ success
  - SendEmail         → ❌ email server down
  - AuditLog          → never reached

// OrderFlow.Domain/Outbox/OutboxMessage.cs
public class OutboxMessage
{
    public Guid     Id          { get; set; } = Guid.NewGuid();
    public string   Type        { get; set; } = default!;   // event type name
    public string   Payload     { get; set; } = default!;   // JSON serialized event
    public DateTime OccurredAt  { get; set; } = DateTime.UtcNow;
    public DateTime? ProcessedAt { get; set; }
    public string?  Error       { get; set; }
    public int      RetryCount  { get; set; }
}

// Updated SaveChangesAsync — writes to outbox instead of dispatching directly
public override async Task<int> SaveChangesAsync(CancellationToken ct = default)
{
    // Collect domain events before saving
    var domainEvents = ChangeTracker
        .Entries<AggregateRoot>()
        .SelectMany(e => e.Entity.DomainEvents)
        .ToList();

    ChangeTracker.Entries<AggregateRoot>()
        .ToList()
        .ForEach(e => e.Entity.ClearDomainEvents());

    // Serialize events to outbox — same transaction as the domain change
    foreach (var domainEvent in domainEvents)
    {
        OutboxMessages.Add(new OutboxMessage
        {
            Type    = domainEvent.GetType().AssemblyQualifiedName!,
            Payload = JsonSerializer.Serialize(domainEvent,
                        domainEvent.GetType(),
                        new JsonSerializerOptions { WriteIndented = false }),
        });
    }

    // Single atomic commit: domain changes + outbox messages
    return await base.SaveChangesAsync(ct);
}

// OrderFlow.Infrastructure/BackgroundJobs/OutboxProcessorWorker.cs
public class OutboxProcessorWorker(
    IServiceScopeFactory scopeFactory,
    ILogger<OutboxProcessorWorker> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            await ProcessBatchAsync(stoppingToken);
            await Task.Delay(TimeSpan.FromSeconds(5), stoppingToken);
        }
    }

    private async Task ProcessBatchAsync(CancellationToken ct)
    {
        using var scope     = scopeFactory.CreateScope();
        var db        = scope.ServiceProvider.GetRequiredService<AppDbContext>();
        var publisher = scope.ServiceProvider.GetRequiredService<IPublisher>();

        var messages = await db.OutboxMessages
            .Where(m => m.ProcessedAt == null && m.RetryCount < 5)
            .OrderBy(m => m.OccurredAt)
            .Take(20)
            .ToListAsync(ct);

        foreach (var message in messages)
        {
            try
            {
                var eventType = Type.GetType(message.Type)!;
                var domainEvent = (IDomainEvent)JsonSerializer.Deserialize(
                    message.Payload, eventType)!;

                await publisher.Publish(domainEvent, ct);

                message.ProcessedAt = DateTime.UtcNow;
            }
            catch (Exception ex)
            {
                logger.LogError(ex, "Failed to process outbox message {Id}", message.Id);
                message.Error      = ex.Message;
                message.RetryCount++;
            }
        }

        await db.SaveChangesAsync(ct);
    }
}

services.AddHostedService<OutboxProcessorWorker>();

Domain Events
✅ Side effects within the same bounded context
✅ Same process, same database
✅ Stock reservation when order confirmed
✅ Audit log entries
✅ Updating read models

Integration Events (Service Bus / RabbitMQ)
✅ Communicating across service boundaries
✅ Notifying a warehouse microservice
✅ Triggering an analytics pipeline
✅ When the handler lives in a different application