ZeroAlloc.Mediator 6.6.3

ZeroAlloc.Mediator

A source-generated MediatR alternative for .NET 8 and .NET 10: requests, notifications and streams dispatched without reflection, with no allocations on the Send and Publish hot path, ready for NativeAOT.

Why ZeroAlloc.Mediator

• 0 B per Send and Publish. The static Mediator path, pipeline behaviors included, is held at zero bytes by AllocationGate tests. MediatR allocates 224 B per Send and 792 B per single-handler Publish in the same benchmark.
• 3.9–20x faster than MediatR on Send and Publish in the same BenchmarkDotNet run. Through IMediator resolved from a new scope per call, the way an ASP.NET Core request does, it is still 1.4–3.2x faster and allocates 176–200 B against MediatR's 352–1,232 B.
• Works under NativeAOT and trimming. Dispatch is a generated, strongly-typed overload per request type: no reflection, no dictionary lookup, no handler scanning at startup. CI publishes and runs a NativeAOT sample on every build.
• Mistakes fail the build, not the request. A request with no handler, two handlers for one request or a misconfigured behavior is reported by the generator as a compiler diagnostic.

Install

dotnet add package ZeroAlloc.Mediator
dotnet add package ZeroAlloc.Mediator.Generator

The second package is the source generator; it is added as a private development dependency. See Getting Started for multi-project solutions.

Quick start

using ZeroAlloc.Mediator;

decimal total = await Mediator.Send(new AddToCart(Quantity: 3, UnitPrice: 9.99m));
Console.WriteLine(total); // 29.97

public readonly record struct AddToCart(int Quantity, decimal UnitPrice) : IRequest<decimal>;

public sealed class AddToCartHandler : IRequestHandler<AddToCart, decimal>
{
    public ValueTask<decimal> Handle(AddToCart request, CancellationToken ct)
        => ValueTask.FromResult(request.Quantity * request.UnitPrice);
}

Mediator.Send(AddToCart) is an overload the generator wrote for this request, so the call is checked by the compiler and dispatches straight to the handler. In an ASP.NET Core app, call builder.Services.AddMediator() and inject IMediator; see Dependency Injection.

What you get

• Requests and responses: commands and queries with a typed response, or Unit for none.
• Notifications: publish to every handler, sequentially or in parallel with [ParallelNotification], and handlers for a base interface receive derived notifications too.
• Streaming: IAsyncEnumerable<T> results through CreateStream.
• Pipeline behaviors: logging, validation, transactions and other cross-cutting code, inlined into each dispatch at compile time instead of iterated from a list.
• Dependency injection: a generated AddMediator() and IMediator, with handler lifetimes you choose.
• Analyzer diagnostics: ZAM001–ZAM011, with fixes, in the diagnostics reference.

Optional packages plug into the pipeline; reference one and call its With...() method on AddMediator():

• ZeroAlloc.Mediator.Validation: runs the ZeroAlloc.Validation validator for a request before its handler. WithValidation()
• ZeroAlloc.Mediator.Authorization: gates dispatch on [RequirePolicy] checks from ZeroAlloc.Authorization. WithAuthorization()
• ZeroAlloc.Mediator.Cache: caches responses for requests marked [CacheResponse]. WithCache()
• ZeroAlloc.Mediator.Resilience: retry, timeout and circuit-breaker policies through ZeroAlloc.Resilience. WithResilience()
• ZeroAlloc.Mediator.Telemetry: OpenTelemetry request count and duration metrics. WithTelemetry()

Performance

.NET 10, BenchmarkDotNet, ZeroAlloc.Mediator and MediatR in the same run. Allocations are exact; speed is a same-run ratio.

The 176 B is the DI scope and the transient IMediator, not the dispatch. The static rows hold with no factory registered, for a handler without instance state. The performance page has every row, including pipelines and streaming, and explains where each byte comes from.

Learn more

• Documentation: mediator.zeroalloc.net, or the docs folder on GitHub, including migration guides.
• Related ZeroAlloc packages:
  • ZeroAlloc.Pipeline (docs): Mediator's pipeline behaviors are ZeroAlloc.Pipeline behaviors, and its generator inlines them.
  • ZeroAlloc.Validation (docs): source-generated validators that ZeroAlloc.Mediator.Validation runs before each handler.
  • ZeroAlloc.Authorization (docs): the policies that ZeroAlloc.Mediator.Authorization checks before dispatch.
  • ZeroAlloc.Results (docs): give a request a Result response and the validation and authorization packages return failures in it instead of throwing.
• Contributing: issues and pull requests are welcome on GitHub.
• License: MIT, see LICENSE.