Covers manual registration for requests, commands, and queries. For streams, see the “Streams” section below. For the source-generated alternative, see Enabling source generation. Background on how these kinds relate is in Dispatch model.

Requests

IRequest for a command with no return 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;
    }
}

IRequest<TResponse> for request/response:

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"));
    }
}

Register both, then dispatch through ISender:

builder.Services
    .AddSendr()
    .AddRequestHandler<CreateOrder, CreateOrderHandler>()
    .AddRequestHandler<GetOrder, OrderDto, GetOrderHandler>();

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 separate contracts from IRequest, with their own handler interfaces (ICommandHandler, IQueryHandler) and registration methods (AddCommandHandler, AddQueryHandler). Use them when the codebase wants an explicit CQRS vocabulary instead of the general-purpose IRequest.

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"));
    }
}
builder.Services
    .AddSendr()
    .AddCommandHandler<CreateOrder, CreateOrderHandler>()
    .AddQueryHandler<GetOrder, OrderDto, GetOrderHandler>();

Call sites still use ISender.SendAsync — it selects the IRequest, ICommand, or IQuery overload from the argument’s static type, so callers don’t need to track which kind a message belongs to.

Streams

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");
    }
}
builder.Services
    .AddSendr()
    .AddStreamRequestHandler<ListOrders, OrderDto, ListOrdersHandler>();

var streamSender = serviceProvider.GetRequiredService<IStreamSender>();

await foreach (var order in streamSender.SendStream(new ListOrders(), cancellationToken))
{
    Console.WriteLine(order.Number);
}

ISender also implements IStreamSender, so an existing ISender instance can dispatch streams directly without resolving IStreamSender separately.

Errors

  • Registering a second handler for the same request/response pair (via any of AddRequestHandler, AddCommandHandler, AddQueryHandler, or AddStreamRequestHandler) throws InvalidOperationException.
  • Dispatching a request with no registered handler throws InvalidOperationException, naming the missing registration call in its message. For streams, this happens when enumeration starts, not when SendStream is called.

See Exceptions and diagnostics for the exact messages.