ModulusKit.Mediator 4.0.0

Modulus.Mediator

Lightweight CQRS mediator for .NET with pipeline behaviors, validation, logging, and a built-in Result pattern.

Installation

dotnet add package ModulusKit.Mediator

Setup

services.AddModulusMediator();
services.AddModulusHandlers(); // source-generated — registers all handlers and validators

// Add built-in pipeline behaviors (order matters — first registered = outermost).
services.AddPipelineBehavior(typeof(UnhandledExceptionBehavior<,>));
services.AddPipelineBehavior(typeof(LoggingBehavior<,>));
services.AddPipelineBehavior(typeof(MetricsBehavior<,>));
services.AddPipelineBehavior(typeof(ValidationBehavior<,>));
services.AddPipelineBehavior(typeof(UnitOfWorkBehavior<,>));

AddModulusMediator() takes no arguments — it registers only the IMediator itself. Handler registration comes from the source-generated AddModulusHandlers() extension method, which the ModulusKit.Generators package emits at compile time for every handler and validator in the compilation (ICommandHandler<>, IQueryHandler<,>, IStreamQueryHandler<,>, IDomainEventHandler<>, AbstractValidator<>). Reference the generator in each project that defines handlers:

<PackageReference Include="ModulusKit.Generators" OutputItemType="Analyzer" ReferenceOutputAssembly="false" />

Solutions scaffolded by the modulus CLI have this wired up already.

Usage

Define a command and handler

public record CreateOrder(string CustomerId, List<OrderItem> Items) : ICommand<Guid>;

public class CreateOrderHandler : ICommandHandler<CreateOrder, Guid>
{
    public async Task<Result<Guid>> Handle(CreateOrder command, CancellationToken ct)
    {
        var order = Order.Create(command.CustomerId, command.Items);
        await _repository.Add(order, ct);
        return Result<Guid>.Success(order.Id);
    }
}

Define a query and handler

public record GetOrderById(Guid Id) : IQuery<OrderDto>;

public class GetOrderByIdHandler : IQueryHandler<GetOrderById, OrderDto>
{
    public async Task<Result<OrderDto>> Handle(GetOrderById query, CancellationToken ct)
    {
        var order = await _repository.GetById(query.Id, ct);
        if (order is null)
            return Error.NotFound("Order.NotFound", "Order was not found");

        return Result<OrderDto>.Success(order.ToDto());
    }
}

Send commands and queries

var result = await mediator.Send(new CreateOrder("cust-1", items));

if (result.IsSuccess)
    Console.WriteLine($"Created order: {result.Value}");
else
    Console.WriteLine($"Failed: {result.Errors[0].Description}");

Pipeline Behaviors

Behaviors wrap every request in a middleware-style pipeline. They execute in registration order (first registered = outermost):

Custom behaviors

Implement IPipelineBehavior<TRequest, TResponse> and register it. Behaviors execute in registration order (first registered = outermost):

public sealed class AuditBehavior<TRequest, TResponse>(IAuditWriter audit)
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : notnull
    where TResponse : Result
{
    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken cancellationToken)
    {
        var response = await next(cancellationToken).ConfigureAwait(false);
        if (response.IsSuccess)
            await audit.RecordAsync(typeof(TRequest).Name, cancellationToken).ConfigureAwait(false);
        return response;
    }
}

services.AddPipelineBehavior(typeof(AuditBehavior<,>));

Using UnitOfWorkBehavior

Implement IUnitOfWork (typically on your DbContext) and register it:

public class AppDbContext : DbContext, IUnitOfWork
{
    // SaveChangesAsync on DbContext already satisfies IUnitOfWork
}

services.AddScoped<IUnitOfWork>(sp => sp.GetRequiredService<AppDbContext>());
services.AddPipelineBehavior(typeof(UnitOfWorkBehavior<,>));

If no IUnitOfWork is registered, the behavior is a no-op — safe to include in every scaffold.

Domain Events

public record OrderPlaced(Guid OrderId, string CustomerId) : IDomainEvent;

public class OrderPlacedHandler : IDomainEventHandler<OrderPlaced>
{
    public async Task Handle(OrderPlaced domainEvent, CancellationToken ct)
    {
        // React to the event
    }
}

// Publish
await mediator.Publish(new OrderPlaced(order.Id, order.CustomerId));

Publish Strategies

By default, Publish dispatches to every registered handler sequentially, collecting failures into a single AggregateException. Configure a different strategy at registration:

services.AddModulusMediator(options =>
{
    options.PublishStrategy = PublishStrategy.Parallel; // or StopOnFirstFailure
});

Not configuring MediatorOptions (or registering IMediator by hand instead of via AddModulusMediator) keeps the pre-4.0 default: Sequential. See Domain Events for the full semantics.

Learn More

See the Modulus repository for full documentation.