Mediator Pattern in ASP.NET Core Applications

Send commands, fetch queries, and broadcast events using a mediator pattern for CQRS+ES

João Simões
Oct 28, 2020 · 7 min read

or the last few years, Command Query Responsibility Segregation (CQRS) and Event Sourcing (ES) emerged as patterns that can help implement large scale systems, with some risky complexity, by having different models to read or mutate data while also using events as a single source of truth.

Since there are already great articles explaining CQRS or ES in great depth, I’m going to focus and show how you can decouple your application layers by only knowing POCOs and a mediator instance from SimpleSoft.Mediator.

Remember that, even if you are not using CQRS or ES to its full extend, just by ensuring a logical model segregation inside the project can make your life easier in the long run, even when implementing a simple Backend for Frontend (BFF) or a minimum viable product (MVP).

Commands, Queries, Events, Handlers and Mediator

Before showing some code, lets make a simple review of some core concepts about these patterns and the library we are going to use:

  • Commands — each action intended to change the system state, by creating, updating or deleting information, should be represented by a class implementing either ICommand or ICommand<TResult>, if you are using the mediator just for in-process decoupling and want to return a result synchronously. Examples: CreateProductCommand or DeleteUserCommand
  • Queries — classes implementing IQuery<TResult> represent data reads that shouldn’t change the system state or else they must be considered commands. Examples: GetProductByIdQuery or SearchUsersQuery
  • Events — representing system changes over time, these classes implement IEvent. Examples: ProductCreatedEvent or UpdatedUserEmailEvent
  • Handlers — responsible for receiving the commands (ICommandHandler), queries (IQueryHandler) or events (IEventHandler), they implement the business behavior to be run. Examples: CreateProductCommandHandler or GetProductByIdQueryHandler
  • Mediator — decouples the caller from the executor exposing generic methods to send commands, fetch queries or broadcast events, being responsible for finding the correct handler (or handlers, in case of an event) and is represented by the interface IMediator.

I also made articles explaining how pipelines work, how to enforce validations, how to manage transactions and how to audit user actions.

The project

The source code for this article can be found on GitHub.

Start by opening Visual Studio and creating an ASP.NET Core 3.1 Web Application with a name and at any location.

Choose an empty project since this is just a demo.

Install the Nuget Swashbuckle.AspNetCore so we can use Swagger to test the API:

Open the file Startup.cs and configure both MVC and Swagger, making it easier to test our web API.

The web API

Since the objective of this article is to show the mediator pattern, a simple endpoint to manage products should be enough:

  • GET /products — search for products using some filters;
  • GET /products/{id} — get a product by its unique identifier;
  • POST /products — create a product;
  • PUT /products/{id} — update a product by its unique identifier;
  • DELETE /products/{id} — delete a product by its unique identifier;

Create a Controllers folder with another Products folder inside, a ProductsController and the following models:

The project should look as follows:

Open the Swagger endpoint (ex: https://localhost:44380/swagger/index.html) and you should see your products endpoint with all the actions:

The database model

For demo purposes we are going to use Entity Framework Core with data stored in-memory.

Install the Nuget Microsoft.EntityFrameworkCore.InMemory:

Create a Database folder, the following database context and entities for products and events, to store both the business data and mutations history:

Open the Startup.cs file and add the context into the container as an in-memory database:

services.AddDbContext<ApiDbContext>(o =>

The project should look as follows:

The mediator

Now that we have created the demo endpoint, models and database, its time to configure the mediator.

Install the Nuget SimpleSoft.Mediator.Microsoft.Extensions which is a specialized package for projects using Microsoft.Extensions.*:

Open the Startup.cs file and add the mediator into the container, scanning the current assembly for all classes implementing ICommandHandler, IQueryHandler and IEventHandler:

services.AddMediator(o =>

Open the ProductsController.cs file and inject into the constructor the IMediator instance:

private readonly IMediator _mediator;public ProductsController(IMediator mediator)
_mediator = mediator;

The handlers

We now have everything we need to start implementing the business logic.

To keep it simple, we are not going to use the mediator pipelines, only focusing on commands, queries, events and their handlers. As stated before, I made some articles more specific for those use cases.

Start by creating a folder named Handlers with another inside Products in which we are going to put our POCOs and their handlers.

As a note, remember this is a demo article and this project structure should not be seen as a valid way to organize your solution in your private projects. Commands, queries, events and their handlers should be, at minimum, in different folders.


We need data so lets create a command that allows that and will be sent when a request for POST /products is received.

Create a class CreateProductResult that will be returned by the handler with the product unique identifier and a CreateProductCommand, implementing the class Command<CreateProductResult>:

Open the ProductsController.cs file and inside the method CreateAsync send the command into the mediator and map its result:

If we now invoked the endpoint, we would receive an exception saying that no ICommandHandler<CreateProductCommand, CreateProductResult> was found by the container.

We will fix that by creating the class CreateProductCommandHandler with the business logic for this action. For this demo, an InvalidOperationException with a custom message will be thrown when a duplicated code is received:

If you now try to create a product using the Swagger endpoint, you will receive the response with the unique identifier or an internal server error indicating a duplicated code.

The project should look as follows:


Time to return a product when a GET /products/:id is received by the web API.

Inside the Handlers/Products folder, create a Product, the GetProductByIdQuery and its corresponding handler, GetProductByIdQueryHandler. Like in the previous handler, for this demo, we are going to throw an InvalidOperationException if the id is unknown:

Open the ProductsController.cs file and inside the method GetByIdAsync fetch the query from the mediator and map its result:

If you now try to get a product using the Swagger endpoint, you will receive the product or an internal server error indicating an unknown identifier.


Finally, we are going to create an event that will be broadcast when a product is successfully created.

Just like the previous ones, create a CreateProductEvent and the handler CreateProductEventHandler that will serialize and store it into the events table.

Open the CreateProductCommandHandler file, inject the IMediator instance and broadcast the event before saving flushing all changes into the database:

The project should look as follows:


I hope this article gave you a good idea on how to use the mediator to implement the CQRS and ES patterns even if you are implementing an MVP and can’t spend much time thinking about the architecture but you still want something that can be maintained and extended for some time.

Soon I’ll be explaining more advanced scenarios, like using the mediator pipeline to validate commands before reaching the handler, managing database transactions or even implementing transversal auditing into you application.

The Startup

Get smarter at building your thing. Join The Startup’s +789K followers.

Sign up for Top 10 Stories

By The Startup

Get smarter at building your thing. Subscribe to receive The Startup's top 10 most read stories — delivered straight into your inbox, once a week. Take a look.

By signing up, you will create a Medium account if you don’t already have one. Review our Privacy Policy for more information about our privacy practices.

Check your inbox
Medium sent you an email at to complete your subscription.

João Simões

Written by

Solutions Architect trying to solve world “problems”!

The Startup

Get smarter at building your thing. Follow to join The Startup’s +8 million monthly readers & +789K followers.

João Simões

Written by

Solutions Architect trying to solve world “problems”!

The Startup

Get smarter at building your thing. Follow to join The Startup’s +8 million monthly readers & +789K followers.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store