Outbox Pattern
The outbox pattern decouples event publishing from handler execution. Instead of dispatching events immediately when EmitAsync is called, events are stored in an outbox and dispatched later in a controlled batch. This is useful when you need to guarantee that events are only dispatched after a database transaction commits successfully.
How it works
EmitAsync(event, EmitMode.Outbox)stores the event inIEventOutboxStorage. No dispatch occurs.- Calling
IOutboxCommit.CommitAsync()moves pending events through the event pipeline and handlers. - If a handler fails, the outbox retries with exponential backoff up to
MaxRetryAttempts. - After all retry attempts are exhausted, the event is marked
Failed(dead-lettered).
Using the outbox
Store and defer an event
// Store event in outbox — nothing dispatched yet
await emitter.EmitAsync(new TaskCreatedEvent(id, title), EmitMode.Outbox, ct);
Flush after your side-effects commit
public class CreateTaskHandler : IRequestHandler<CreateTaskCommand, Guid>
{
private readonly ITaskRepository _repository;
private readonly IEmitter _emitter;
private readonly IOutboxCommit _outboxCommit;
public CreateTaskHandler(ITaskRepository repository, IEmitter emitter, IOutboxCommit outboxCommit)
{
_repository = repository;
_emitter = emitter;
_outboxCommit = outboxCommit;
}
public async ValueTask<Result<Guid>> HandleAsync(CreateTaskCommand cmd, CancellationToken ct = default)
{
var id = Guid.NewGuid();
await _repository.SaveAsync(id, cmd.Title, ct); // ← side-effect
await _emitter.EmitAsync(
new TaskCreatedEvent(id, cmd.Title),
EmitMode.Outbox, ct); // ← store, don't dispatch yet
await _outboxCommit.CommitAsync(ct); // ← dispatch after save succeeded
return Result.Success(id);
}
}
IOutboxCommit can equally be injected somewhere else and called outside the handler — for example from a
transaction wrapper that flushes once the whole unit of work has committed:
await outboxCommit.CommitAsync(ct);
CommitAsync dispatches every pending entry as a separate unit of work: a fresh DI scope, and an
IContext rebuilt from the flow the entry was stored in — its trace id, its causation id and its baggage.
So handlers do not see the committing request's scoped services. A DbContext they resolve is a new one, not
the one that just saved, and they cannot enlist in a transaction that has already committed — which is the
point of storing the event in the first place. It also means an entry stored by one request is never dispatched
under another request's identity, which matters because CommitAsync drains whatever is pending, not only what
the calling scope stored. See Propagation.
Dispatch in the background
Instead of calling CommitAsync yourself, or as well as it, let a hosted service poll the outbox and
dispatch whatever is pending:
services.AddSynapse(cfg =>
{
cfg.AddOutboxDispatcher(opts => opts.PollingInterval = TimeSpan.FromSeconds(2));
});
The dispatcher polls every PollingInterval (default 5 seconds). When a poll dispatches a full
BatchSize batch successfully, it polls again straight away rather than waiting. Each poll runs in
its own DI scope, and a poll that fails (for example because the database is unreachable) is logged
and retried at the next interval. Retry, dead-letter and batch settings are the ones from
ConfigureOutbox, shared with CommitAsync. Only generic-host applications start hosted services.
Running several instances
Before dispatching, entries are claimed from a storage that implements IClaimableOutboxStorage,
as the in-memory, EF Core and ADO.NET storages do. A claimed entry is hidden from
every other claimer, so several instances of your application, and CommitAsync calls running alongside
the dispatcher, never hand the same entry out twice. CommitAsync claims too.
A claim is a lease rather than a held lock. Marking the entry processed or failed releases it. If an
instance crashes mid-batch, its entries become claimable again once ClaimLeaseDuration (default 5
minutes) has passed. Delivery stays at-least-once, so keep the lease comfortably longer than a batch
takes to dispatch: an entry whose lease runs out mid-dispatch can be claimed and dispatched by another
instance too.
:::caution Set a BatchSize when running several instances
BatchSize is unlimited by default, so a single poll claims the whole backlog under one lease.
After an outage or a burst, draining that backlog can take longer than ClaimLeaseDuration, and
another instance can then claim and dispatch the entries still waiting in the same batch. A finite
BatchSize keeps each claim small enough to finish well within its lease. The dispatcher polls
again straight away after a full batch, so throughput doesn't suffer.
:::
A custom storage that does not implement IClaimableOutboxStorage still works. The dispatcher logs a
warning at startup, because without claiming two processors can dispatch the same entry.
Configure the outbox
Set outbox options in AddSynapse:
services.AddSynapse(cfg =>
{
cfg.ConfigureOutbox(opts =>
{
opts.MaxRetryAttempts = 5;
opts.InitialRetryDelay = TimeSpan.FromSeconds(1);
opts.BackoffFactor = 2.0; // exponential: 1s, 2s, 4s, 8s, 16s
opts.BatchSize = 100; // max events per CommitAsync call or dispatcher poll
opts.ClaimLeaseDuration = TimeSpan.FromMinutes(5);
});
});
| Option | Default | Description |
|---|---|---|
MaxRetryAttempts | 3 | Number of delivery attempts before marking the event as failed. |
InitialRetryDelay | TimeSpan.Zero | Delay before the first retry. |
BackoffFactor | 2.0 | Multiplier applied to the delay for each subsequent retry. |
BatchSize | unlimited | Cap the number of events dispatched per CommitAsync call or dispatcher poll. |
ClaimLeaseDuration | 5 minutes | How long a claimed entry stays hidden from other processors if it is never marked processed or failed. |
Configure the default emit mode
If most of your events should use the outbox, set it as the default:
cfg.SetDefaultPublishingMode(EmitMode.Outbox);
With this setting, EmitAsync(event) and EmitAsync(event, EmitMode.Default) store to the outbox automatically.
:::warning Production storage
The built-in InMemoryEventOutboxStorage is not persistent — all pending events are lost on restart. Replace it with a database-backed implementation before going to production.
It is also not transactional: it is not enlisted in your database transaction. If a handler emits an event with EmitMode.Outbox and then fails or rolls back, the pending entry stays in memory and is dispatched by the next IOutboxCommit.CommitAsync call, typically triggered by an unrelated request. Use a storage that writes the entry in the same transaction as your data.
When the in-memory storage is registered in a Production host, Synapse logs a warning at startup. If the application never emits with EmitMode.Outbox, turn it off with cfg.DisableInMemoryOutboxProductionWarning().
:::
Discard the events of a failed request
If you stay on the in-memory storage, opt in to OutboxDiscardOnFailureBehavior. When a request returns a failed Result or throws, it takes back the outbox events that request stored and that were not dispatched yet, so a later CommitAsync does not publish something that never happened. It runs outermost, so a failure raised by any other behavior counts too.
Enable it per request type:
cfg.RegisterOutboxDiscardOnFailure<CreateTaskCommand, Guid>();
cfg.RegisterOutboxDiscardOnFailure<DeleteTaskCommand>();
Or for every handler in the assembly:
[assembly: SynapseGlobalBehavior(typeof(OutboxDiscardOnFailureBehavior<>))]
[assembly: SynapseGlobalBehavior(typeof(OutboxDiscardOnFailureBehavior<,>))]
Things to know:
- It is opt-in. Without it, the leak described above still happens.
- Discarding is scope-wide: it takes back everything the current DI scope stored, not only what the failing request stored. Events stored by other scopes, such as concurrent requests, are never touched.
- Events already dispatched by an explicit
CommitAsyncinside the failed handler cannot be taken back. - It only applies to a storage that implements
IDiscardableOutboxStorage, which the in-memory one does. With a transactional storage the database rollback already removes the entry, so the behavior does nothing.
Replace the storage for production
The built-in InMemoryEventOutboxStorage is suitable for testing and simple scenarios. For production, replace it with a persistent implementation. UnambitiousFx.Synapse.Outbox.EntityFrameworkCore ships a ready-made, transactional one — see EF Core outbox storage for installation, the multi-DbContext (modular monolith) transaction-sharing pattern, and migrations. Without EF Core, UnambitiousFx.Synapse.Outbox.AdoNet does the same over plain ADO.NET for PostgreSQL and SQL Server — see ADO.NET outbox storage. With EF Core, in short:
services.AddDbContext<OutboxDbContext>(o => o.UseNpgsql(connectionString));
services.AddEfCoreEventOutbox<OutboxDbContext>();
services.AddSynapse(cfg =>
{
cfg.SetEventOutboxStorage<EfCoreEventOutboxStorage<OutboxDbContext>>();
});
Health check
Register the outbox health check to surface queue depth and lag in your /health endpoint:
builder.Services.AddHealthChecks()
.AddCheck<OutboxHealthCheck>("outbox", tags: ["ready"]);
OutboxHealthCheck reads its OutboxHealthCheckOptions from its constructor (not IOptions<T>), so register a configured instance as a singleton; AddCheck<OutboxHealthCheck> resolves it through the optional constructor parameter:
builder.Services.AddSingleton(new OutboxHealthCheckOptions
{
DegradedPendingThreshold = 50, // Degraded when pending >= 50
CriticalPendingThreshold = 200, // Unhealthy when pending >= 200
CriticalLagThreshold = TimeSpan.FromMinutes(5),
});
See Observability for the full threshold list (dead-letter and lag thresholds included).
See also
- Events —
EmitModeexplained, how to publish events withIEmitter. - Observability — outbox metrics (queue depth, lag, failed count).