As applications scale, controllers often fall victim to the "fat controller" anti-pattern. They accumulate hundreds of lines of code, mixing business logic, database queries, DTO mapping, and validation rules into a single unmaintainable file. Furthermore, traditional CRUD approaches treat reads and writes the same way, even though reads usually require optimized projections and writes require strict business rule validation.
To solve this, modern enterprise systems pair Clean Architecture with CQRS (Command Query Responsibility Segregation) and MediatR.
In this comprehensive guide, we will explore how CQRS and MediatR work together to decouple your application layers, keep your controllers razor-thin, and make your codebase exceptionally testable and scalable.
What is CQRS and MediatR?
CQRS: Splits your data operations into two distinct categories:
Commands: Write operations that mutate state (Create, Update, Delete) and typically return nothing or an ID.
Queries: Read operations that fetch data without modifying state and return DTOs.
MediatR: An implementation of the Mediator pattern in .NET. It facilitates in-process messaging, decoupling your API controllers from your business logic handlers so that controllers simply act as thin dispatchers.
Step 1: Install MediatR in the Application Layer
Commands and queries belong in your Application layer because they represent business use cases.
Navigate to your YourSolution.Application project and install the core MediatR package:
Bash
dotnet add package MediatR
(Note: In modern versions of MediatR, dependency injection extensions are bundled directly into the core package).
Step 2: Organize by Feature Folders
Instead of grouping files by technical role (putting all services together or all classes together), organize your Application layer by features. This keeps everything related to a specific domain action localized:
Plaintext
YourSolution.Application/
├── Features/
│ └── Products/
│ ├── Commands/
│ │ ├── CreateProductCommand.cs
│ │ └── CreateProductCommandHandler.cs
│ └── Queries/
│ ├── GetProductByIdQuery.cs
│ └── GetProductByIdQueryHandler.cs
└── DependencyInjection.cs
Step 3: Implement a Command (Write Operation)
Commands represent actions that change state. We use C# record types for immutability, paired with a dedicated handler that executes the logic.
1. The Command Record
C#
using MediatR;
namespace YourSolution.Application.Features.Products.Commands
{
public record CreateProductCommand(string Name, decimal Price) : IRequest<Guid>;
}
2. The Command Handler
The handler contains the business rules and interacts with domain entities and repository interfaces.
C#
using MediatR;
using YourSolution.Domain.Entities;
using YourSolution.Domain.Interfaces;
namespace YourSolution.Application.Features.Products.Commands
{
public class CreateProductCommandHandler : IRequestHandler<CreateProductCommand, Guid>
{
private readonly IProductRepository _productRepository;
public CreateProductCommandHandler(IProductRepository productRepository)
{
_productRepository = productRepository;
}
public async Task<Guid> Handle(CreateProductCommand request, CancellationToken cancellationToken)
{
// 1. Instantiate domain entity (encapsulating business rules)
var product = new Product(request.Name, request.Price);
// 2. Persist via repository interface
await _productRepository.AddAsync(product);
await _productRepository.UnitOfWork.SaveChangesAsync(cancellationToken);
// 3. Return the generated ID
return product.Id;
}
}
}
Join the conversation! Your thoughts help the community grow.