Davish.Sendr.Generators
4.1.2
dotnet add package Davish.Sendr.Generators --version 4.1.2
NuGet\Install-Package Davish.Sendr.Generators -Version 4.1.2
<PackageReference Include="Davish.Sendr.Generators" Version="4.1.2"> <PrivateAssets>all</PrivateAssets> <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets> </PackageReference>
<PackageVersion Include="Davish.Sendr.Generators" Version="4.1.2" />
<PackageReference Include="Davish.Sendr.Generators"> <PrivateAssets>all</PrivateAssets> <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets> </PackageReference>
paket add Davish.Sendr.Generators --version 4.1.2
#r "nuget: Davish.Sendr.Generators, 4.1.2"
#:package Davish.Sendr.Generators@4.1.2
#addin nuget:?package=Davish.Sendr.Generators&version=4.1.2
#tool nuget:?package=Davish.Sendr.Generators&version=4.1.2
<div align="center">
Davish.Sendr
A free, lightweight mediator for .NET with explicit registration and no runtime assembly scanning.
</div>
Sendr is a small mediator library designed to limit allocations. It supports request/response dispatch, async streams, and notification publishing, with decorators for each. Register handlers explicitly or opt into compile-time discovery.
Features
- Dispatch
IRequestcommands andIRequest<TResponse>queries to one handler per request/response pair. - Use
ICommand,ICommand<TResponse>, andIQuery<TResponse>for explicit CQRS contracts, dispatched through the sameISender. - Return lazy async streams with
IStreamRequest<TResponse>andIAsyncEnumerable<T>. - Publish
INotificationto any number of handlers in ordered Sequence and concurrent Parallel groups. - Wrap compatible request, stream, or notification handlers with a reusable, non-generic decorator.
- Register handlers manually or use compile-time discovery — one or the other for the sender, and separately for the publisher. Neither path scans assemblies at runtime.
- Enable reflection-free
ISender/IStreamSenderdispatch withDavish.Sendr.GeneratorsandAddSendr(o => o.UseGenerators()). - Emit an
Activityper request, command, query, and notification dispatch for OpenTelemetry tracing. See Tracing. - Target
netstandard2.0andnet10.0. - Reference
Davish.Sendr.Abstractionsfor domain contracts andDavish.Sendrfor the request/response and notification implementations.
Manual registration uses generic constraints to check handler compatibility at compile time. The optional source generator discovers handlers in the current project and explicitly included assemblies. Missing request handlers are reported when dispatched; stream requests report them when enumeration starts.
Install
dotnet add package Davish.Sendr
The contracts (IRequest, IRequestHandler, IRequestDecorator, ISender, …) also ship on their own so your domain assemblies can reference them without pulling in the DI implementation:
dotnet add package Davish.Sendr.Abstractions
Notification publishing (INotification, IPublisher, AddSendrNotification, …) is included in these two packages.
The CQRS contracts (ICommand, ICommandHandler, IQuery, and IQueryHandler) are also included in Davish.Sendr.Abstractions.
Davish.Sendr.Message, Davish.Sendr.Notification, and Davish.Sendr.Notification.Abstractions are deprecated compatibility packages. They reference Davish.Sendr.Abstractions or Davish.Sendr, so existing package references still compile. New projects should reference Davish.Sendr.Abstractions and Davish.Sendr directly.
For optional compile-time handler discovery and dispatch, install:
dotnet add package Davish.Sendr.Generators
Getting started
Call AddSendr once, then register each handler explicitly.
builder.Services
.AddSendr()
.AddRequestHandler<CreateOrder, CreateOrderHandler>()
.AddRequestHandler<GetOrder, OrderDto, GetOrderHandler>()
.AddStreamRequestHandler<ListOrders, OrderDto, ListOrdersHandler>();
Register one handler per request/response pair. A second AddRequestHandler, AddCommandHandler, AddQueryHandler, or AddStreamRequestHandler call for the same type and response throws InvalidOperationException. Dispatching a request without a registered handler also throws InvalidOperationException, with a message naming the missing registration call. For streams, this happens when enumeration starts. Registration captures the configuration immediately; later changes to the object passed to configure have no effect.
Requests
Use IRequest for commands that do not return a value.
public sealed record CreateOrder(Guid Id) : IRequest;
public sealed class CreateOrderHandler : IRequestHandler<CreateOrder>
{
public Task HandleAsync(CreateOrder request, CancellationToken cancellationToken = default)
{
return Task.CompletedTask;
}
}
Use IRequest<TResponse> for request/response dispatching.
public sealed record GetOrder(Guid Id) : IRequest<OrderDto>;
public sealed record OrderDto(Guid Id, string Number);
public sealed class GetOrderHandler : IRequestHandler<GetOrder, OrderDto>
{
public Task<OrderDto> HandleAsync(GetOrder request, CancellationToken cancellationToken = default)
{
return Task.FromResult(new OrderDto(request.Id, "SO-001"));
}
}
Resolve ISender and call SendAsync.
var sender = serviceProvider.GetRequiredService<ISender>();
await sender.SendAsync(new CreateOrder(Guid.NewGuid()), cancellationToken);
var order = await sender.SendAsync(new GetOrder(Guid.NewGuid()), cancellationToken);
Commands and queries (CQRS)
ICommand / ICommand<TResponse> and IQuery<TResponse> are independent of IRequest / IRequest<TResponse>. Each has its own handler interface, ISender.SendAsync overload, registration method, and decorator interface. Command and query handlers use ICommandHandler and IQueryHandler respectively, without requiring IRequestHandler.
public sealed record CreateOrder(Guid Id) : ICommand;
public sealed class CreateOrderHandler : ICommandHandler<CreateOrder>
{
public Task HandleAsync(CreateOrder command, CancellationToken cancellationToken = default)
{
return Task.CompletedTask;
}
}
public sealed record GetOrder(Guid Id) : IQuery<OrderDto>;
public sealed record OrderDto(Guid Id, string Number);
public sealed class GetOrderHandler : IQueryHandler<GetOrder, OrderDto>
{
public Task<OrderDto> HandleAsync(GetOrder query, CancellationToken cancellationToken = default)
{
return Task.FromResult(new OrderDto(query.Id, "SO-001"));
}
}
Register with AddCommandHandler or AddQueryHandler. Call sites still use ISender.SendAsync, which selects the overload from the argument's static type.
builder.Services
.AddSendr()
.AddCommandHandler<CreateOrder, CreateOrderHandler>()
.AddQueryHandler<GetOrder, OrderDto, GetOrderHandler>();
Command and query decorators implement ICommandDecorator and IQueryDecorator. They follow the same pattern as IRequestDecorator, with constraints on ICommand and IQuery:
public sealed class LoggingCommandDecorator(ILogger<LoggingCommandDecorator> logger) : ICommandDecorator
{
public async Task HandleAsync<TCommand>(
TCommand command, RequestHandlerDelegate next, CancellationToken cancellationToken = default)
where TCommand : ICommand
{
logger.LogInformation("Handling {Command}", typeof(TCommand).Name);
await next();
}
}
Decorators
Decorators are non-generic pipeline behaviours that can wrap any compatible request type. Use IRequestDecorator for IRequest and IRequestDecorator.WithResponse for IRequest<TResponse>. The separate CQRS contracts use ICommandDecorator, ICommandDecorator.WithResponse, and IQueryDecorator.
builder.Services
.AddSendr()
.AddRequestHandler<GetOrder, OrderDto, GetOrderHandler>(x => x.Decorator
.With<TransactionDecorator>()
.With<LoggingDecorator>());
Decorators execute in the order they are added: the first With<> is the outermost layer. In the example above, TransactionDecorator runs first and last, with LoggingDecorator nested inside it.
public sealed class LoggingDecorator(ILogger<LoggingDecorator> logger)
: IRequestDecorator, IRequestDecorator.WithResponse
{
public async Task HandleAsync<TRequest>(
TRequest request,
RequestHandlerDelegate next,
CancellationToken cancellationToken = default)
where TRequest : IRequest
{
logger.LogInformation("Handling {Request}", typeof(TRequest).Name);
await next();
logger.LogInformation("Handled {Request}", typeof(TRequest).Name);
}
public async Task<TResponse> HandleAsync<TRequest, TResponse>(
TRequest request,
RequestHandlerDelegate<TResponse> next,
CancellationToken cancellationToken = default)
where TRequest : IRequest<TResponse>
{
logger.LogInformation("Handling {Request}", typeof(TRequest).Name);
var response = await next();
logger.LogInformation("Handled {Request}", typeof(TRequest).Name);
return response;
}
}
Source-generated registration (opt-in)
Davish.Sendr.Generators discovers your request, command, query, and stream handler implementations at compile time and generates UseGenerators(), a SendrOptions extension that plugs into AddSendr. It registers the discovered handlers and installs a reflection-free ISender/IStreamSender. Dispatch uses generated dictionaries keyed by message type and, where applicable, response type.
<PackageReference Include="Davish.Sendr" Version="4.1.0" />
<PackageReference Include="Davish.Sendr.Generators" Version="4.1.0" PrivateAssets="all" />
builder.Services.AddSendr(o => o.UseGenerators());
Declare decorators on the handler with [DecorateWith<...>]. Type arguments run from outermost to innermost, matching the order of x.Decorator.With<T>() calls:
[DecorateWith<TransactionDecorator, LoggingDecorator>]
public sealed class GetOrderHandler : IRequestHandler<GetOrder, OrderDto>
{
public Task<OrderDto> HandleAsync(GetOrder request, CancellationToken cancellationToken) { /* ... */ }
}
Notes:
AddSendr()withoutUseGenerators()registers the default reflection-based sender.- Once
UseGenerators()installs the generated sender, dispatch only knows about handlers discovered at compile time. ManualAddRequestHandler/AddCommandHandler/AddQueryHandler/AddStreamRequestHandlercalls do not extend its dispatch tables. Choose manual registration or generated registration for the sender. UseSendrOptions.UseSender<TSender>()to install a custom sender implementation. [DecorateWith<...>]comes in arities 1 through 8; apply at most one per handler class.- The generator discovers both classes and record classes.
- The generator needs
Davish.Sendrin the same project. In a project that references onlyDavish.Sendr.Abstractions(for example a handler library), it generates nothing and reports warningSENDR008; remove the generator there and include the library from the host withIncludeAssemblyOf<TMarker>(). - A handler declared as
struct/record structis a compile error (SENDR004), since handler resolution (generated or manual) requires a reference type; useclass/record classinstead. - Open generic handler classes are not discovered. Register closed constructed handler types with the appropriate manual registration method, without
UseGenerators(). - By default, the generator discovers handlers only in the project that calls
UseGenerators(). Handlers in a referenced project or NuGet package require an explicitIncludeAssemblyOf<TMarker>()declaration (see Cross-assembly discovery). Alternatively, use manual registration withoutUseGenerators(). - Multiple handlers for the same request/response pair produce compile error
SENDR002. A message may implementIRequest<TResponse>,ICommand<TResponse>,IQuery<TResponse>, orIStreamRequest<TResponse>with multiple response types; each response type has its own handler slot. - The generator also discovers
ICommandHandlerandIQueryHandler. It validates their[DecorateWith<...>]attributes against the corresponding command or query decorator interface. - For
INotificationHandler, useAddSendrNotification. See Notification: source-generated registration. - Known limitations (one class implementing several handler interfaces, derived request types, replacing handlers in tests) are listed in the documentation.
Cross-assembly discovery
Include another assembly explicitly to discover its handlers. For example, a domain or application library referenced through ProjectReference does not need to run the generator itself:
// Any type declared in the library assembly works as the marker — it doesn't need to
// implement any particular interface.
public sealed class ApplicationAssemblyMarker;
builder.Services.AddSendr(o => o.UseGenerators(g => g.IncludeAssemblyOf<ApplicationAssemblyMarker>()));
IncludeAssemblyOf<TMarker>() chains, and combines with more than one assembly:
o.UseGenerators(g => g
.IncludeAssemblyOf<ApplicationAssemblyMarker>()
.IncludeAssemblyOf<InfrastructureAssemblyMarker>());
Notes:
- The generator reads this declaration directly from source; it does not scan assemblies at runtime. Write calls inline in the
UseGenerators(g => ...)lambda, either as a fluent chain or as individual statements in a block. Delegate variables, method groups, loops, conditionals, and helper or extension methods wrapping the configuration produce compile errorSENDR005. - The current project is always included automatically; naming its own assembly again via a local marker is harmless, not an error.
- Discovery includes only the named assemblies, not their transitive dependencies.
- A handler discovered this way must be accessible from the calling project: public (including every containing type, for a nested handler), or internal with a matching
[assembly: InternalsVisibleTo("...")]declared by the library. Otherwise it's a compile error (SENDR007) rather than an invisible handler. - Handlers and decorators declared in the calling project must be reachable by the generated code as well: a
privateorprotectednested type is a compile error (SENDR007); make itinternalorpublic, including any containing type. - Each compilation has one set of generated dispatch tables for
ISender/IStreamSenderand a separate set forIPublisher. Each uses the assemblies declared in its ownUseGenerators()configuration. You can include the same library on both sides. Multiple calls configuring the same sender or publisher must declare identical assembly sets; conflicting sets produce compile errorSENDR006. - Duplicate handlers for a request/response pair produce
SENDR002whether they are local, in an included assembly, or spread across assemblies.
Tracing
ISender.SendAsync (requests, commands, queries) and IPublisher.PublishAsync (notifications) emit Activity spans from an ActivitySource named Davish.Sendr. Nothing is emitted, and no Activity is created, until a listener subscribes to that name:
builder.Services.AddOpenTelemetry()
.WithTracing(t => t
.AddSource(SendrActivitySource.Name) // "Davish.Sendr"
.AddOtlpExporter());
Each span is ActivityKind.Internal and nests under whatever Activity is current at the call site, such as an ASP.NET Core request.
| Span | Name | Emitted for |
|---|---|---|
| Send | Send <RequestTypeName> |
each request, command, or query |
| Publish | Publish <NotificationTypeName> |
each PublishAsync that has at least one handler |
| Handle | Handle <HandlerTypeName> |
each notification handler, including its decorators; a child of the Publish span |
A PublishAsync for a notification with no handlers emits nothing. Sequence handlers are siblings under the Publish span, not nested in one another, and Parallel handlers overlap in time.
| Tag | On | Value |
|---|---|---|
sendr.kind |
all | request, command, query, notification, or notification.handler |
sendr.request.type |
Send, Publish | Full name of the request or notification type |
sendr.handler.type |
Handle | Full name of the handler type |
sendr.notification.group |
Handle | sequence or parallel |
error.type |
any | Exception type full name, set only on failure (the span status is also Error) |
A failed handler marks only its own Handle span as Error; the Publish span is Error when any handler failed, and its error.type is the exception that PublishAsync throws (AggregateException when several handlers failed). Cancellation (OperationCanceledException) is recorded as an error like any other exception.
Both the reflection-based and the generated sender and publisher emit these spans. Generated code needs Davish.Sendr 3.6.0 or later at runtime, because it calls SendrActivitySource. Stream requests are not traced yet.
SendAsync throws synchronously only for a null message (ArgumentNullException). Every other failure (no handler, a handler or decorator that cannot be resolved, or one that throws) is reported through the returned Task, whether or not a listener is subscribed. PublishAsync behaves the same way: only a null notification throws synchronously. A handler that throws, synchronously or not, faults the returned Task once the other handlers have run, whether or not a listener is subscribed.
Streams
Use IStreamRequest<TResponse> and IStreamRequestHandler<TRequest, TResponse> for async streams. Handling begins when enumeration starts.
public sealed record ListOrders : IStreamRequest<OrderDto>;
public sealed class ListOrdersHandler : IStreamRequestHandler<ListOrders, OrderDto>
{
public async IAsyncEnumerable<OrderDto> HandleAsync(
ListOrders request,
[System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken = default)
{
yield return new OrderDto(Guid.NewGuid(), "SO-001");
await Task.Delay(10, cancellationToken);
yield return new OrderDto(Guid.NewGuid(), "SO-002");
}
}
Resolve IStreamSender and call SendStream. ISender also inherits this method, so an existing sender can dispatch streams directly.
var streamSender = serviceProvider.GetRequiredService<IStreamSender>();
await foreach (var order in streamSender.SendStream(new ListOrders(), cancellationToken))
{
Console.WriteLine(order.Number);
}
Stream handlers support decorators too, via IStreamRequestDecorator.
builder.Services
.AddSendr()
.AddStreamRequestHandler<ListOrders, OrderDto, ListOrdersHandler>(x =>
x.Decorator.With<LoggingStreamDecorator>());
public sealed class LoggingStreamDecorator(ILogger<LoggingStreamDecorator> logger)
: IStreamRequestDecorator
{
public IAsyncEnumerable<TResponse> HandleAsync<TRequest, TResponse>(
TRequest request,
StreamHandlerDelegate<TResponse> next,
CancellationToken cancellationToken = default)
where TRequest : IStreamRequest<TResponse>
{
logger.LogInformation("Streaming {Request}", typeof(TRequest).Name);
return next();
}
}
A stream decorator that uses yield should wrap the enumeration in try/finally and forward the token via [EnumeratorCancellation] so cancellation and disposal propagate correctly.
Notifications
A notification can have any number of handlers, including zero. Define the event with INotification, implement each handler with INotificationHandler<TNotification>, and publish it through IPublisher.
public sealed record OrderPlaced(Guid OrderId) : INotification;
public sealed class ReserveInventoryHandler : INotificationHandler<OrderPlaced>
{
public Task HandleAsync(OrderPlaced notification, CancellationToken cancellationToken = default)
{
return Task.CompletedTask;
}
}
public sealed class SendConfirmationEmailHandler : INotificationHandler<OrderPlaced>
{
public Task HandleAsync(OrderPlaced notification, CancellationToken cancellationToken = default)
{
return Task.CompletedTask;
}
}
Call AddSendrNotification once, then register every handler for a notification type in a single AddNotificationHandler call, arranging them into a Sequence (run one after another in registration order, continuing after failures) and/or a Parallel group (run concurrently). The two groups run concurrently with each other, so a Parallel handler does not wait for the Sequence group to finish.
builder.Services
.AddSendrNotification()
.AddNotificationHandler<OrderPlaced>(x =>
{
x.Handler.Sequence.With<ReserveInventoryHandler>();
x.Handler.Parallel.With<SendConfirmationEmailHandler>();
});
Resolve IPublisher and call PublishAsync. It accepts the non-generic INotification, so you can publish a polymorphic batch, such as events from an outbox, without knowing each concrete type. Publishing a notification with no registered handlers is a no-op.
var publisher = serviceProvider.GetRequiredService<IPublisher>();
await publisher.PublishAsync(new OrderPlaced(order.Id), cancellationToken);
Each handler entry can have its own decorator pipeline via INotificationDecorator, configured the same way as request decorators.
builder.Services
.AddSendrNotification()
.AddNotificationHandler<OrderPlaced>(x => x.Handler.Sequence
.With<ReserveInventoryHandler>(h => h.Decorator.With<LoggingNotificationDecorator>()));
public sealed class LoggingNotificationDecorator(ILogger<LoggingNotificationDecorator> logger)
: INotificationDecorator
{
public async Task HandleAsync<TNotification>(
TNotification notification,
NotificationHandlerDelegate next,
CancellationToken cancellationToken = default)
where TNotification : INotification
{
logger.LogInformation("Handling {Notification}", typeof(TNotification).Name);
await next();
logger.LogInformation("Handled {Notification}", typeof(TNotification).Name);
}
}
Both groups run every handler even if an earlier handler fails. Sequence awaits handlers one at a time; Parallel starts them concurrently. PublishAsync collects all exceptions: a single exception is rethrown with its original stack trace, and multiple exceptions are combined into an AggregateException. Handlers share the calling DI scope, so Parallel handlers must not share a non-thread-safe scoped service such as a DbContext.
Call AddNotificationHandler<TNotification> once per notification type, with all handlers declared together so their Sequence order is explicit. A second call throws. Registration captures the configuration immediately; later changes to the object passed to configure have no effect.
Notification: source-generated registration (opt-in)
Davish.Sendr.Generators also discovers your INotificationHandler<T> implementations at compile time and generates UseGenerators(), a NotificationOptions extension that plugs into AddSendrNotification, backed by a reflection-free IPublisher.
Multiple classes can handle the same notification, so they do not trigger the duplicate-handler diagnostic (SENDR002). There is no per-handler execution-mode attribute. Instead, RunAs sets how handlers of the same notification execute throughout the generated publisher. The default is Sequence:
builder.Services.AddSendrNotification(o => o.UseGenerators());
// Or, to run same-notification handlers concurrently instead:
builder.Services.AddSendrNotification(o => o.UseGenerators(x => x.RunAs(NotificationRunMode.Parallel)));
Decorators are declared with [DecorateWith<...>] the same way, validated against INotificationDecorator:
[DecorateWith<LoggingNotificationDecorator>]
public sealed class ReserveInventoryHandler : INotificationHandler<OrderPlaced>
{
public Task HandleAsync(OrderPlaced notification, CancellationToken cancellationToken) { /* ... */ }
}
Notes:
RunAsselects sequential or concurrent execution. Neither mode guarantees the relative order of handlers for the same notification.- The generated publisher dispatches only to handlers discovered at compile time. Manual
AddNotificationHandlercalls do not extend its dispatch table; choose manual registration or generated registration for the publisher. - Generated and manual dispatch use
NotificationGroupRunner, with the same exception aggregation rules described above. GeneratedNotificationRunOptions.IncludeAssemblyOf<TMarker>()supports cross-assembly discovery and chains withRunAs:o.UseGenerators(x => x.RunAs(NotificationRunMode.Parallel).IncludeAssemblyOf<ApplicationAssemblyMarker>()). Its assembly set is independent of the one configured forAddSendr.
Learn more about Target Frameworks and .NET Standard.
-
.NETStandard 2.0
- No dependencies.
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.