ZeroAlloc.Mediator.Validation 6.6.1

ZeroAlloc.Mediator

ZeroAlloc.Mediator is a source-generated, zero-allocation mediator for .NET 8 and .NET 10. It supports request/response, notifications, and streaming without reflection or dynamic dispatch. The source generator eliminates the runtime overhead that reflection-based mediators incur by wiring all dispatch at compile time — no dictionaries, no virtual dispatch, no delegate allocation per request.

Install

dotnet add package ZeroAlloc.Mediator

The generator package must also be added as an analyzer:

<PackageReference Include="ZeroAlloc.Mediator.Generator" Version="*" OutputItemType="Analyzer" ReferenceOutputAssembly="false" PrivateAssets="all" />

Optional bridge packages add pipeline behaviors for other ZeroAlloc libraries:

dotnet add package ZeroAlloc.Mediator.Cache   # or .Validation, .Resilience, .Telemetry, .Authorization

PrivateAssets="all" matters in multi-project solutions: without it the analyzer flows transitively across a ProjectReference, so a downstream project runs the generator a second time and gets CS0436 on the duplicate generated types — a hard failure under TreatWarningsAsErrors.

Request types should be readonly record struct. A reference-type record still works, but the generator reports ZAM003 (a warning, which TreatWarningsAsErrors turns into a build failure) because dispatch then allocates.

Example

using ZeroAlloc.Mediator;

var builder = WebApplication.CreateBuilder(args);

// 3. Register IMediator with DI (the generator emits services.AddMediator() automatically)
builder.Services.AddMediator();

var app = builder.Build();

// 4. Send the request and use the result — fully strongly-typed, no boxing
app.MapPost("/orders", async (CreateOrder cmd, IMediator mediator, CancellationToken ct) =>
{
    var id = await mediator.Send(cmd, ct);   // returns OrderId
    return Results.Created($"/orders/{id.Value}", id);
});

app.Run();

// 1. Define a request record and its expected response type
public readonly record struct OrderId(Guid Value);
public readonly record struct CreateOrder(string Product, int Qty) : IRequest<OrderId>;

// 2. Implement a handler — no constructor dependencies needed for this example
public class CreateOrderHandler : IRequestHandler<CreateOrder, OrderId>
{
    public ValueTask<OrderId> Handle(CreateOrder request, CancellationToken ct)
        => ValueTask.FromResult(new OrderId(Guid.NewGuid()));
}

IMediator is generated into your assembly and is internal, so it cannot appear in a public signature. Endpoint lambdas and internal services are unaffected; see Visibility for the reasoning and the pattern for MVC controllers.

Performance

The static Mediator class is 36–160x faster than MediatR on Send and Publish, with zero heap allocation on those paths (.NET 10, i9-12900HK, BenchmarkDotNet). Through IMediator resolved from a new scope per call, the way an ASP.NET Core request does, it is 1.2–1.5x faster and allocates 176 B for the scope and the transient MediatorService.

The 0 B rows are pinned by AllocationGate tests, including with no factory registered. Without a factory, the static Mediator reuses one cached instance of a stateless handler: one with a parameterless constructor and no instance fields, auto-properties or captured primary-constructor parameters, on the class or any base class. That needs no configuration and no JIT help, so it holds on .NET 8 too. A handler that holds instance state is still created on every call, so its state never leaks between calls; that costs one handler object per call. Mediator.Configure(c => c.SetFactory(() => handler)) is only needed for such stateful handlers, to make them 0 B as well (#328).

The 104 B on the Stream row is the C# compiler's async IAsyncEnumerable<T> state machine for your handler method — every mediator dispatching to such handlers pays this; ZA.Mediator's own stream-dispatch contribution is 0 B. See docs/performance.md for the full benchmark table and zero-allocation design explanation.

Features

• Request/Response — strongly-typed Send overloads per request type
• Notifications — sequential or parallel ([ParallelNotification]) dispatch
• Streaming — IAsyncEnumerable<T> via CreateStream
• Pipeline Behaviors — compile-time inlined middleware chain (logging, validation, etc.)
• Bridge Packages — WithCache(), WithValidation(), WithResilience(), WithTelemetry() (OpenTelemetry metrics on IRequest<T>.Send; every dispatch opens a span with or without it), WithAuthorization() ([Authorize]-gated dispatch via ZeroAlloc.Authorization policies)
• Polymorphic Notifications — base interface handlers are automatically included in concrete notification dispatch
• Analyzer Diagnostics — missing handlers, duplicates, and misconfigurations are build errors/warnings
• Zero Allocation — ValueTask, readonly record struct, static dispatch, no closures; Send and Publish gated at 0 B by AllocationGate tests
• Native AOT Compatible — no reflection at runtime; all dispatch is resolved at compile time by the source generator

Documentation

License

MIT. See LICENSE.