Microservices Architecture with .NET

public enum FulfillmentState { AwaitingStock, AwaitingPayment, Completed, Cancelled }

// Orchestrated saga for one order. It is persisted between messages, keyed by OrderId,
// with a concurrency token; each handler runs in a transaction that also writes the
// returned commands to the outbox.
public sealed class OrderFulfillmentSaga
{
    public Guid OrderId { get; private set; }
    public decimal Amount { get; private set; }
    public FulfillmentState State { get; private set; } = FulfillmentState.AwaitingStock;

    public object[] Handle(StockReserved e)
    {
        State = FulfillmentState.AwaitingPayment;
        return [new ChargePayment(OrderId, Amount)];
    }

    public object[] Handle(StockRejected e)
    {
        State = FulfillmentState.Cancelled;
        return [new CancelOrder(OrderId, "Out of stock")];
    }

    public object[] Handle(PaymentSucceeded e) // the pivot: after this, move forward only
    {
        State = FulfillmentState.Completed;
        return [new ConfirmOrder(OrderId)];
    }

    public object[] Handle(PaymentFailed e) // compensate the steps that already succeeded
    {
        State = FulfillmentState.Cancelled;
        return [new ReleaseStock(OrderId), new CancelOrder(OrderId, "Payment failed")];
    }
}

public sealed class OutboxMessage
{
    public Guid Id { get; init; } = Guid.CreateVersion7();
    public required string Type { get; init; }
    public required string Payload { get; init; }
    public DateTimeOffset OccurredAt { get; init; }
    public DateTimeOffset? PublishedAt { get; set; }
}

// In the command handler: the order and its event commit atomically.
db.Orders.Add(order);
db.Outbox.Add(new OutboxMessage
{
    Type = nameof(OrderPlacedIntegrationEvent),
    Payload = JsonSerializer.Serialize(new OrderPlacedIntegrationEvent(order.Id, order.Total)),
    OccurredAt = clock.GetUtcNow()
});
await db.SaveChangesAsync(ct);

// The relay publishes pending messages at least once.
public sealed class OutboxRelay(IServiceScopeFactory scopes, IMessagePublisher publisher,
    ILogger<OutboxRelay> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        using var timer = new PeriodicTimer(TimeSpan.FromSeconds(2));
        while (await timer.WaitForNextTickAsync(stoppingToken))
        {
            try
            {
                await PublishPendingAsync(stoppingToken);
            }
            catch (Exception ex) when (ex is not OperationCanceledException)
            {
                logger.LogError(ex, "Outbox relay failed; retrying on the next tick.");
            }
        }
    }

    private async Task PublishPendingAsync(CancellationToken ct)
    {
        await using var scope = scopes.CreateAsyncScope();
        var db = scope.ServiceProvider.GetRequiredService<OrderingDbContext>();
        var pending = await db.Outbox
            .Where(m => m.PublishedAt == null)
            .OrderBy(m => m.OccurredAt)
            .Take(100)
            .ToListAsync(ct);

        foreach (var message in pending)
        {
            // The message ID travels with the message so consumers can deduplicate.
            await publisher.PublishAsync(message.Type, message.Payload, message.Id, ct);
            message.PublishedAt = DateTimeOffset.UtcNow;
            await db.SaveChangesAsync(ct);
        }
    }
}