Event-Driven Architecture

Event-driven architecture takes the observer idea across a process boundary. Something happens, the component that owns it publishes a fact, and other components react in their own time, in their own processes. Orders announces that an order was approved. Invoicing raises an invoice. Reporting updates a figure. Orders was not told about either of them.

Two properties you had in process are now gone, and almost every difficulty in this lesson comes from losing them. The publisher no longer knows whether a reaction ran, or when, or whether it succeeded. And a message can arrive more than once, because the delivery guarantee every practical broker offers is at-least-once. Design for both from the first handler, not after the first incident.

// The contract. Past tense, versioned, carrying what a subscriber needs.
public sealed record OrderApproved(
    Guid EventId,
    int OrderId,
    string OrderNumber,
    decimal Total,
    string CurrencyCode,
    DateTime ApprovedUtc)
{
    public const string Type = "orders.order-approved.v1";
}

public async Task ApproveAsync(int orderId, string approvedBy, CancellationToken token)
{
    Order order = await db.Orders.SingleAsync(o => o.Id == orderId, token);
    order.Approve(approvedBy, clock.GetUtcNow().UtcDateTime);

    var fact = new OrderApproved(
        Guid.CreateVersion7(), order.Id, order.Number, order.Total, "GBP", order.ApprovedUtc);

    db.OutboxMessages.Add(new OutboxMessage
    {
        Id = fact.EventId,
        Type = OrderApproved.Type,
        Payload = JsonSerializer.Serialize(fact),
        OccurredUtc = fact.ApprovedUtc,
    });

    // One transaction covers the state change and the intent to publish.
    await db.SaveChangesAsync(token);
}

• Saving the order and publishing to a broker are two separate systems, and no transaction spans them. Either can succeed alone. Putting the publish after the save does not fix it: the process can stop in between, and then the order is approved and nobody was told.
• The outbox row is written in the same transaction as the state change, so both land or neither does. A background publisher then reads unsent rows, publishes them, and marks them sent.
• That publisher is where duplicates come from. If it crashes after the broker accepted the message but before the row was marked sent, it will publish the same message again on restart. This is not a flaw to engineer away; it is the reason the receiving side must tolerate repeats.
• Guid.CreateVersion7 produces a time-ordered identifier, which keeps index inserts roughly sequential and makes the event id a sensible deduplication key. On .NET 8 or earlier, generate the identifier however you normally would — what matters is that it is stable across republishes of the same fact.
• The versioned type string is the contract between teams. Subscribers match on it, so publishing orders.order-approved.v2 alongside v1 lets you change the shape without waiting for another team's release.

Between that commit and the last handler finishing, the system is inconsistent in a way a user can see. The order is approved, the invoice does not exist yet, and the dashboard total is the one from before. Usually the window is milliseconds. When a consumer is restarting, or a queue has backed up behind a slow handler, it is minutes.

The expectation this breaks has a name worth knowing: read-your-own-writes. A person clicks approve, the page reloads, and the thing they did is not there. They conclude the click did not work, so they click again. No amount of care inside the handler prevents this, because the cause is the design, not a defect.

So the decision belongs with whoever owns the product, and it has to be made before the code is written. The realistic options are: show the outcome from the command's own response rather than re-reading, show an explicit pending state, or wait for the reaction before responding — which gives back the decoupling you paid for. Engineers picking silently is how a working system becomes a ticket saying the system is broken.

internal sealed class RaiseInvoiceOnOrderApproved(
    AppDbContext db,
    TimeProvider clock,
    ILogger<RaiseInvoiceOnOrderApproved> log) : IConsume<OrderApproved>
{
    private const string Handler = nameof(RaiseInvoiceOnOrderApproved);

    public async Task ConsumeAsync(OrderApproved fact, CancellationToken token)
    {
        bool done = await db.HandledMessages
            .AnyAsync(h => h.EventId == fact.EventId && h.Handler == Handler, token);

        if (done)
        {
            log.LogInformation("Skipping {EventId}: {Handler} already ran.", fact.EventId, Handler);
            return;
        }

        db.Invoices.Add(Invoice.For(fact.OrderId, fact.OrderNumber, fact.Total, fact.CurrencyCode));
        db.HandledMessages.Add(new HandledMessage
        {
            EventId = fact.EventId,
            Handler = Handler,
            HandledUtc = clock.GetUtcNow().UtcDateTime,
        });

        try
        {
            await db.SaveChangesAsync(token);
        }
        catch (DbUpdateException ex) when (IsDuplicateKey(ex))
        {
            // A concurrent delivery got there first. The invoice exists; there is nothing to do.
            log.LogInformation("Duplicate delivery of {EventId} lost the race.", fact.EventId);
        }
    }
}

• Idempotent means running twice leaves the same result as running once. It does not mean the message arrives once — no broker can promise that end to end, whatever its documentation calls the feature.
• The check and both inserts commit together, so a repeat delivery cannot squeeze between deciding and acting.
• The check on its own is not enough, and this is the part that gets missed. Two deliveries can be handled at the same instant on two instances: both queries find nothing, both insert. A unique constraint on EventId plus Handler is what actually makes it safe, and the catch block is the expected path rather than an error path.
• The key includes the handler name because three handlers each need to process the same fact once. Keying on the event id alone means the first handler to finish blocks the other two.
• IsDuplicateKey is a small helper you write, because the exception details are database-specific. Keep it in one place rather than matching error numbers at each call site.
• When the side effect is outside your database — an email, a payment, a file upload — it cannot join the transaction. Then you need the remote system's own idempotency key, which is why the payment port in the adapter lesson carried a Reference.