IronAlpine.Framework.Mediator 3.1.1

IronAlpine.Framework.Mediator

In-process mediator for requests (commands/queries), notifications and streams, with an explicit, ordered pipeline and FluentValidation integration.

• Package id: IronAlpine.Framework.Mediator (3.1.1, net10.0)
• Depends on: IronAlpine.Framework.Kernel, FluentValidation 12
• INotification and IDomainEvent live in the Kernel (IronAlpine.Kernel.Primitives).

Installation

<PackageReference Include="IronAlpine.Framework.Mediator" Version="3.1.1" />

Registration

using IronAlpine.Mediator.Extensions;

services.AddIronAlpineMediator(cfg =>
{
    cfg.RegisterServicesFromAssemblyContaining<CreateOrderCommandHandler>();
    cfg.UseValidationBehavior(typeof(CreateOrderCommandHandler).Assembly);
});

AddIronAlpineMediator throws if no assembly is registered. It registers:

Two request handlers (or two stream handlers) for the same request/response pair throw at registration. Notification handlers can be many.

Configuration API (IronAlpineMediatorConfiguration)

Other packages add behaviour shortcuts as extension methods on the same configuration object:

Pipeline order

Behaviours run in the order they are registered: the first registered behaviour is the outermost. The recommended order is:

services.AddIronAlpineMediator(cfg =>
{
    cfg.RegisterServicesFromAssembly(applicationAssembly);
    cfg.UseLoggingBehavior();                 // 1. log every request, including cache hits and validation failures
    cfg.UseCachingBehavior();                 // 2. return cached query results before any other work
    cfg.UseValidationBehavior(applicationAssembly); // 3. reject invalid requests
    cfg.UseAuditingBehavior();                // 4. write an audit row for IAuditableCommand requests
    cfg.UseResultAwareTransactionBehavior();  // 5. one DB transaction around the handler
});

Behaviours apply only to Send (requests). Publish (notifications, domain events, integration events received from the event bus) does not go through IPipelineBehavior.

A behaviour whose generic constraints do not match a request (for example CachingBehavior requires ICacheableQuery) is skipped for that request.

Requests and handlers

using IronAlpine.Kernel.Results;
using IronAlpine.Mediator.Contracts;

public sealed record CreateOrderCommand(Guid CustomerId, IReadOnlyList<OrderLineDto> Lines) : IRequest<Result<Guid>>;

public sealed class CreateOrderCommandHandler(IRepository<Order> orders, IUnitOfWork unitOfWork)
    : IRequestHandler<CreateOrderCommand, Result<Guid>>
{
    public async Task<Result<Guid>> Handle(CreateOrderCommand request, CancellationToken cancellationToken)
    {
        var order = Order.Create(request.CustomerId);
        orders.Add(order);
        await unitOfWork.SaveChangesAsync(cancellationToken);
        return Result.Success(order.Id);
    }
}

// caller
Result<Guid> result = await sender.Send(new CreateOrderCommand(customerId, lines), ct);
object? untyped = await sender.Send((object)command, ct);   // resolves the response type at runtime

IRequest<TResponse> is the only request contract; many applications define their own marker interfaces on top of it (for example ICommand : IRequest<Result> and IQuery<T> : IRequest<Result<T>>) to distinguish commands from queries in custom behaviours. A missing handler throws RequestHandlerNotFoundException (IronAlpine.Mediator.Errors).

Validation

using FluentValidation;

public sealed class CreateOrderCommandValidator : AbstractValidator<CreateOrderCommand>
{
    public CreateOrderCommandValidator()
    {
        RuleFor(x => x.CustomerId).NotEmpty();
        RuleFor(x => x.Lines).NotEmpty();
    }
}

ValidationBehavior<TRequest, TResponse> (requires TResponse : class):

• runs every IValidator<TRequest> registered for the request (validators are scoped, internal types included);
• when invalid and TResponse is Result or Result<T>, returns Result.Failure(Error.ValidationError(errors)) - code Validation.Failed, ErrorType.Validation, one ValidationError(PropertyName, ErrorMessage) per failure (FluentValidation error codes are not copied);
• for any other response type throws FluentValidation.ValidationException;
• requests without validators pass through.

Replace the FluentValidation adapter by registering your own IRequestValidator<TRequest> (returns a ValidationSummary) before AddIronAlpineMediator.

Notifications

using IronAlpine.Kernel.Primitives;

public sealed record OrderShippedNotification(Guid OrderId) : INotification;

public sealed class SendShipmentMailHandler : INotificationHandler<OrderShippedNotification>
{
    public Task Handle(OrderShippedNotification notification, CancellationToken cancellationToken) => Task.CompletedTask;
}

await publisher.Publish(new OrderShippedNotification(orderId), ct);
await publisher.Publish((object)notification, ct);   // throws ArgumentException if it is not an INotification

• Sequential: handlers run one after another in registration order; the first exception stops the rest.
• ParallelWhenAll: all handlers start at once. They share the same DI scope, so do not use it when handlers use the same scoped DbContext.
• No handler registered: Publish completes without error.

Streams

public sealed record ExportOrdersRequest(DateOnly From) : IStreamRequest<OrderRow>;

public sealed class ExportOrdersHandler : IStreamRequestHandler<ExportOrdersRequest, OrderRow>
{
    public async IAsyncEnumerable<OrderRow> Handle(
        ExportOrdersRequest request,
        [EnumeratorCancellation] CancellationToken cancellationToken)
    {
        yield return new OrderRow(Guid.NewGuid(), 10m);
        await Task.CompletedTask;
    }
}

await foreach (var row in sender.CreateStream(new ExportOrdersRequest(from), ct))
{
    // ...
}

Stream behaviours implement IStreamPipelineBehavior<TRequest, TResponse> and are added with AddOpenStreamBehavior.

Custom behaviours

public sealed class TimingBehavior<TRequest, TResponse>(ILogger<TimingBehavior<TRequest, TResponse>> logger)
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : IRequest<TResponse>
{
    public async Task<TResponse> Handle(TRequest request, RequestHandlerDelegate<TResponse> next, CancellationToken cancellationToken)
    {
        var started = Stopwatch.GetTimestamp();
        var response = await next();
        logger.LogDebug("{Request} took {Elapsed} ms", typeof(TRequest).Name, Stopwatch.GetElapsedTime(started).TotalMilliseconds);
        return response;
    }
}

services.AddIronAlpineMediator(cfg =>
{
    cfg.RegisterServicesFromAssembly(applicationAssembly);
    cfg.AddOpenBehavior(typeof(TimingBehavior<,>));
});

Add generic constraints (for example where TRequest : IMyCommandMarker) to restrict a behaviour to some requests.

Pitfalls

• UseValidationBehavior() without assemblies scans the assemblies registered with RegisterServicesFromAssembly(...) for validators (since 3.0.5; up to 3.0.4 it registered no IRequestValidator<> and every Send failed). Pass assemblies explicitly when validators live elsewhere; then only those assemblies are scanned.
• Call AddIronAlpineMediator once per service collection; a second call adds the behaviours and handlers again.
• Behaviours do not run for notifications. Logging, validation, caching and transactions are not applied to INotificationHandler<T> code.
• Handler wrappers are cached per request type for the process lifetime; handlers themselves are resolved from the current scope on every call.