Mediatly 1.1.0

Mediatly

Mediatly is a lightweight, MIT-licensed, single-file CQRS mediator for .NET. It provides a simple, dependency-free implementation with a familiar API, making it easy to integrate into existing CQRS applications.

• Zero dependencies beyond Microsoft.Extensions.DependencyInjection.Abstractions.
• Commands, queries, notifications (many handlers, sequential), and pipeline behaviors.
• Reflection at most once per request type, then a cached dictionary lookup.
• Handlers and mediator registered scoped (safe with EF Core DbContext).
• Optional reflection-free / Native AOT registration path.

Install

dotnet add package Mediatly

Target frameworks

The public API is identical on every target (enforced at pack time by EnablePackageValidation). On netstandard2.0 the trim/AOT attributes are compiled from internal polyfills and are inert, and the reflection-free AddHandler<...> registration APIs still work — they are simply not required, since every runtime that consumes netstandard2.0 is JIT-based.

Quick start

using Mediatly;

// 1) Define a request + handler
public record GetUser(int Id) : IRequest<string>;

public class GetUserHandler : IRequestHandler<GetUser, string>
{
    public Task<string> Handle(GetUser request, CancellationToken ct)
        => Task.FromResult($"User#{request.Id}");
}

// 2) Register (reflection scan) + an open-generic behavior
services.AddMediatly(typeof(GetUserHandler).Assembly);
services.AddPipelineBehavior(typeof(LoggingBehavior<,>));

// 3) Send
var mediator = provider.GetRequiredService<IMediator>();
string user = await mediator.Send(new GetUser(42));

Native AOT / trimming

The convenient reflection APIs — assembly scanning (AddMediatly(assembly), cfg.AddHandlersFromAssembly...) and open-generic behaviors (AddPipelineBehavior(typeof(X<,>)), cfg.AddBehavior(typeof(X<,>))) — are not Native-AOT compatible, and this is fundamental to AOT (any reflection-based mediator shares this restriction), not a Mediatly limitation:

For trimmed / Native AOT builds, register everything explicitly and closed — no reflection at dispatch time:

services.AddHandler<GetUser, string, GetUserHandler>();
services.AddHandler<DoThing, DoThingHandler>();                 // void (Unit) request
services.AddNotificationHandler<OrderPlaced, EmailHandler>();
services.AddBehavior<GetUser, string, LoggingBehavior<GetUser, string>>(); // closed behavior

Each of these builds its dispatch wrapper with a plain new at startup (both generic arguments known at compile time). If a request reaches the mediator without a registered wrapper under AOT, you get an InvalidOperationException naming the exact AddHandler<...> call to add.

AOT-safe equivalent of a "scan + AddOpenBehavior ×N" config

A scan-based configuration like this is not AOT-compatible:

// ❌ Not AOT: reflection scan + open-generic behaviors
services.AddMediatly(cfg =>
{
    cfg.AddHandlersFromAssemblies(AppDomain.CurrentDomain.GetAssemblies()); // IL2026
    cfg.AddBehavior(typeof(AuthenticationBehavior<,>));                     // IL3050
    cfg.AddBehavior(typeof(ValidationBehavior<,>));
    cfg.AddBehavior(typeof(LoggingBehavior<,>));
});

The AOT-safe form registers each request explicitly and closes the same behavior stack per request type. A one-line helper keeps it ergonomic and preserves order (first registered = outermost):

public static class Registration
{
    public static IServiceCollection AddRequestPipeline<TRequest, TResponse,
        [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)] THandler>(
        this IServiceCollection services)
        where TRequest : IRequest<TResponse>
        where THandler : class, IRequestHandler<TRequest, TResponse>
    {
        services.AddHandler<TRequest, TResponse, THandler>();
        services.AddBehavior<TRequest, TResponse, AuthenticationBehavior<TRequest, TResponse>>(); // outermost
        services.AddBehavior<TRequest, TResponse, ValidationBehavior<TRequest, TResponse>>();
        services.AddBehavior<TRequest, TResponse, LoggingBehavior<TRequest, TResponse>>();         // innermost
        return services;
    }
}

// One line per request type — no scanning, no open generics:
services.AddRequestPipeline<GetUser,   string, GetUserHandler>();
services.AddRequestPipeline<PlaceOrder, string, PlaceOrderHandler>();

Trade-off: you list each request type once (O(number of requests) instead of a single scan), and behaviors are closed per request type so each gets its own correctly-ordered pipeline. For a large app, a source generator can emit these AddRequestPipeline<...> calls at build time to restore scan-like ergonomics while staying AOT-safe.

Publishing

dotnet publish -c Release -r win-x64   # requires the "Desktop development with C++" workload

Performance

Vs MediatR 12.4.1 (last Apache-2.0 release). BenchmarkDotNet v0.15.8, .NET 8.0.24, AMD Ryzen 7 5800U (16 logical / 8 physical cores), Windows 10; MediatR is the baseline in each group. Reproduce with the Mediatly.Benchmarks project.

Warm dispatch — Send / Publish / dynamic Send(object)

Send = plain request/response; Publish = notification to 2 handlers; Send(object) = the non-generic dynamic-dispatch path.

Startup — register + BuildServiceProvider + first (cold) dispatch

100,000 requests — batch throughput + memory

Notification fan-out — Publish to N handlers

Mediatly's per-publish allocation stays flat at 56 B regardless of handler count; MediatR's grows with the number of handlers.

Pipeline scaling — Send through N pass-through behaviors

Per-behavior overhead is similar for both, and Mediatly allocates less at every stage. On a shared machine the 3-behavior Mediatly figure showed high run-to-run variance (±42 ns, P95 411 ns), so treat the ordering at that single point as noise.

Multi-threaded throughput — scope per request, 16 logical cores

Summary: ~1.7× faster on warm dispatch, ~13× faster to cold-start, and 4–45× less allocation depending on scenario. The gains come from Mediatly doing less (no streaming / processors / publish strategies). Numbers are indicative — rerun with the Mediatly.Benchmarks project; sub-microsecond benchmarks vary on a shared machine.

Not included (by design)

IStreamRequest/streaming behaviors, request pre/post processors, and custom publish strategies are intentionally omitted to keep the library tiny. They can be added as extensions.

License

MIT.