Skip to main content
Version: 3.x

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​

  1. EmitAsync(event, EmitMode.Outbox) stores the event in IEventOutboxStorage. No dispatch occurs.
  2. Calling IOutboxCommit.CommitAsync() moves pending events through the event pipeline and handlers.
  3. If a handler fails, the outbox retries with exponential backoff up to MaxRetryAttempts.
  4. 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);
Each entry is dispatched in its own scope

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);
});
});
OptionDefaultDescription
MaxRetryAttempts3Number of delivery attempts before marking the event as failed.
InitialRetryDelayTimeSpan.ZeroDelay before the first retry.
BackoffFactor2.0Multiplier applied to the delay for each subsequent retry.
BatchSizeunlimitedCap the number of events dispatched per CommitAsync call or dispatcher poll.
ClaimLeaseDuration5 minutesHow 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 CommitAsync inside 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 — EmitMode explained, how to publish events with IEmitter.
  • Observability — outbox metrics (queue depth, lag, failed count).