MediatR for C# (.NET): Complete Guide with Examples

What is MediatR and why is it needed?

MediatR is a lightweight yet powerful library for .NET that implements the Mediator pattern. In the world of software development, especially in applications built on the CQRS (Command Query Responsibility Segregation) architecture, MediatR has become the de facto standard.

Why is it needed?

In classical architecture, when one class (e.g., a controller) wants to perform an action in another class (e.g., a service), it must know about the existence of that service and its interface. This creates tight coupling. If you want to add logging, validation, or caching before calling the service, you would have to modify the controller code or create decorators, which complicates maintenance.

MediatR solves this problem by introducing the concept of a mediator. System components (e.g., controllers) no longer communicate directly. Instead, they send Requests or Commands through MediatR. The library itself finds and invokes the corresponding Handler.

Key advantages of using MediatR:

• Loose Coupling: The request sender knows nothing about the receiver. It only knows about the request type.
• Single Responsibility Principle (SRP): Each handler is responsible for only one action (e.g., "Create User", "Get Order List").
• Simplified CQRS: MediatR is ideal for separating commands (changing state) and queries (reading state).
• Pipeline Behaviors: You can easily add cross-cutting functionality (logging, validation, transactions) without changing handler code.
• Testability: Handlers are easy to test in isolation, and their implementations can be easily swapped.

Installing MediatR

MediatR is distributed via NuGet. You can install it in several ways:

1. Via .NET CLI (recommended)

Open a terminal in the root of your project and run the command:

dotnet add package MediatR

You will also need the dependency injection (DI) package if you are using ASP.NET Core:

dotnet add package MediatR.Extensions.Microsoft.DependencyInjection

2. Via Package Manager Console (Visual Studio)

Install-Package MediatRInstall-Package MediatR.Extensions.Microsoft.DependencyInjection

3. Via NuGet Package Manager UI

In Visual Studio: Tools → NuGet Package Manager → Manage NuGet Packages for Solution.... Search for "MediatR" and install both packages.

Quick Start with Code Example

Let's create a simple example: sending a greeting to a user.

Step 1: Create a Project

Create a new console project or an ASP.NET Core Web API project.

Step 2: Define the Request

Create a class that represents the request. It must implement the IRequest<TResponse> interface, where TResponse is the return type.

using MediatR;

public class PingRequest : IRequest<string>{    public string Message { get; set; } = "Ping";}

Step 3: Create the Handler

Create a class that implements the IRequestHandler<TRequest, TResponse> interface.

using MediatR;using System.Threading;using System.Threading.Tasks;

public class PingHandler : IRequestHandler<PingRequest, string>{    public Task<string