ZeroAlloc.Outbox 2.5.0

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 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.EfCore    # production — Entity Framework Core
dotnet add package ZeroAlloc.Outbox.InMemory  # testing — in-process, no database

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;
        })
        .WithEfCore<AppDbContext>()      // or .WithInMemoryStore()
        .AddOrderPlacedOutbox();         // generated extension

3. 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.

4. Implement a dispatcher:

public class OrderPlacedDispatcher(IMessageBus bus) : IOutboxDispatcher<OrderPlaced>
{
    public async Task 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.

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
• Diagnostics: ZO0001 · ZO0002 · ZO0003

License

MIT