MediatR — Simple Mediator Pattern for .NET

Introduction

MediatR is a simple, unambitious mediator implementation for .NET. It enables in-process message passing where requests are dispatched to a single handler, notifications are broadcast to multiple handlers, and pipeline behaviors wrap cross-cutting concerns around every request.

What MediatR Does

• Dispatches requests to their corresponding handlers without direct coupling
• Broadcasts notifications to all registered notification handlers
• Supports pipeline behaviors for cross-cutting concerns like logging and validation
• Integrates with Microsoft.Extensions.DependencyInjection for handler registration
• Enables CQRS patterns by separating command and query request types

Architecture Overview

MediatR uses the mediator design pattern where a central IMediator interface routes messages to handlers. At startup, it scans assemblies for IRequestHandler and INotificationHandler implementations and registers them in the DI container. Pipeline behaviors form a middleware chain around each request, similar to ASP.NET Core middleware but for application-level messages.

Self-Hosting & Configuration

• Install via NuGet: dotnet add package MediatR
• Register in DI: builder.Services.AddMediatR(cfg => cfg.RegisterServicesFromAssembly(typeof(Program).Assembly))
• Add pipeline behaviors for validation, logging, or caching
• Supports both request/response and notification message types
• Compatible with .NET 6 through .NET 9

Key Features

• Clean separation between request definition and handling logic
• Pipeline behaviors for composable cross-cutting concerns
• Support for streaming responses via IStreamRequest
• Polymorphic dispatch for notification handlers
• Minimal API surface with low learning curve

Comparison with Similar Tools

• Wolverine — full messaging framework with persistence and scheduling; heavier, broader scope
• MassTransit Mediator — in-process mediator within MassTransit; requires MassTransit dependency
• Brighter — command processor with support for external message brokers; more complex setup
• Raw DI interfaces — direct handler injection; tighter coupling, no pipeline behaviors
• Jimmy Bogard Vertical Slices — architectural pattern often paired with MediatR; not a library itself

FAQ

Q: Is MediatR the same as a message broker? A: No. MediatR is strictly in-process. It routes messages within a single application. For cross-service communication, use a message broker like RabbitMQ or Azure Service Bus.

Q: How do I add validation to MediatR requests? A: Create an IPipelineBehavior that runs FluentValidation validators before the handler executes. This keeps validation logic separate from business logic.

Q: Does MediatR support CQRS? A: MediatR itself does not enforce CQRS, but its request/handler pattern naturally maps to command and query separation. Define separate request types for commands and queries.

Q: What is the licensing model? A: MediatR v12.x is Apache-licensed. Version 13+ introduced a dual license with a free Community edition for individuals, non-profits, and educational use, plus a commercial license for enterprise use.

Sources

• https://github.com/jbogard/MediatR
• https://www.jimmybogard.com/mediatr-going-commercial/