Building clean request pipelines with MediatR in ASP.NET Core

ASP.NET Core developers working across Sydney, Melbourne and Brisbane have leaned hard into clean architecture as their delivery squads scale, and few libraries simplify cross-cutting concerns as gracefully as the mediator pattern. By inserting a thin dispatcher between the caller and the responder, the pattern pushes validation, logging and authorisation into reusable components, leaving controllers lean and intent obvious. The discipline pays off in codebases that ship new features every sprint while still obeying the regulator-driven security expectations that APRA and the ACSC publish for Australian financial and government systems.

MediatR, the open-source .NET library maintained by Jimmy Bogard, has quietly become the default choice for teams wanting an in-process implementation of the pattern. It hooks into ASP.NET Core's dependency injection container with a couple of lines in Program.cs, plays nicely with minimal APIs, and pairs with FluentValidation, Serilog and OpenTelemetry without ceremony. At recent .NET meetups in Melbourne and Perth, presenters regularly described how swapping a sprawling controller for a handful of request handlers shrank their test surfaces from days to hours.

This walkthrough shows how to add MediatR to an ASP.NET Core 8 solution, model requests and notifications, layer in pipeline behaviours, and keep everything testable. The samples target .NET 8, though the same ideas apply to .NET 6 and 7. Whether you are reshaping an ageing MVC monolith for a logistics client in Alexandria or building a greenfield service for a fintech team in Barangaroo, the patterns below should slot into your workflow without rewiring the rest of the stack.

The case for a mediator layer

Controllers in a typical ASP.NET Core Web API tend to grow unwieldy once they juggle input shaping, authorisation, auditing and repository calls. Each new responsibility adds a new dependency, and unit tests start to require mocks for half the application graph. Introducing a mediator inverts that growth: the controller hands a plain request object to the dispatcher and lets the pipeline do everything else. The handler becomes a single-purpose class that talks to the data layer and returns a result, a shape that maps neatly onto the Single Responsibility Principle auditors expect during ISO 27001 reviews that many Australian SaaS vendors pursue.

A second benefit surfaces when the same business operation has to be invoked from multiple entry points. A "create invoice" command might arrive through an HTTP controller, a Hangfire background job and an Azure Service Bus queue trigger. With the mediator pattern, each entry point calls the same handler, so the rules around GST calculation, duplicate detection and ATO-compliant invoice numbering stay in one place. That single source of truth becomes invaluable when the Australian Taxation Office updates its reporting requirements and the change has to ship to every channel at once.

Before going further, a quick map of MediatR's messaging primitives helps frame the rest of the article:

Knowing which primitive fits a scenario is half the battle. The remainder is wiring them up in a way that keeps handlers easy to test and behaviour ordering deterministic.

Wiring MediatR into an ASP.NET Core project

The setup is deliberately small. Add the NuGet packages to your application project, then register the dispatcher in Program.cs.

dotnet add package MediatR
dotnet add package MediatR.Extensions.Microsoft.DependencyInjection

In Program.cs, point MediatR at the assembly containing your handlers so it can resolve them through the container:

builder.Services.AddMediatR(cfg =>
    cfg.RegisterServicesFromAssemblyContaining<CreateInvoiceHandler>());

That single line scans the assembly, registers every IRequestHandler, INotificationHandler and IPipelineBehavior it finds, and wires them into a scoped lifetime. For larger solutions split across multiple projects, pass an array of assemblies to keep discovery explicit, which helps when working in regulated environments where audit trails must show exactly which assembly contributed a given service.

If you prefer composition over attribute-driven discovery, the same call accepts a Type parameter and the library exposes AddOpenBehavior for registering cross-cutting behaviours globally. Pair this with builder.Services.AddProblemDetails() and you get a uniform error contract for every handler, a pattern that ACCC-aligned consumer-facing APIs tend to favour.

Modelling requests, handlers and validators

A request is just a record. Define it next to the handler that fulfils it, and prefer positional parameters so the type doubles as documentation.

public record CreateInvoiceCommand(
    Guid CustomerId,
    decimal Amount,
    DateOnly IssuedOn,
    string Currency) : IRequest<Guid>;

The handler implements IRequestHandler<TRequest, TResponse> and receives the request through its constructor along with whatever dependencies it needs.

public class CreateInvoiceHandler : IRequestHandler<CreateInvoiceCommand, Guid>
{
    private readonly IInvoiceRepository _repository;

    public CreateInvoiceHandler(IInvoiceRepository repository) => _repository = repository;

    public async Task<Guid> Handle(CreateInvoiceCommand request, CancellationToken cancellationToken)
    {
        var invoice = Invoice.Create(request.CustomerId, request.Amount, request.IssuedOn, request.Currency);
        await _repository.AddAsync(invoice, cancellationToken);
        return invoice.Id;
    }
}

Validation fits naturally through a pipeline behaviour, but many teams still attach FluentValidation rules directly to each request record for readability. Either approach works; what matters is that invalid input is rejected before the handler runs, so business logic never has to defend itself against malformed arguments.

Broadcasting domain events with notifications

Some operations need to fan out. A confirmed order might trigger an email, an audit log entry and a sync push to a warehouse management system. INotification is designed for that pattern. Unlike a request, every registered handler gets invoked, the dispatcher does not wait for a particular response, and failures in one handler do not stop the others by default.

public record OrderConfirmedNotification(Guid OrderId, DateTimeOffset ConfirmedAt) : INotification;

public class EmailConfirmationHandler : INotificationHandler<OrderConfirmedNotification> { /* ... */ }
public class AuditLogHandler : INotificationHandler<OrderConfirmedNotification> { /* ... */ }

Publishing is a one-liner injected wherever the event originates:

await _mediator.Publish(new OrderConfirmedNotification(order.Id, DateTimeOffset.UtcNow), cancellationToken);

This shape is useful when integrating with Australian third parties such as Australia Post's tracking APIs or the Australian Energy Market Operator's data feeds. The mediator lets you add a new subscriber without touching the producer, which keeps change sets small and reviewable across distributed teams in Adelaide, Brisbane and Hobart.

Pipeline behaviours for cross-cutting concerns

Pipeline behaviours wrap every request and notification, making them the right place for logging, validation, performance tracing and the security headers mandated by the Australian Cyber Security Centre's Essential Eight. A typical behaviour looks like this:

public class LoggingBehavior<TRequest, TResponse> : IPipelineBehavior<TRequest, TResponse>
    where TRequest : IRequest<TResponse>
{
    private readonly ILogger<LoggingBehavior<TRequest, TResponse>> _logger;

    public LoggingBehavior(ILogger<LoggingBehavior<TRequest, TResponse>> logger) => _logger = logger;

    public async Task<TResponse> Handle(TRequest request, RequestHandlerDelegate<TResponse> next, CancellationToken cancellationToken)
    {
        _logger.LogInformation("Handling {Request}", typeof(TRequest).Name);
        var response = await next();
        _logger.LogInformation("Handled {Request}", typeof(TRequest).Name);
        return response;
    }
}

Register it globally with cfg.AddOpenBehavior(typeof(LoggingBehavior<,>)). Order matters: validation usually goes first, logging next, then any performance or caching behaviour. Keep each behaviour focused on one responsibility so they remain composable and individually testable. In larger teams, separating behaviours into a dedicated project also gives reviewers a single, easy-to-read pull request when something has to change ahead of a Notifiable Data Breaches scheme audit.

Testing strategies and production lessons from the field

Handlers are trivially testable because they are plain classes with explicit dependencies. A typical xUnit test constructs the handler, supplies a fake repository, sends a request and asserts on the result. Notifications are slightly trickier because several handlers fire in parallel; capture each handler's output in a list and assert on the aggregated state.

Two habits pay dividends in production. First, treat request records as immutable contracts and version them explicitly when fields change, mirroring the discipline Australian banks apply to their public API tiers. Second, instrument the mediator pipeline with OpenTelemetry so the Australian Digital Transformation Agency's observability guidelines are satisfied out of the box. With those two practices in place, a MediatR-based API delivers clean architecture, predictable performance and a story auditors recognise, which is exactly what regulators, customers and engineering leaders want when a system scales from a single squad in Sydney to a multi-region rollout across the Asia-Pacific.