Zenvoy.Abstractions 10.0.0

Zenvoy

A high-performance, zero-allocation, reflection-free mediator for .NET 10 — powered by a C# source generator.

Zenvoy gives you a MediatR-style API (Send, Publish, CreateStream, pipeline behaviors) while generating all dispatch code at compile time:

• Fast — Send through the generated Mediator compiles down to a direct handler call (sub-nanosecond overhead).
• Zero allocations on the hot path (send, publish, pipelines) with singleton handlers.
• Native AOT and trimming compatible — no reflection, no MakeGenericType, no assembly scanning.
• Compile-time safety — a missing or duplicate handler is a build error, not a runtime surprise.
• Easy migration from MediatR.

Contents

• Installation
• Quick start
• Features
  • Requests
  • Notifications
  • Streams
  • Pipeline behaviors
  • Lifetimes
  • Multi-project solutions
• Which mediator type to inject
• Configuration
• Diagnostics
• Migrating from MediatR
• Native AOT
• Benchmarks
• Limitations
• Building from source
• CI/CD
• License

Installation

dotnet add package Zenvoy                # host project
dotnet add package Zenvoy.Abstractions   # class libraries that only declare requests/handlers

The generator runs only in projects that reference Zenvoy. It discovers handlers in the current project and in every referenced assembly that references Zenvoy.Abstractions.

Quick start

// Program.cs
using Zenvoy;

[assembly: ZenvoyOptions(DefaultLifetime = ServiceLifetimeKind.Singleton)]

var builder = WebApplication.CreateSlimBuilder(args);
builder.Services.AddZenvoy();          // generated: registers the mediator and every handler
var app = builder.Build();

app.MapGet("/ping", (Zenvoy.Generated.Mediator mediator, CancellationToken ct)
    => mediator.Send(new Ping("hello"), ct));   // concrete overload — the fastest path

app.Run();

// Request + handler
public sealed record Ping(string Message) : IRequest<Pong>;
public sealed record Pong(string Message);

public sealed class PingHandler : IRequestHandler<Ping, Pong>
{
    public ValueTask<Pong> Handle(Ping request, CancellationToken ct)
        => new(new Pong($"Pong: {request.Message}"));
}

A complete Minimal API sample lives in samples/Zenvoy.Sample.WebApi.

Features

Requests

// Request with a response
public sealed record GetUser(int Id) : IRequest<User?>;

public sealed class GetUserHandler(AppDb db) : IRequestHandler<GetUser, User?>
{
    public ValueTask<User?> Handle(GetUser request, CancellationToken ct) => db.FindUserAsync(request.Id, ct);
}

// Request without a response (command) — responds with Unit
public sealed record DeleteUser(int Id) : IRequest;

public sealed class DeleteUserHandler(AppDb db) : RequestHandler<DeleteUser>
{
    protected override ValueTask HandleCore(DeleteUser request, CancellationToken ct) => db.DeleteUserAsync(request.Id, ct);
}

RequestHandler<TRequest> is a convenience base class: implement HandleCore returning a plain ValueTask. When it completes synchronously no async state machine is created. You can also implement IRequestHandler<TRequest> directly and return Unit.Task.

Value-type requests are supported without boxing:

public readonly record struct Add(int Left, int Right) : IRequest<int>;

await mediator.Send(new Add(1, 2));               // concrete overload, no boxing
await mediator.Send<Add, int>(new Add(1, 2));     // generic, still no boxing

Sending through ISender/IMediator uses a generated type switch (or a FrozenDictionary above 16 request types). An unknown request type throws HandlerNotFoundException; a null request throws ArgumentNullException.

Notifications

public sealed record UserCreated(int Id) : INotification;

public sealed class SendWelcomeEmail : INotificationHandler<UserCreated>
{
    public ValueTask Handle(UserCreated notification, CancellationToken ct) => ValueTask.CompletedTask;
}

await mediator.Publish(new UserCreated(42), ct);

• Handlers are matched at compile time, including polymorphic handlers: INotificationHandler<DomainEvent> receives every event deriving from DomainEvent, and INotificationHandler<INotification> receives everything.
• Handlers run in a deterministic order (by full type name).
• Sequential (default): handlers run one after another. Synchronously completed handlers are not awaited; the first exception stops publishing.
• Parallel: all handlers are started, then the pending ones are awaited. Exceptions are collected into an AggregateException (when there are two or more handlers).
• A notification without handlers is a no-op (reported as the informational diagnostic ZEN007).
• Zero and one handler get dedicated code paths (no arrays).

Publish<TNotification> through IPublisher dispatches on the runtime type, so publishing an event typed as its base class still reaches the handlers of the concrete type.

Streams

public sealed record Countdown(int From) : IStreamRequest<int>;

public sealed class CountdownHandler : IStreamRequestHandler<Countdown, int>
{
    public async IAsyncEnumerable<int> Handle(Countdown request, [EnumeratorCancellation] CancellationToken ct)
    {
        for (var i = request.From; i >= 0; i--)
        {
            await Task.Delay(100, ct);
            yield return i;
        }
    }
}

await foreach (var n in mediator.CreateStream(new Countdown(3), ct)) { /* ... */ }

Stream pipeline behaviors implement IStreamPipelineBehavior<TRequest, TResponse>.

Pipeline behaviors

[PipelineOrder(0)]   // lower = outer (runs first)
public sealed class LoggingBehavior<TRequest, TResponse>(ILogger<LoggingBehavior<TRequest, TResponse>> logger)
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : IRequest<TResponse>
{
    public ValueTask<TResponse> Handle(TRequest request, RequestHandlerDelegate<TRequest, TResponse> next, CancellationToken ct)
    {
        logger.LogDebug("Handling {Request}", typeof(TRequest).Name);
        return next(request, ct);
    }
}

• next takes the request and the token as parameters: pipelines are built once and reused, with no closures and no per-call allocations.
• Open generic behaviors are closed over every matching request at compile time. Generic constraints are honored: a behavior declared where TRequest : ICommand is only applied to commands.
• Closed behaviors (IPipelineBehavior<CreateOrder, int>) apply to a single request.
• Behaviors may fix the response type: ValidationBehavior<TRequest> : IPipelineBehavior<TRequest, Result>.
• Ordering: [PipelineOrder] (default 0), then the full type name.
• A behavior can short-circuit by returning without calling next.
• Requests without behaviors call the handler directly — no pipeline object is generated.

Lifetimes

• Singleton: resolved once (lazily, thread-safe) and cached in a field of the mediator.
• Scoped: resolved once per scope; the mediator itself becomes scoped.
• Transient: resolved from the container on every call.

The mediator is registered as Singleton when every handler and behavior is a singleton, and as Scoped otherwise. Resolving a scoped mediator from the root provider fails with ValidateScopes = true, as expected.

Multi-project solutions

Only the host project references Zenvoy; class libraries reference Zenvoy.Abstractions. The generator includes all public requests, handlers, behaviors and notifications from referenced assemblies that reference Zenvoy.Abstractions.

Which mediator type to inject

AddZenvoy() registers a single instance under all of these contracts:

Requests whose types are not public get internal overloads on Mediator and are not part of IZenvoyMediator.

ASP.NET Core Minimal APIs with Native AOT

Source generators cannot see each other's output, so ASP.NET Core's Request Delegate Generator (enabled with PublishAot) does not know the generated Mediator type. When you inject Mediator/IZenvoyMediator into minimal API endpoints in an AOT app:

1. Add a partial declaration so the type is visible to the Request Delegate Generator:

   namespace Zenvoy.Generated;
   
   public sealed partial class Mediator;
   

2. Give endpoint lambdas an explicit return type:

   app.MapGet("/ping/{message}", ValueTask<Pong> (string message, Mediator mediator, CancellationToken ct)
       => mediator.Send(new Ping(message), ct));
   

Injecting IMediator/ISender needs neither step. Without Native AOT (no Request Delegate Generator) neither is needed.

Configuration

Configuration is done with attributes because the generator reads it at compile time.

[assembly: ZenvoyOptions(
    DefaultLifetime = ServiceLifetimeKind.Singleton,                  // Singleton | Scoped | Transient
    NotificationStrategy = NotificationPublishStrategy.Sequential,    // Sequential | Parallel
    Namespace = "Zenvoy.Generated")]                                  // namespace of the generated Mediator

[ZenvoyHandler(Lifetime = ServiceLifetimeKind.Scoped)]
public sealed class SaveOrderHandler(AppDb db) : IRequestHandler<SaveOrder, int> { /* ... */ }

[PipelineOrder(-10)]
public sealed class TransactionBehavior<TRequest, TResponse> : IPipelineBehavior<TRequest, TResponse> /* ... */

Diagnostics

All diagnostics are reported at build time by the generator.

ZEN001

A concrete type implements IRequest<T> but no IRequestHandler<TRequest, T> exists for it (in the project or in a referenced assembly). Add a handler, or make the request abstract if it is only a base type. A handler whose response type differs from the request's declared response type does not count.

ZEN002

Exactly one handler per request is allowed. Remove or merge the extra handlers listed in the message.

ZEN003

Handlers must be non-abstract classes that the generated code can reference (public or internal, not private, not file-local) and that have a public constructor. Abstract base handlers are fine as long as a concrete subclass exists.

ZEN004

Open generic handlers such as class Handler<T> : INotificationHandler<T> are not supported in v1. Use a closed handler, a polymorphic handler (INotificationHandler<IMyEvent>) or an open generic pipeline behavior.

ZEN005

A singleton would capture a scoped dependency. Mark the handler or behavior with [ZenvoyHandler(Lifetime = ServiceLifetimeKind.Scoped)].

ZEN006

Every stream request needs exactly one IStreamRequestHandler<TRequest, T>.

ZEN007

Publishing the notification does nothing. Informational only.

Migrating from MediatR

Steps:

1. Replace the MediatR package with Zenvoy (host) / Zenvoy.Abstractions (libraries) and using MediatR; with using Zenvoy;.
2. Change handler return types from Task to ValueTask (Task.FromResult(x) → new(x), Task.CompletedTask → ValueTask.CompletedTask).
3. Update behaviors to call next(request, cancellationToken).
4. Replace AddMediatR(...) with AddZenvoy() and move lifetime / publisher settings to [assembly: ZenvoyOptions].
5. Optionally inject Zenvoy.Generated.Mediator (or IZenvoyMediator) in hot paths.

Native AOT

Zenvoy is annotated IsAotCompatible and the generated code uses no reflection. The repository verifies this with tests/Zenvoy.AotTests, a console app published with PublishAot=true that exercises send (concrete, generic, struct), void requests, pipelines, publish, streams and scoped handlers; publishing must produce zero IL2xxx/IL3xxx warnings:

scripts/aot-check.sh              # current machine
scripts/aot-check.sh linux-x64    # on Linux (cross-OS Native AOT publishing is not supported by the SDK)

Benchmarks

Apple M5 Pro, .NET 10.0.9, BenchmarkDotNet 0.15.7. Full results and methodology: benchmarks/RESULTS.md.

A direct handler call is fully inlined by the JIT (0 ns). Sub-nanosecond numbers vary by about ±0.3 ns between runs.

Limitations

• Open generic handlers are not supported (open generic behaviors are).
• Generic request types (Query<T> : IRequest<T>) are not discovered, because the generator cannot enumerate their closed forms. Sending such a request through ISender throws HandlerNotFoundException.
• Open generic behaviors are closed when each interface type argument is either a concrete type or exactly one of the behavior's type parameters (IPipelineBehavior<TRequest, TResponse>, IPipelineBehavior<TRequest, Result>). Shapes like IPipelineBehavior<TRequest, List<T>> are ignored.
• Requests are matched to handlers by exact type. Through ISender, a request instance whose runtime type was not discovered falls back to the nearest discovered base request type.
• Value-type notifications only reach handlers declared for that exact type (contravariance does not apply to value types).
• Only public types of referenced assemblies are discovered.
• Sending through a covariant interface (IRequest<object> for a request declaring IRequest<string>) works but takes a slower path (it allocates when the handler completes asynchronously).
• No pre/post processors or exception handlers — use pipeline behaviors.
• Targets .NET 10 only.

Building from source

dotnet build -c Release -warnaserror
dotnet test -c Release
scripts/aot-check.sh
dotnet run -c Release --project benchmarks/Zenvoy.Benchmarks -- --filter '*'
dotnet pack src/Zenvoy.Abstractions -c Release -o artifacts/packages && dotnet pack src/Zenvoy -c Release -o artifacts/packages
scripts/verify-packages.sh
scripts/test-local-package.sh     # builds the sample against the local .nupkg files

Snapshot tests store expected generator output in tests/Zenvoy.SourceGenerator.Tests/Snapshots. When output changes intentionally, review the .received.cs files or run the tests with ZENVOY_ACCEPT_SNAPSHOTS=1.

Versions come from git tags via MinVer: tag v10.0.0 produces packages 10.0.0.

The .NET SDK version is pinned in global.json (10.0.403 or a later feature band).

CI/CD

CI runs on GitLab (.gitlab-ci.yml):

Pushes to master (or any other branch) and merge request pipelines do not run CI.

License

MIT © Maxsud Mutalov