RabbitMQ in .NET 10: publishing and receiving messages between microservices
When one service needs to tell others that something happened, like an order being placed, an HTTP call is the obvious first choice. It also couples the services together: if the notifications service is down, the order API either fails or has to remember to try again. A message broker removes that coupling. The order API publishes an event, RabbitMQ stores it safely, and every service that cares picks it up in its own time.
This guide builds that with .NET 10 and the official RabbitMQ.Client 7 library, and focuses on the parts tutorials usually skip: what happens when the broker restarts, a consumer crashes mid-message, a message is malformed, or the same message arrives twice.
What we’re building
Two services and a shared library:
- Orders.Api, a minimal API that publishes an
OrderPlacedevent when an order is created. - Notifications.Worker, a worker service that consumes
OrderPlacedand emails the customer. - OrderFlow.Messaging, a small shared library for the connection, topology, publisher and a reusable consumer base class.
- OrderFlow.Contracts, the message types both sides share.
.dlq.OrderFlow/
├── docker-compose.yml
├── src/
│ ├── OrderFlow.Contracts/ OrderPlaced and other message records
│ ├── OrderFlow.Messaging/ connection, topology, publisher, consumer base
│ ├── Orders.Api/ minimal API → publishes OrderPlaced
│ └── Notifications.Worker/ BackgroundService → consumes OrderPlaced
└── tests/
└── OrderFlow.Messaging.Tests/ Testcontainers + a real RabbitMQ
RabbitMQ in two minutes
- Publishers send to an exchange, never directly to a queue, along with a routing key such as
order.placed. - Exchanges route to queues using bindings. A topic exchange matches routing keys against patterns:
order.*matchesorder.placedandorder.cancelled. - Consumers read from queues and acknowledge each message once they’ve handled it. Until then, RabbitMQ keeps it and redelivers it if the consumer disappears.
- Quorum queues replicate messages across nodes and are the recommended queue type for data safety. Use them for anything that matters.
Step 1: Run RabbitMQ locally
# docker-compose.yml
services:
rabbitmq:
image: rabbitmq:4-management
hostname: rabbitmq
ports:
- "5672:5672" # AMQP
- "15672:15672" # management UI: http://localhost:15672
environment:
RABBITMQ_DEFAULT_USER: orderflow
RABBITMQ_DEFAULT_PASS: local-dev-only
RABBITMQ_DEFAULT_VHOST: orderflow
volumes:
- rabbitmq-data:/var/lib/rabbitmq # keep messages across container restarts
volumes:
rabbitmq-data:
docker compose up -d, then open the management UI to watch exchanges, queues and messages as you go. A dedicated virtual host (orderflow) keeps this system’s exchanges and queues separate from anything else on the same broker.
Step 2: Contracts
Messages are the public API between services, so they live in their own small project that both sides reference:
// OrderFlow.Contracts/OrderPlaced.cs
namespace OrderFlow.Contracts;
/// <summary>Published by Orders.Api when an order has been created.</summary>
public sealed record OrderPlaced(Guid OrderId, string CustomerEmail, decimal Total, DateTimeOffset PlacedAt);
Name events in the past tense: they describe something that has already happened, not a request. Treat them like a public API: add optional fields freely, but never rename or remove one that consumers might rely on. For a breaking change, publish a new message type (for example OrderPlacedV2) alongside the old one until every consumer has moved.
Step 3: Configuration
// OrderFlow.Messaging/RabbitMqOptions.cs
public sealed class RabbitMqOptions
{
public const string SectionName = "RabbitMq";
/// <summary>amqp://user:password@host:5672/vhost (use amqps:// for TLS).</summary>
public string Uri { get; set; } = "";
/// <summary>Shows in the management UI, so you can tell services' connections apart.</summary>
public string ClientName { get; set; } = "";
/// <summary>How many unacknowledged messages a consumer may hold at once.</summary>
public ushort PrefetchCount { get; set; } = 20;
}
The URI contains a password, so keep it out of appsettings.json and source control: use dotnet user-secrets locally and environment variables or a secret store in production.
dotnet user-secrets set "RabbitMq:Uri" "amqp://orderflow:local-dev-only@localhost:5672/orderflow"
Step 4: One long-lived connection
Opening a connection is expensive: a TCP connection, a TLS handshake and an AMQP handshake. Create one connection per service and share it. Channels are the cheap, lightweight things you create per publisher or consumer.
// OrderFlow.Messaging/RabbitMqConnection.cs
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;
using RabbitMQ.Client;
public sealed class RabbitMqConnection(IOptions<RabbitMqOptions> options, ILogger<RabbitMqConnection> logger)
: IAsyncDisposable
{
private readonly SemaphoreSlim _lock = new(1, 1);
private IConnection? _connection;
public async Task<IConnection> GetAsync(CancellationToken ct = default)
{
if (_connection is not null) return _connection;
await _lock.WaitAsync(ct);
try
{
if (_connection is not null) return _connection;
var factory = new ConnectionFactory
{
Uri = new Uri(options.Value.Uri),
ClientProvidedName = options.Value.ClientName,
AutomaticRecoveryEnabled = true, // reconnect after a network blip or broker restart
TopologyRecoveryEnabled = true, // and re-create consumers on the new connection
};
_connection = await factory.CreateConnectionAsync(ct);
logger.LogInformation("Connected to RabbitMQ as {ClientName}", options.Value.ClientName);
return _connection;
}
finally
{
_lock.Release();
}
}
public async ValueTask DisposeAsync()
{
if (_connection is not null)
{
await _connection.CloseAsync();
await _connection.DisposeAsync();
}
}
}
Automatic recovery is on by default in the 7.x client, but it’s worth being explicit. Note that it only kicks in after the first successful connection: if the broker isn’t reachable when a service starts, CreateConnectionAsync throws. In containers, either retry at startup or make the service depend on RabbitMQ’s health check.
Step 5: Topology, declared idempotently
Exchanges and queues are declared from code. Declarations are idempotent: declaring something that already exists with the same settings does nothing, so every service can safely declare what it needs on startup. Declaring it with different settings fails with a PRECONDITION_FAILED error, so keep all declarations in one shared place.
// OrderFlow.Messaging/Topology.cs
using RabbitMQ.Client;
public static class Topology
{
public const string EventsExchange = "orderflow.events";
public const string DeadLetterExchange = "orderflow.dead-letter";
public static Task DeclareEventsExchangeAsync(IChannel channel, CancellationToken ct = default) =>
channel.ExchangeDeclareAsync(EventsExchange, ExchangeType.Topic,
durable: true, autoDelete: false, cancellationToken: ct);
/// <summary>
/// A consuming service's own durable quorum queue, bound to the routing keys it cares about,
/// with a dead-letter queue of its own for messages it gives up on.
/// </summary>
public static async Task DeclareConsumerQueueAsync(
IChannel channel, string queue, IEnumerable<string> routingKeys, CancellationToken ct = default)
{
await DeclareEventsExchangeAsync(channel, ct);
await channel.ExchangeDeclareAsync(DeadLetterExchange, ExchangeType.Direct,
durable: true, autoDelete: false, cancellationToken: ct);
var deadLetterQueue = $"{queue}.dlq";
await channel.QueueDeclareAsync(deadLetterQueue, durable: true, exclusive: false, autoDelete: false,
arguments: new Dictionary<string, object?> { ["x-queue-type"] = "quorum" },
cancellationToken: ct);
await channel.QueueBindAsync(deadLetterQueue, DeadLetterExchange, routingKey: queue, cancellationToken: ct);
await channel.QueueDeclareAsync(queue, durable: true, exclusive: false, autoDelete: false,
arguments: new Dictionary<string, object?>
{
["x-queue-type"] = "quorum", // replicated, durable
["x-dead-letter-exchange"] = DeadLetterExchange,
["x-dead-letter-routing-key"] = queue, // lands in exactly this queue's .dlq
["x-delivery-limit"] = 5, // safety net for poison messages
},
cancellationToken: ct);
foreach (var routingKey in routingKeys)
await channel.QueueBindAsync(queue, EventsExchange, routingKey, cancellationToken: ct);
}
}
A few things are doing a lot of work here:
durable: truemeans the exchange and queues survive a broker restart.- Quorum queues replicate across nodes in a cluster. Classic mirrored queues were removed in RabbitMQ 4.0, and quorum queues are now the recommended choice for data safety.
- The dead-letter exchange gives rejected messages somewhere to go instead of disappearing. Pointing the dead-letter routing key at the queue’s own name means each service’s failures end up in that service’s
.dlq, not in one shared pile. x-delivery-limitcaps how many times a message can be redelivered before it’s dead-lettered. That protects you from a message that crashes the consumer every time it’s processed. RabbitMQ 4.3 changed which redeliveries count towards the limit, so check the behaviour for the version you run.
Step 6: A reliable publisher
There are three ways to lose a message on the way in, and three settings that close them off:
| Risk | Fix |
|---|---|
| The broker restarts before the message is written to disk | Persistent messages on durable queues |
| The publish is lost on the network or the broker can’t store it | Publisher confirms: wait for the broker to say “got it” |
| No queue is bound for the routing key, so the exchange silently drops it | mandatory: true: the broker returns unroutable messages |
In RabbitMQ.Client 7, confirms are switched on per channel through CreateChannelOptions. With confirmation tracking enabled as well, awaiting BasicPublishAsync only completes once the broker has confirmed the message, and throws a PublishException if it was rejected or returned as unroutable. Reliability becomes a normal await and try/catch.
// OrderFlow.Messaging/RabbitMqEventPublisher.cs
using System.Text.Json;
using Microsoft.Extensions.Logging;
using RabbitMQ.Client;
public interface IEventPublisher
{
Task PublishAsync<T>(T message, string routingKey,
Guid? messageId = null, string? correlationId = null, CancellationToken ct = default);
}
public sealed class RabbitMqEventPublisher(RabbitMqConnection connection, ILogger<RabbitMqEventPublisher> logger)
: IEventPublisher, IAsyncDisposable
{
private static readonly CreateChannelOptions ConfirmedChannel = new(
publisherConfirmationsEnabled: true,
publisherConfirmationTrackingEnabled: true);
private readonly SemaphoreSlim _lock = new(1, 1);
private IChannel? _channel;
public async Task PublishAsync<T>(T message, string routingKey,
Guid? messageId = null, string? correlationId = null, CancellationToken ct = default)
{
var properties = new BasicProperties
{
Persistent = true, // written to disk
ContentType = "application/json",
MessageId = (messageId ?? Guid.NewGuid()).ToString(), // consumers de-duplicate on this
CorrelationId = correlationId, // ties logs together across services
Type = typeof(T).Name, // e.g. "OrderPlaced"
Timestamp = new AmqpTimestamp(DateTimeOffset.UtcNow.ToUnixTimeSeconds()),
};
var body = JsonSerializer.SerializeToUtf8Bytes(message);
await _lock.WaitAsync(ct);
try
{
var channel = await GetChannelAsync(ct);
// Completes when the broker confirms; throws PublishException if it's nacked or unroutable.
await channel.BasicPublishAsync(Topology.EventsExchange, routingKey, mandatory: true,
basicProperties: properties, body: body, cancellationToken: ct);
}
finally
{
_lock.Release();
}
logger.LogInformation("Published {Type} {MessageId} with routing key {RoutingKey}",
properties.Type, properties.MessageId, routingKey);
}
private async Task<IChannel> GetChannelAsync(CancellationToken ct)
{
if (_channel is { IsOpen: true }) return _channel;
if (_channel is not null) await _channel.DisposeAsync();
var conn = await connection.GetAsync(ct);
_channel = await conn.CreateChannelAsync(ConfirmedChannel, ct);
await Topology.DeclareEventsExchangeAsync(_channel, ct);
return _channel;
}
public async ValueTask DisposeAsync()
{
if (_channel is not null) await _channel.DisposeAsync();
}
}
The publisher keeps one channel and serialises access with a SemaphoreSlim, which is simple and safe. If you need more throughput, keep a small pool of confirmed channels instead.
One consequence of mandatory: true: publishing fails until at least one queue is bound to the routing key. That’s the point, because it turns a silent misconfiguration into an error. It does mean consuming services (or a deployment step) need to declare their queues before the publisher starts sending.
Publishing from the API
// Orders.Api/Program.cs
using OrderFlow.Contracts;
var builder = WebApplication.CreateBuilder(args);
builder.Services.Configure<RabbitMqOptions>(builder.Configuration.GetSection(RabbitMqOptions.SectionName));
builder.Services.AddSingleton<RabbitMqConnection>();
builder.Services.AddSingleton<IEventPublisher, RabbitMqEventPublisher>();
var app = builder.Build();
app.MapPost("/orders", async (PlaceOrder request, IEventPublisher events, HttpContext http, CancellationToken ct) =>
{
var placed = new OrderPlaced(Guid.NewGuid(), request.CustomerEmail, request.Total, DateTimeOffset.UtcNow);
// In a real service, save the order and publish via an outbox (see below).
await events.PublishAsync(placed, "order.placed", correlationId: http.TraceIdentifier, ct: ct);
return Results.Accepted($"/orders/{placed.OrderId}", new { placed.OrderId });
});
app.Run();
public sealed record PlaceOrder(string CustomerEmail, decimal Total);
Step 7: A consumer you can trust
Receiving is where most of the subtlety lives. The rules:
- Acknowledge manually (
autoAck: false), and only after the work is done. With auto-ack, a crash halfway through loses the message. - Set a prefetch count. Without one, RabbitMQ pushes the entire queue at a consumer as fast as it can, and one slow instance hoards messages the others could be processing.
- Retry transient failures, then give up cleanly. After a few attempts,
BasicNackwithrequeue: falsesends the message to the dead-letter queue. Requeueing forever just makes a poison message spin. - Never ack on shutdown. If the service is stopping mid-message, leave it unacknowledged and RabbitMQ will redeliver it.
Rather than repeat all that in every service, it goes in a base class:
// OrderFlow.Messaging/RabbitMqConsumer.cs
using System.Text.Json;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;
using RabbitMQ.Client;
using RabbitMQ.Client.Events;
public sealed record MessageContext(string MessageId, string? CorrelationId, bool Redelivered);
public abstract class RabbitMqConsumer<T>(
RabbitMqConnection connection,
IOptions<RabbitMqOptions> options,
ILogger logger) : BackgroundService
{
private const int MaxAttempts = 3;
private IChannel? _channel;
protected abstract string QueueName { get; }
protected abstract string[] RoutingKeys { get; }
protected abstract Task HandleAsync(T message, MessageContext context, CancellationToken ct);
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
var conn = await connection.GetAsync(stoppingToken);
_channel = await conn.CreateChannelAsync(cancellationToken: stoppingToken);
await Topology.DeclareConsumerQueueAsync(_channel, QueueName, RoutingKeys, stoppingToken);
await _channel.BasicQosAsync(prefetchSize: 0, prefetchCount: options.Value.PrefetchCount,
global: false, cancellationToken: stoppingToken);
var consumer = new AsyncEventingBasicConsumer(_channel);
consumer.ReceivedAsync += (_, delivery) => OnReceivedAsync(delivery, stoppingToken);
await _channel.BasicConsumeAsync(QueueName, autoAck: false, consumer: consumer,
cancellationToken: stoppingToken);
logger.LogInformation("Consuming {Queue}", QueueName);
try { await Task.Delay(Timeout.Infinite, stoppingToken); }
catch (OperationCanceledException) { /* shutting down */ }
}
private async Task OnReceivedAsync(BasicDeliverEventArgs delivery, CancellationToken stoppingToken)
{
var props = delivery.BasicProperties;
// The body's memory is only valid inside this handler, so deserialise it here.
T? message = default;
try { message = JsonSerializer.Deserialize<T>(delivery.Body.Span); }
catch (JsonException ex) { logger.LogError(ex, "Malformed message on {Queue}", QueueName); }
if (message is null || props.MessageId is null)
{
// Retrying won't fix a bad message: dead-letter it straight away.
await _channel!.BasicNackAsync(delivery.DeliveryTag, multiple: false, requeue: false);
return;
}
var context = new MessageContext(props.MessageId, props.CorrelationId, delivery.Redelivered);
using var scope = logger.BeginScope(new Dictionary<string, object?>
{
["MessageId"] = context.MessageId,
["CorrelationId"] = context.CorrelationId,
});
for (var attempt = 1; ; attempt++)
{
try
{
await HandleAsync(message, context, stoppingToken);
await _channel!.BasicAckAsync(delivery.DeliveryTag, multiple: false);
return;
}
catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
{
return; // shutting down: leave it unacked so the broker redelivers it
}
catch (Exception ex) when (attempt < MaxAttempts)
{
logger.LogWarning(ex, "Handling failed on attempt {Attempt}; retrying", attempt);
}
catch (Exception ex)
{
logger.LogError(ex, "Handling failed {Attempts} times; dead-lettering", attempt);
await _channel!.BasicNackAsync(delivery.DeliveryTag, multiple: false, requeue: false);
return;
}
try { await Task.Delay(TimeSpan.FromSeconds(Math.Pow(2, attempt)), stoppingToken); } // 2s, 4s
catch (OperationCanceledException) { return; }
}
}
public override async Task StopAsync(CancellationToken ct)
{
await base.StopAsync(ct); // cancels stoppingToken
if (_channel is not null)
{
await _channel.CloseAsync(ct);
await _channel.DisposeAsync();
}
}
}
By default the 7.x client runs one handler at a time per channel, so the prefetch count acts as a buffer of messages waiting their turn. To process several messages from one queue in parallel, pass consumerDispatchConcurrency in CreateChannelOptions. Your handler then has to be safe to run concurrently.
Step 8: Idempotent handlers
RabbitMQ guarantees at-least-once delivery, not exactly-once. A consumer can finish its work and then crash before its acknowledgement reaches the broker, and the message is delivered again. So every handler must be safe to run twice for the same message. That’s why the publisher stamps every message with a MessageId.
The usual pattern is an inbox: record each processed MessageId and skip ones you’ve seen before.
// Notifications.Worker/OrderPlacedConsumer.cs
using Microsoft.Extensions.Options;
using OrderFlow.Contracts;
public sealed class OrderPlacedConsumer(
RabbitMqConnection connection,
IOptions<RabbitMqOptions> options,
IServiceScopeFactory scopes,
ILogger<OrderPlacedConsumer> logger)
: RabbitMqConsumer<OrderPlaced>(connection, options, logger)
{
protected override string QueueName => "notifications.order-placed";
protected override string[] RoutingKeys => ["order.placed"];
protected override async Task HandleAsync(OrderPlaced message, MessageContext context, CancellationToken ct)
{
await using var scope = scopes.CreateAsyncScope();
var inbox = scope.ServiceProvider.GetRequiredService<IInbox>();
var email = scope.ServiceProvider.GetRequiredService<IEmailSender>();
if (await inbox.HasProcessedAsync(context.MessageId, ct))
return; // a redelivery of something we've already handled
await email.SendOrderConfirmationAsync(message.CustomerEmail, message.OrderId, ct);
await inbox.MarkProcessedAsync(context.MessageId, ct);
}
}
Each message is handled in its own DI scope, so scoped services such as a DbContext aren’t shared between messages. When the handler writes to a database, do the work and the inbox insert in the same transaction, with a unique key on MessageId. Then a duplicate either does nothing or fails cleanly. For side effects you can’t roll back, like sending an email, a duplicate is still possible if the service crashes between sending and recording it. That’s usually acceptable; if it isn’t, the receiving system needs its own idempotency key.
// Notifications.Worker/Program.cs
var builder = Host.CreateApplicationBuilder(args);
builder.Services.Configure<RabbitMqOptions>(builder.Configuration.GetSection(RabbitMqOptions.SectionName));
builder.Services.AddSingleton<RabbitMqConnection>();
builder.Services.AddSingleton<IInbox, InMemoryInbox>(); // use a database table in production
builder.Services.AddScoped<IEmailSender, LoggingEmailSender>();
builder.Services.AddHostedService<OrderPlacedConsumer>();
builder.Build().Run();
Step 9: The outbox pattern
The API above has a subtle bug that every event-driven system has to solve: saving to the database and publishing to RabbitMQ are two separate operations. If the order is saved and the publish fails, the event is lost. Publish first and the save fails, and you’ve announced an order that doesn’t exist.
The transactional outbox fixes this. Instead of publishing directly, the API writes the event to an OutboxMessages table in the same database transaction as the order. A background dispatcher then publishes anything unsent and marks it sent once RabbitMQ confirms.
// In the endpoint: one transaction for the order and its event
db.Orders.Add(order);
db.OutboxMessages.Add(new OutboxMessage
{
Id = Guid.NewGuid(), // becomes the RabbitMQ MessageId
Type = nameof(OrderPlaced),
RoutingKey = "order.placed",
Payload = JsonSerializer.Serialize(placed),
CreatedUtc = DateTime.UtcNow,
});
await db.SaveChangesAsync(ct); // both rows, or neither
// The dispatcher's loop (sketch): publish unsent messages, mark them sent once confirmed
while (!stoppingToken.IsCancellationRequested)
{
await using var scope = scopes.CreateAsyncScope();
var db = scope.ServiceProvider.GetRequiredService<OrdersDbContext>();
var pending = await db.OutboxMessages
.Where(m => m.SentUtc == null)
.OrderBy(m => m.CreatedUtc)
.Take(50)
.ToListAsync(stoppingToken);
foreach (var message in pending)
{
// An overload of the publisher that takes the stored JSON and the outbox Id as the MessageId.
await publisher.PublishRawAsync(message.Payload, message.Type, message.RoutingKey,
messageId: message.Id, ct: stoppingToken);
message.SentUtc = DateTime.UtcNow;
await db.SaveChangesAsync(stoppingToken);
}
if (pending.Count == 0)
await Task.Delay(TimeSpan.FromSeconds(2), stoppingToken);
}
Because the outbox row’s Id becomes the MessageId, a crash between publishing and marking the row sent just causes a duplicate publish with the same ID, which the consumer’s inbox already handles. The outbox and the inbox are two halves of the same guarantee.
Testing against a real broker
Mocking IChannel tells you very little about whether messages actually flow. Testcontainers starts a throwaway RabbitMQ in Docker for the test run, so you can test the real thing: declare the topology, publish, and wait for the consumer to receive it.
public sealed class RabbitMqFixture : IAsyncLifetime
{
private readonly RabbitMqContainer _container =
new RabbitMqBuilder("rabbitmq:4-management").Build();
public string Uri => _container.GetConnectionString();
public Task InitializeAsync() => _container.StartAsync();
public Task DisposeAsync() => _container.DisposeAsync().AsTask();
}
The tests worth writing:
- A published
OrderPlacedreaches the consumer and is acknowledged. - Publishing with no queue bound throws a
PublishException, which provesmandatoryand confirms are working. - A malformed message ends up in the
.dlqand doesn’t block the queue. - A handler that always throws is retried, then dead-lettered.
- The same
MessageIddelivered twice only sends one email.
Observability
- Correlation IDs. The publisher stamps
CorrelationIdand the consumer adds it to a logging scope, so one request can be followed through every service’s logs. - Distributed tracing. The
RabbitMQ.Client.OpenTelemetrypackage addsAddRabbitMQInstrumentation()for OpenTelemetry, linking the publish and consume spans into one trace. At the time of writing it’s a release candidate. - Alert on queues, not just services. The numbers that tell you something is wrong: a growing queue (consumers can’t keep up or are down), a growing
.dlq(messages are failing), and a high unacked count (consumers are stuck). The management UI shows all three, and the Prometheus plugin exports them.
Security
- One user per service, with permissions limited to what it needs. The publisher can write to
orderflow.events; each consumer can configure and read only its own queues. - Never use
guestin production. It’s restricted to localhost by default for good reason. - Use TLS (
amqps://) for anything leaving the machine. - Keep credentials in secrets: user secrets locally, a vault or your platform’s secret store in production.
Raw client or a library?
This guide uses the official client directly, because it shows exactly what’s happening. For a larger system, a messaging library handles the outbox, retries, serialisation and topology for you:
- MassTransit is the most widely used. Version 9 is commercial; version 8 remains open source, with security patches through the end of 2026.
- Wolverine is open source, with a built-in outbox and RabbitMQ transport.
- NServiceBus is commercial, with long-term support.
- .NET Aspire has a RabbitMQ integration that wires up the connection, health checks and telemetry, and starts a local broker for development.
Even with a library, everything above still applies: it’s what the library is doing for you under the hood.
Best practices checklist
| Area | Do this |
|---|---|
| Connections | One long-lived connection per service; a channel per publisher or consumer |
| Recovery | Keep automatic recovery on; retry the first connection at startup |
| Topology | Durable topic exchange; one durable quorum queue per consuming service; declarations in one shared place |
| Publishing | Persistent messages, publisher confirms, mandatory: true, a MessageId on every message |
| Atomicity | Publish through a transactional outbox, never straight after SaveChanges |
| Consuming | Manual acks after the work is done; a sensible prefetch (10–50) |
| Failures | Retry transient errors with backoff, then BasicNack(requeue: false) to a per-queue dead-letter queue |
| Poison messages | Set x-delivery-limit; dead-letter malformed messages immediately |
| Duplicates | Idempotent handlers with an inbox keyed on MessageId |
| Contracts | Past-tense event names; additive changes only; a new type for breaking changes |
| Shutdown | Cancel cleanly, never ack an unfinished message |
| Testing | Integration tests against a real broker with Testcontainers |
| Operations | Alert on queue depth, .dlq depth and unacked messages; trace with correlation IDs |
| Security | A user per service, no guest, TLS, secrets out of source control |