Messaging patterns: queues, pub/sub, outbox, sagas
Synchronous HTTP calls couple services in time: the caller waits, and if the callee is down the caller fails too. Messaging removes that coupling. The sender puts a message on a broker and moves on; the receiver processes it when it can, even if it was offline when the message was sent. The broker absorbs load spikes (load leveling), lets you add consumers without touching the producer, and retries work that fails.
That freedom has a price: delivery is usually at least once, so consumers see duplicates; order is guaranteed only within a queue, partition or session; and a business process that spans several services can no longer use one database transaction. This page covers the patterns that deal with those facts, using an invented OrdersPortal order flow.
The C# samples marked as run are .NET 10 file-based programs (dotnet run file.cs) that simulate the broker in memory with System.Threading.Channels, so they need no infrastructure; they were run with .NET SDK 10.0.115. The Azure Service Bus sample was compiled but not run, because it needs a real namespace.
Topics on this page
Section titled “Topics on this page”| Pattern | Use it for |
|---|---|
| Queues and topics | Work distribution with competing consumers, fan-out to many subscribers, request and reply, retries and dead-letter queues. |
| Transactional outbox | Publishing a message if and only if the database change commits. |
| Sagas | Business processes across several services, with compensation instead of rollback. |
| Brokers and libraries | Choosing Azure Service Bus, RabbitMQ or Kafka, and a .NET client library. |
Queues and topics
Section titled “Queues and topics”A queue is point-to-point: each message is delivered to exactly one consumer. Several instances of the same consumer can read the same queue (competing consumers), which spreads work and lets you scale by adding instances; use it for commands such as ResizeImage or GenerateInvoice. A topic is publish/subscribe: each subscription gets its own copy of every message, so email, inventory and analytics each receive OrderPlaced and progress independently. Use topics for events. Request/reply sends a request with a ReplyTo address and a correlation ID and receives the answer asynchronously on a reply queue; use it sparingly, since it reintroduces waiting.
Brokers redeliver a message whose processing fails or times out. After a maximum number of deliveries (10 by default in Azure Service Bus) the message moves to a dead-letter queue (DLQ), so one poison message cannot block the rest. A consumer can also dead-letter a message immediately when retrying cannot help, such as an invalid payload. Someone must watch the DLQ: alert on its size, inspect the reason, fix the cause and resubmit.
using System.Threading.Channels;
// Point-to-point queue with competing consumers, retries and a dead-letter queue.var queue = Channel.CreateUnbounded<Envelope<ResizeImage>>();var deadLetters = new List<Envelope<ResizeImage>>();const int MaxDeliveries = 3;
foreach (var id in new[] { "p1.jpg", "p2.jpg", "corrupt.jpg", "p3.jpg" }) await queue.Writer.WriteAsync(new(new ResizeImage(id)));queue.Writer.Complete();
var log = new List<string>();async Task Worker(string name){ await foreach (var envelope in queue.Reader.ReadAllAsync()) { for (envelope.DeliveryCount = 1; ; envelope.DeliveryCount++) { try { Resize(envelope.Message); lock (log) log.Add($"{envelope.Message.File}: done"); break; } catch (InvalidDataException) when (envelope.DeliveryCount < MaxDeliveries) { /* redeliver */ } catch (InvalidDataException) { lock (deadLetters) deadLetters.Add(envelope); break; } } }}await Task.WhenAll(Worker("worker-1"), Worker("worker-2")); // each message goes to exactly one workerforeach (var line in log.Order()) Console.WriteLine(line);Console.WriteLine($"Dead-lettered: {string.Join(", ", deadLetters.Select(d => $"{d.Message.File} after {d.DeliveryCount} deliveries"))}");
// Publish/subscribe: every subscription gets its own copy of each event.var subscriptions = new Dictionary<string, Channel<OrderPlaced>>{ ["email"] = Channel.CreateUnbounded<OrderPlaced>(), ["inventory"] = Channel.CreateUnbounded<OrderPlaced>(), ["analytics"] = Channel.CreateUnbounded<OrderPlaced>(),};var placed = new OrderPlaced(1001, 128.48m);foreach (var sub in subscriptions.Values) await sub.Writer.WriteAsync(placed); // the topic fans outforeach (var (name, sub) in subscriptions) Console.WriteLine($"{name} received order {(await sub.Reader.ReadAsync()).OrderId}");
static void Resize(ResizeImage m){ if (m.File.StartsWith("corrupt")) throw new InvalidDataException("not an image");}
public sealed record ResizeImage(string File);public sealed record OrderPlaced(int OrderId, decimal Total);public sealed class Envelope<T>(T message){ public T Message { get; } = message; public int DeliveryCount { get; set; }}Output:
p1.jpg: donep2.jpg: donep3.jpg: doneDead-lettered: corrupt.jpg after 3 deliveriesemail received order 1001inventory received order 1001analytics received order 1001The same flow on Azure Service Bus, with a stable MessageId for duplicate detection and explicit settlement (compiled with Azure.Messaging.ServiceBus 7.21.0, not run):
#:package Azure.Messaging.ServiceBus@7.21.0#:package Azure.Identity@1.21.0#:property PublishAot=falseusing System.Text.Json;using Azure.Identity;using Azure.Messaging.ServiceBus;
await using var client = new ServiceBusClient("ordersportal.servicebus.windows.net", new DefaultAzureCredential());
// Publish to a topic; every subscription (email, inventory, analytics) gets a copy.await using var sender = client.CreateSender("order-events");var message = new ServiceBusMessage(JsonSerializer.Serialize(new OrderPlaced(1001, 128.48m))){ MessageId = "order-1001-placed", // stable ID: enables duplicate detection and idempotent consumers Subject = nameof(OrderPlaced), CorrelationId = "checkout-7f3a",};await sender.SendMessageAsync(message);
// Consume one subscription with explicit settlement.await using var processor = client.CreateProcessor("order-events", "inventory", new ServiceBusProcessorOptions { AutoCompleteMessages = false, MaxConcurrentCalls = 4 });
processor.ProcessMessageAsync += async args =>{ var placed = args.Message.Body.ToObjectFromJson<OrderPlaced>(); if (placed is null || placed.Total <= 0) { // Poison message: retrying will never help, so dead-letter it with a reason. await args.DeadLetterMessageAsync(args.Message, "InvalidPayload", "Total must be positive"); return; } // ... reserve stock, idempotently, keyed on args.Message.MessageId ... await args.CompleteMessageAsync(args.Message);};processor.ProcessErrorAsync += args => { Console.Error.WriteLine(args.Exception.Message); return Task.CompletedTask; };await processor.StartProcessingAsync();
public sealed record OrderPlaced(int OrderId, decimal Total);Pitfalls:
- Commands on topics, events on queues. A command has one owner and belongs on a queue; an event may have many listeners and belongs on a topic. Mixing them couples producers to consumers.
- Retrying poison messages forever. Without a delivery limit and a DLQ, one bad message is retried endlessly and blocks a session or partition.
- Large payloads. Brokers cap message size (256 KB on the Service Bus Standard tier). Send a reference to blob storage instead (the claim check pattern).
Transactional outbox
Section titled “Transactional outbox”A service that saves an order and then publishes OrderPlaced performs two writes to two systems. If the process crashes between them, the order exists but nobody hears about it; if it publishes first and the database transaction fails, consumers act on an order that never existed. Distributed transactions across a database and a broker are not available or not practical in the cloud.
The transactional outbox solves this: in the same database transaction as the business change, insert the message into an outbox table. A relay (a background service, a change-data-capture feed, or the messaging library) reads unsent rows, publishes them and marks them sent. Because the relay can crash after publishing but before marking the row, a message can be published twice, so consumers must be idempotent: record processed message IDs (the inbox pattern) or make the handler naturally idempotent. A runnable version, including a simulated relay crash and duplicate suppression, is on architecture patterns: event-driven architecture.
Messaging libraries implement both halves for you. With MassTransit and EF Core, for example (fragment, not run):
builder.Services.AddDbContext<OrdersDbContext>(o => o.UseSqlServer(connectionString));builder.Services.AddMassTransit(x =>{ x.AddEntityFrameworkOutbox<OrdersDbContext>(o => { o.UseSqlServer(); // outbox and inbox tables live in the orders database o.UseBusOutbox(); // Publish/Send inside a request are stored, then delivered after SaveChanges }); x.UsingAzureServiceBus((context, cfg) => cfg.ConfigureEndpoints(context));});
// In the use case: both changes commit together or not at all.db.Orders.Add(order);await publishEndpoint.Publish(new OrderPlaced(order.Id, order.Total));await db.SaveChangesAsync();Pitfalls:
- Publishing before committing. Calling the broker directly inside the transaction scope still loses or invents events on failure; only the outbox makes the two writes atomic.
- Unbounded outbox tables. Delete or archive sent rows on a schedule, and index the “unsent” column the relay polls.
- Assuming the outbox gives exactly-once. It gives at-least-once; idempotent consumers are still required.
A saga runs a business process across several services as a sequence of local transactions. Each step commits in its own service and publishes an event or reply; if a later step fails, the saga runs compensating actions for the steps that already completed (release reserved stock, refund a payment). Compensation is a business operation, not a rollback: a refund is a new transaction, and the customer may have seen the charge.
In choreography, there is no coordinator: each service listens for events and emits its own (OrderPlaced → inventory reserves → StockReserved → payment charges…). It is simple for two or three steps but hard to follow, change or monitor as it grows. In orchestration, a saga orchestrator (a state machine with persisted state) sends commands to each service, waits for replies and decides the next step or compensation; the process is visible in one place. MassTransit state machines, NServiceBus sagas, Azure Durable Functions and Temporal are common orchestrators.
// An orchestrated saga: each step is a local transaction in another service,// and each completed step has a compensating action used if a later step fails.var inventory = new InventoryService();var payments = new PaymentService(declineAbove: 500m);var shipping = new ShippingService();
foreach (var order in new[] { new OrderRequest(1001, "KB-101", 2, 99.98m), new OrderRequest(1002, "TV-900", 1, 899.00m) }){ var saga = new PlaceOrderSaga(inventory, payments, shipping); var state = await saga.RunAsync(order); Console.WriteLine($"order {order.OrderId}: {state} (stock KB-101={inventory.Stock["KB-101"]}, TV-900={inventory.Stock["TV-900"]})");}
public sealed record OrderRequest(int OrderId, string Sku, int Quantity, decimal Amount);public enum SagaState { Started, StockReserved, PaymentCaptured, Completed, Compensated }
public sealed class PlaceOrderSaga(InventoryService inventory, PaymentService payments, ShippingService shipping){ private readonly Stack<(string Name, Func<Task> Undo)> _compensations = new(); public SagaState State { get; private set; } = SagaState.Started; // persisted in a real saga
public async Task<SagaState> RunAsync(OrderRequest o) { try { await inventory.ReserveAsync(o.OrderId, o.Sku, o.Quantity); _compensations.Push(("release stock", () => inventory.ReleaseAsync(o.OrderId, o.Sku, o.Quantity))); State = SagaState.StockReserved;
await payments.CaptureAsync(o.OrderId, o.Amount); _compensations.Push(("refund payment", () => payments.RefundAsync(o.OrderId))); State = SagaState.PaymentCaptured;
await shipping.ScheduleAsync(o.OrderId); return State = SagaState.Completed; } catch (StepFailedException ex) { Console.WriteLine($" step failed: {ex.Message}"); while (_compensations.TryPop(out var c)) { Console.WriteLine($" compensate: {c.Name}"); await c.Undo(); } return State = SagaState.Compensated; } }}
public sealed class StepFailedException(string message) : Exception(message);
public sealed class InventoryService{ public Dictionary<string, int> Stock { get; } = new() { ["KB-101"] = 10, ["TV-900"] = 3 }; public Task ReserveAsync(int orderId, string sku, int qty) { Stock[sku] -= qty; return Task.CompletedTask; } public Task ReleaseAsync(int orderId, string sku, int qty) { Stock[sku] += qty; return Task.CompletedTask; }}
public sealed class PaymentService(decimal declineAbove){ public Task CaptureAsync(int orderId, decimal amount) => amount > declineAbove ? throw new StepFailedException($"payment declined for order {orderId}") : Task.CompletedTask; public Task RefundAsync(int orderId) => Task.CompletedTask;}
public sealed class ShippingService{ public Task ScheduleAsync(int orderId) => Task.CompletedTask;}Output:
order 1001: Completed (stock KB-101=8, TV-900=3) step failed: payment declined for order 1002 compensate: release stockorder 1002: Compensated (stock KB-101=8, TV-900=3)The sample keeps saga state in memory to show the control flow. A real orchestrator persists its state after every step and receives replies as messages, so it survives restarts and can wait hours for a slow step.
Pitfalls:
- Non-idempotent steps and compensations. Commands are redelivered; reserving stock twice or refunding twice must be harmless.
- Missing timeouts. A saga that waits forever for a reply never compensates. Schedule a timeout message for each waiting state.
- Steps that cannot be compensated. Sending an email cannot be undone. Order steps so irreversible actions (shipping, notifications) come last, after the risky ones (payment) succeed.
Brokers and libraries
Section titled “Brokers and libraries”| Broker | Model | Strengths | Watch out for |
|---|---|---|---|
| Azure Service Bus | Queues, topics and subscriptions | Managed; sessions for ordered processing, duplicate detection, scheduled messages, built-in DLQ, transactions within a namespace | Message size limits per tier; Azure only |
| RabbitMQ | Exchanges routing to queues | Flexible routing (direct, topic, fanout), self-hosted or managed, quorum queues for durability | You operate it; throughput lower than Kafka at very high volume |
| Apache Kafka (or Azure Event Hubs) | Partitioned, replayable log | Very high throughput, retention and replay, stream processing | Consumers track offsets; order only per partition; no per-message DLQ built in |
For .NET, you can use the broker’s own SDK (Azure.Messaging.ServiceBus, RabbitMQ.Client, Confluent.Kafka) or a messaging library that adds outbox, retries, sagas and a transport-independent API. MassTransit is the most widely used; note its licensing: version 8 is Apache 2.0, while version 9 (current on NuGet in November 2026) is distributed under a commercial license from its publisher, so check the terms before upgrading. NServiceBus is commercial; Wolverine is an open-source alternative.
Choosing between them
Section titled “Choosing between them”| Scenario | Pattern |
|---|---|
| Background job that exactly one worker should do | Queue with competing consumers |
| Notify every interested service that something happened | Topic with one subscription per consumer |
| Publish reliably when the database changes | Transactional outbox plus idempotent consumers |
| Business process across services that may need to be undone | Saga: orchestration for more than two or three steps |
| Messages that must be processed in order per customer or order | Service Bus sessions or Kafka partitions keyed by that ID |
| The caller needs the answer now to continue | Synchronous HTTP or gRPC with resilience, see service communication |
Interview questions
Section titled “Interview questions”What is the difference between a queue and a topic? A queue delivers each message to one consumer, so instances compete for work. A topic delivers a copy to every subscription, so several independent consumers each process every event.
Why do consumers need to be idempotent? Brokers deliver at least once: a consumer can crash after doing the work but before acknowledging, and outbox relays can publish twice. Processing a duplicate must not change the result, for example by recording processed message IDs.
What problem does the transactional outbox solve? The dual-write problem: a database change and a message publish cannot be made atomic directly. Writing the message to an outbox table in the same transaction, then relaying it, guarantees the message is published if and only if the change commits.
Choreography or orchestration for a saga? Choreography for short flows with few participants, because it needs no coordinator. Orchestration once there are more steps, branching or timeouts, because the process, its state and its compensation logic live in one place that can be monitored.
What is a poison message and how do you handle it? A message that fails every time it is processed (invalid data, a bug). Limit deliveries so it moves to a dead-letter queue, dead-letter it immediately when the failure is not transient, alert on DLQ growth, and resubmit after fixing the cause.
Senior scenario: after a deployment, OrdersPortal customers receive two confirmation emails for some orders. How do you investigate and fix it? Duplicates usually come from at-least-once delivery meeting a non-idempotent consumer: a consumer that sends the email and then fails to complete the message (timeout longer than the lock duration, crash during a rolling deployment) or an outbox relay that republished. Check broker metrics for redeliveries and lock-lost errors around the deployment, and trace by correlation ID. Fix by making the email consumer idempotent (store the processed message ID or an “email sent” flag keyed by order in the same transaction as the send record), give messages stable IDs and enable duplicate detection, set the lock duration and graceful shutdown so in-flight messages complete before pods stop.
Related pages
Section titled “Related pages”- Microservices overview
- Microservices communication: gateway, discovery and circuit breakers
- Architecture patterns: CQRS and event-driven architecture
- Structural and behavioral patterns: observer
Official references
Section titled “Official references”- Asynchronous message-based communication, .NET microservices guide
- Azure Service Bus queues, topics and subscriptions
- Service Bus dead-letter queues
- Service Bus duplicate detection
- Saga distributed transactions pattern, Azure Architecture Center
- Compensating Transaction pattern, Azure Architecture Center
- Competing Consumers pattern, Azure Architecture Center
- Claim-Check pattern, Azure Architecture Center