Mediator Pattern in .NET with MediatR

The Mediator pattern in .NET Core is a behavioral design pattern that reduces coupling between components by forcing them to communicate indirectly through a central "mediator" object. Instead of classes having direct references to each other, they send messages to the mediator, which then routes them to the appropriate handlers. 

Why Use It?

• Decoupling: Objects don't need to know about each other's existence or implementation details.
• Slim Controllers: In ASP.NET Core, it keeps API controllers thin by moving business logic into separate "handler" classes.
• Maintainability: Centralizing communication logic makes it easier to modify or extend individual components without ripple effects.
• CQRS Support: It is the standard way to implement Command Query Responsibility Segregation (CQRS), where "Commands" (writes) and "Queries" (reads) are handled separately

The Standard Implementation: MediatR

While you can build your own mediator, the MediatR NuGet package is the industry standard for .NET applications. 

1. Request/Command: A simple class representing the action you want to perform (e.g., CreateUserCommand).
2. Handler: A class implementing IRequestHandler<TRequest, TResponse> that contains the actual business logic.
3. The Mediator: An IMediator instance (injected via Dependency Injection) that sends the request to the correct handler.

 

In the .NET ecosystem, the most popular implementation of the Mediator pattern is MediatR.

In this article, you’ll learn:

• What the Mediator Pattern is
• Why it matters
• Problems it solves
• How MediatR works internally
• Commands & Queries
• Real-world architecture flow
• Advantages and disadvantages
• Best practices
• Full CRUD implementation strategy

---

What is the Mediator Pattern?

The Mediator Pattern is a behavioral design pattern that allows objects to communicate through a central mediator instead of communicating directly with each other.

Instead of this:

Controller → Service → Repository → Logger → Cache

You introduce a mediator:

Controller → Mediator → Handler

The mediator becomes the central communication hub.

---

Real-World Example

Imagine an airport.

Pilots do not directly coordinate with one another.

Instead:

Pilot → Air Traffic Controller → Another Pilot

The Air Traffic Controller acts as the mediator.

Similarly in software:

Controller → Mediator → Handler

The controller sends requests to the mediator, and the mediator routes those requests to the correct handler.

---

Why Traditional Architectures Become Problematic

In many ASP.NET applications, controllers become overloaded with dependencies.

Example:

public class GroupController : ControllerBase
{
    private readonly IGroupService _groupService;
    private readonly ILoggerService _logger;
    private readonly IEmailService _email;
    private readonly ICacheService _cache;
    private readonly IAuditService _audit;
}

Problems with this approach:

• Tight coupling
• Large controllers
• Hard unit testing
• Difficult maintenance
• Business logic spread everywhere
• Increasing complexity over time

As applications grow, these issues become severe.

---

How Mediator Solves This

Using MediatR, the controller only depends on one object:

public class GroupController : ControllerBase
{
    private readonly IMediator _mediator;
}

Now the controller becomes extremely clean.

Instead of handling logic directly:

await _mediator.Send(command);

The mediator decides which handler should process the request.

---

Core Components of the Mediator Pattern

The Mediator pattern in .NET generally contains these components:

Component	Responsibility
Controller	Receives HTTP requests
Mediator	Routes requests
Command / Query	Represents an action
Handler	Executes business logic
Repository / DbContext	Accesses database

---

Understanding Commands and Queries (CQRS)

Mediator is commonly used with CQRS (Command Query Responsibility Segregation).

CQRS separates:

• Read operations
• Write operations

---

Commands

Commands modify data.

Examples:

• Create
• Update
• Delete

Example:

public record CreateGroupCommand(
    string Name,
    string Description
) : IRequest<Group>;

This means:

“Create a new group.”

---

Queries

Queries only read data.

Examples:

• GetAll
• GetById

Example:

public record GetAllGroupsQuery() : IRequest<List<Group>>;

This means:

“Fetch all groups.”

---

How MediatR Works Internally

Here’s the actual request flow.

---

Step 1 — HTTP Request Arrives

POST /api/group

---

Step 2 — Controller Receives Request

[HttpPost]
public async Task<IActionResult> Create(CreateGroupCommand command)
{
    var result = await _mediator.Send(command);

    return Ok(result);
}

The controller does not know how the group is created.

It simply sends the command.

---

Step 3 — Mediator Finds Correct Handler

MediatR automatically maps:

CreateGroupCommand
        ↓
CreateGroupHandler

---

Step 4 — Handler Executes Logic

public class CreateGroupHandler
    : IRequestHandler<CreateGroupCommand, Group>
{
    private readonly AppDbContext _context;

    public async Task<Group> Handle(
        CreateGroupCommand request,
        CancellationToken cancellationToken)
    {
        var group = new Group
        {
            Name = request.Name,
            Description = request.Description
        };

        _context.Groups.Add(group);

        await _context.SaveChangesAsync();

        return group;
    }
}

---

Step 5 — Response Returned

{
  "id": 1,
  "name": "Admin Group",
  "description": "System administrators"
}

---

Typical Mediator Folder Structure

A clean structure usually looks like this:

Features
 └── Groups
      ├── Commands
      │     ├── CreateGroup
      │     ├── UpdateGroup
      │     └── DeleteGroup
      │
      ├── Queries
      │     ├── GetAllGroups
      │     └── GetGroupById

This is called:

• Feature-based architecture
• Vertical slice architecture

---

Example CRUD Flow

---

Create Operation

Command

public record CreateGroupCommand(
    string Name,
    string Description
) : IRequest<Group>;

Handler

public class CreateGroupHandler
    : IRequestHandler<CreateGroupCommand, Group>
{
}

---

Read Operation

Query

public record GetAllGroupsQuery()
    : IRequest<List<Group>>;

Handler

public class GetAllGroupsHandler
    : IRequestHandler<GetAllGroupsQuery, List<Group>>
{
}

---

Update Operation

Command

public record UpdateGroupCommand(
    int Id,
    string Name,
    string Description
) : IRequest<bool>;

---

Delete Operation

Command

public record DeleteGroupCommand(int Id)
    : IRequest<bool>;

---

Benefits of Using Mediator Pattern

---

1. Loose Coupling

Without mediator:

Controller → Multiple Services

With mediator:

Controller → Mediator

Classes become independent.

---

2. Clean Controllers

Controllers stay very small.

Example:

await _mediator.Send(command);

instead of hundreds of lines of business logic.

---

3. Better Separation of Concerns

Each handler does exactly one job.

Examples:

CreateGroupHandler
UpdateGroupHandler
DeleteGroupHandler

This follows the Single Responsibility Principle.

---

4. Easier Unit Testing

Handlers can be tested independently.

Example:

[Test]
public async Task Should_Create_Group()
{
}

No need to instantiate full controllers.

---

5. Scalable Architecture

Mediator works extremely well for:

• Enterprise applications
• Microservices
• Clean Architecture
• Domain-Driven Design
• CQRS systems

---

6. Better Maintainability

Because logic is separated into handlers:

• Easier debugging
• Easier feature additions
• Easier refactoring

---

Advanced MediatR Features

---

1. Pipeline Behaviors

Behaviors work like middleware for requests.

Used for:

• Validation
• Logging
• Authentication
• Performance monitoring
• Transactions

Example:

Request
   ↓
ValidationBehavior
   ↓
LoggingBehavior
   ↓
Handler

---

2. Notifications

MediatR supports publish/subscribe patterns.

Example:

await _mediator.Publish(new UserCreatedNotification());

Multiple handlers can react to the same event.

Useful for:

• Sending emails
• Auditing
• Logging
• Cache invalidation

---

3. Request/Response Pattern

Most common usage:

await _mediator.Send(request);

---

Mediator Pattern in Clean Architecture

Mediator is heavily used in Clean Architecture.

Flow:

API Layer
   ↓
Application Layer
   ↓
Mediator
   ↓
Handlers
   ↓
Infrastructure Layer
   ↓
Database

This keeps layers independent.

---

Common Mistakes Developers Make

---

1. Putting Business Logic in Controllers

Wrong:

[HttpPost]
public async Task<IActionResult> Create()
{
    // huge logic
}

Correct:

await _mediator.Send(command);

---

2. Creating Fat Handlers

Handlers should focus on one use case only.

Avoid giant handlers.

---

3. Using Mediator for Tiny Applications

Mediator introduces additional files and complexity.

For very small CRUD apps, it may be unnecessary.

---

Disadvantages of Mediator Pattern

---

1. More Files

Mediator-based systems generate many files:

Command
Query
Handler
Validator
DTO
Behavior

---

2. Learning Curve

Beginners often struggle to understand:

• Requests
• Handlers
• Pipeline behaviors
• CQRS concepts

---

3. Indirection

Flow becomes less obvious because logic is separated into many classes.

---

When Should You Use Mediator?

Mediator is excellent for:

• Medium to large applications
• Enterprise APIs
• Complex business logic
• Microservices
• Scalable systems

Avoid using it for:

• Tiny applications
• Simple prototypes
• Very small CRUD projects

---

Best Practices

---

Keep Handlers Small

One handler = one responsibility.

---

Use Feature-Based Structure

Instead of organizing by type:

Controllers
Services
Repositories

Prefer:

Features
 └── Groups

---

Add Validation

Use libraries like:

• FluentValidation

for validating commands before execution.

---

Use DTOs

Avoid exposing entities directly.

---

Use Pipeline Behaviors

Centralize:

• Validation
• Logging
• Error handling

---

Simple Mental Model

Remember this:

Controller = What happened
Mediator = Who handles it
Handler = How it works

---

Final Thoughts

The Mediator pattern is one of the most powerful architectural patterns in modern .NET applications.

Using MediatR helps developers build:

• Clean APIs
• Scalable systems
• Maintainable applications
• Loosely coupled architectures

Although it introduces additional structure and files, the long-term benefits become extremely valuable as applications grow.

If you're building enterprise-grade ASP.NET Core applications, understanding and mastering the Mediator pattern is an important step toward writing professional, scalable software