ZeroAlloc.Outbox 4.4.4

ZeroAlloc.Outbox

Source-generated transactional outbox for .NET. Annotate a message type with [OutboxMessage] and a Roslyn source generator emits a typed writer and dispatcher bridge — no reflection, no boxing, AOT-safe. Backed by ZeroAlloc.ORM or EF Core (production) or in-memory (tests), with a built-in polling worker, exponential-backoff retry, and dead-letter support.

Multiple packages in this family — see Documentation or NuGet for the full list.

Install

The source generator is bundled into the main package — a single PackageReference is all you need:

# Core abstractions + source generator (always required)
dotnet add package ZeroAlloc.Outbox

# Pick a store:
dotnet add package ZeroAlloc.Outbox.Orm       # production — ZeroAlloc.ORM raw SQL, Native AOT (net10.0)
dotnet add package ZeroAlloc.Outbox.EfCore    # production — Entity Framework Core
dotnet add package ZeroAlloc.Outbox.InMemory  # testing — in-process, no database

# Optional bridges:
dotnet add package ZeroAlloc.Outbox.Mediator    # dispatch through ZeroAlloc.Mediator IMediator.Publish
dotnet add package ZeroAlloc.Outbox.Resilience  # wrap dispatchers in a ZeroAlloc.Resilience proxy
dotnet add package ZeroAlloc.Outbox.Telemetry   # OpenTelemetry instrumentation around dispatch

See Mediator Integration, Resilience Bridge and OpenTelemetry integration.

The standalone ZeroAlloc.Outbox.Generator package is still published for backwards compatibility with existing direct PackageReferences, but new consumers should reference only ZeroAlloc.Outbox.

Quick start

1. Annotate your message:

using ZeroAlloc.Outbox;

[OutboxMessage]
public sealed record OrderPlaced(int OrderId, decimal Amount);

The generator emits IOutboxWriter<OrderPlaced> and its DI registration extension.

2. Register with DI:

builder.Services.AddOutbox(options =>
        {
            options.PollingInterval = TimeSpan.FromSeconds(5);
            options.BatchSize       = 50;
            options.MaxAttempts     = 3;
            options.LeaseDuration   = TimeSpan.FromMinutes(2); // must exceed your slowest dispatch
        })
        .WithEfCore<AppDbContext>()      // or .WithOrm() / .WithInMemoryStore()
        .AddOrderPlacedOutbox();         // generated extension

3. Choose a serializer. AddOutbox() has no implicit serializer since 4.0; pick one:

// AOT-safe: annotate OrderPlaced with [ZeroAllocSerializable] (ZeroAlloc.Serialisation)
builder.Services.AddSerializerDispatcher();

// or reflection-based System.Text.Json, not trim- or AOT-safe:
builder.Services.AddOutbox().WithSystemTextJsonSerializer();

Without either, the host fails to start with an error that names both options. See AOT-Safe Serialisation.

4. Write in a transaction:

public class OrderService(IOutboxWriter<OrderPlaced> writer, AppDbContext db)
{
    public async Task PlaceOrderAsync(Order order, CancellationToken ct)
    {
        db.Orders.Add(order);
        await db.SaveChangesAsync(ct);
        await writer.WriteAsync(new OrderPlaced(order.Id, order.Total), ct: ct);
    }
}

For atomic writes (both or neither commit), pass the DbTransaction explicitly. See EF Core Transaction.

5. Implement a dispatcher:

public class OrderPlacedDispatcher(IMessageBus bus) : IOutboxDispatcher<OrderPlaced>
{
    public async ValueTask DispatchAsync(OrderPlaced message, CancellationToken ct)
        => await bus.PublishAsync(message, ct);
}

// Register the dispatcher
builder.Services.AddTransient<IOutboxDispatcher<OrderPlaced>, OrderPlacedDispatcher>();

Dashboard

Operate the outbox at runtime: inspect pending / retry / dead-lettered / dispatched messages, watch a live throughput chart, and requeue or cancel individual messages.

Add the package, then register the event publisher and map the endpoints:

dotnet add package ZeroAlloc.Outbox.Dashboard

// Register the publisher (required for SSE live updates)
builder.Services.AddOutbox().WithDashboardEvents();

// Map the dashboard endpoints
app.MapOutboxDashboard("/outbox");

// Optional: protect with auth
app.MapOutboxDashboard("/outbox").RequireAuthorization("AdminPolicy");

The mapped root (/outbox) serves the HTML dashboard; REST endpoints (snapshot, throughput, requeue, cancel, force-dispatch) and the SSE stream (events) live under the same prefix.

Security

The dashboard exposes write actions (requeue, cancel, force-dispatch) as POST endpoints:

• POST /outbox/api/messages/{id}/requeue
• POST /outbox/api/messages/{id}/cancel
• POST /outbox/api/messages/{id}/force-dispatch

Never mount the dashboard unauthenticated in a production environment. Always apply authentication/authorization:

app.MapOutboxDashboard("/outbox").RequireAuthorization("AdminPolicy");

The IEndpointConventionBuilder returned by MapOutboxDashboard supports all standard ASP.NET Core auth middleware (RequireAuthorization, AllowAnonymous, route filters, etc.).

CSRF protection is the host application's responsibility — the dashboard does not emit or validate anti-forgery tokens. If your authentication scheme is cookie-based, apply the standard ASP.NET Core [ValidateAntiForgeryToken] or enable the antiforgery middleware as appropriate.

What the dashboard shows

• Pending — messages awaiting their first dispatch attempt
• Retry queue — messages that have failed at least once and are scheduled for retry
• Dead-lettered — messages that exceeded MaxAttempts, with the last failure reason
• Dispatched — most-recently succeeded messages
• Throughput — SVG chart of dispatched + failed counts per minute
• Actions — Requeue a dead-lettered message · Cancel a pending one · Force dispatch to run it now

Tab	Screenshot
Pending — queue of messages awaiting first dispatch
Retry — failed messages with back-off schedule
Dead-lettered — exhausted retries with last error
Dispatched — recently-succeeded history feeding the throughput chart

The dashboard is fully responsive — tablet (768 × 1024) and mobile (375 × 812) captures live in docs/screenshots/.

Blazor component

For apps already using Blazor, ZeroAlloc.Outbox.Dashboard.Blazor ships an <OutboxDashboard /> component that embeds the dashboard via iframe:

dotnet add package ZeroAlloc.Outbox.Dashboard.Blazor

@* In any Razor page / component *@
<OutboxDashboard BaseUrl="/outbox" />

You still need MapOutboxDashboard("/outbox") — the Blazor component is a thin wrapper around the mapped endpoints.

Performance

Correctness-matched overhead vs a hand-rolled SQLite outbox (same connection, both transactional). .NET 10.0.7, i9-12900HK, BenchmarkDotNet v0.15.4.

Near-zero abstraction overhead vs writing the same outbox by hand — the 2–9% delta is IOutboxWriter<T> + IOutboxStore interface dispatch. The value of ZA.Outbox is the [OutboxMessage] attribute + typed writer + ecosystem composability (resilience / telemetry / dispatcher bridges) at this cost.

Serializing a message for enqueue allocates only its exact-size payload array: 72 B for a small struct message, 64 B for a small class message, with the generated SerializerDispatcher. The ORM store persists that array without copying it. Reading a payload back for dispatch does not box a struct message: a MemoryPack struct dispatches with 0 B allocated.

Full methodology: docs/performance.md.

Features

Diagnostics

Documentation

Full docs live in docs/:

• Getting Started
• Outbox Pattern
• Message Types
• Dispatchers
• Store Adapters
• Background Worker
• Dependency Injection
• Migrating to v3
• Migrating to v4
• Dashboard · Testing · Performance
• Cookbook: EF Core transaction, custom dispatcher, Mediator integration, dead-letter handling, testing with a host, AOT-safe serialisation, Resilience bridge, telemetry
• Diagnostics: ZO0001 · ZO0002 · ZO0003 · ZO0004 · ZO0005 · ZO0006 · ZO0007

License

MIT