Sponsor: Do you build complex software systems? See how NServiceBus makes it easier to design, build, and manage software systems that use message queues to achieve loose coupling. Get started for free.
The MediatR library by Jimmy Bogard has become increasingly popular over recent years, and deservedly so. By its own definition, it’s a simple, unambitious mediator implementation in .NET. Why are so many developers using it? Why should you use MediatR? Here are 3 reasons why you should at least consider using it and one reason why shouldn’t.
Check out my YouTube channel where I post all kinds of content that accompanies my posts including this one regarding MediatR.
What is MediatR?
For those unfamiliar with MediatR library or the mediator pattern:
In software engineering, the mediator pattern defines an object that encapsulates how a set of objects interact. This pattern is considered to be a behavioral pattern due to the way it can alter the program’s running behavior.
Reason #1: Decoupling
Most examples I’ve seen using MediatR are with ASP.NET Core, but that doesn’t mean that’s the only framework where it’s useful. The point is decoupling your application code from the top-level framework code. Whatever code is actually in charge of executing your code.
Here’s a example using ASP.NET Core MVC
The point is creating a request object that you pass to MediatR which in turn invokes the correct Handler for that request object.
The PlaceOrderHandler has no references to any types or APIs in ASP.NET Core.
Reason #2: Application Requests
The reason why decoupling from top-level framework code such as ASP.NET Core can be important is to ask yourself: Is the application I’m creating an application or a web application?
There’s a difference between a web application and just an application.
An application can have many different inputs. Not all incoming requests are going to be via HTTP. There may be various ways that interact with your application.
For example, you could have recurring jobs that need to perform specific actions at a given time during the day. Or you may also have work that gets triggered from specific messages you’re picking up from a Message Broker.
There are a number of ways that you may want to invoke behaviors in your system that don’t initiate from an HTTP request.
In my example above with ASP.NET Core, we’re ultimately converting an HTTP request into an Application Request. That Application request is entirely decoupled from any specific top level framework and could be invoke from anywhere.
Using MediatR to create application requests to cross an integration boundary.
Reason #3: Request Pipelines
Once you start thinking about application requests, you can go deeper into creating a pipeline for those requests.
If you’re familiar with ASP.NET Core middleware, the purpose is to define a pipeline for an HTTP request.
You can create the same concept using MediatR behaviors. There are a few different ways to create them but here’s an example of a that implements the IPipelineBehavior
When you call mediator.Send() this behavior is called first prior to your primary handler (PlaceOrderHandler). The RequestHandlerDelegate which is a delegate to call PlaceOrderHandler. This allows us to do primary work before calling it or possibly even short-circuiting and not calling it at all, say if we had some validation issues.
This means you could have any number of pre-processors that can be run prior to the primary handler, or post-processors that can be run after.
This is incredibly powerful and allows you to separate different concerns related to a given application request.
The reason you may not want to use MediatR is simply that everything is done in-process. Meaning that wherever process is calling mediator.Send() is also the same process that is executing the relevant Handler for that request.
With everything in-process, this becomes really apparent with Events/Notifications (MediatR calls them Notifications).
A notification can have zero or multiple handlers. However the execution of all the notification handlers are done all in the same process.
In the example above, if you publish a notification to MediatR, and there are 3 handlers for that notification, it will execute all 3. But what happens if one of them fails and throws an exception?
That exception will bubble up back to where you published the message via MediatR. How do you want to handle this? Can you re-publish that message again and have the handlers that succeeded run again? What if one of them was sending an email?
You want event/notification handlers to be run in independently in isolation. This is where out-of-process messaging comes in.
If you want more details on how MediatR works, I’ve talked and written about this in my Fat Controller CQRS Diet where I use MediatR as an example on how to decouple your application code from top-level framework code.
- Fat Controller CQRS Diet
- Part 1: Simple Query
- Part 2: Simple Command
- Part 3: Command Pipeline
- Part 4: Notifications
- Part 5: Vertical Slices
- Part 6: Trade-offs