In this article, we are going to explore the key differences between the Publish and Send methods in MediatR, a powerful .NET library for component communication.
We will see MediatR in action as we explore its implementation with requests, notifications, and behaviors.
Let’s start.
The Mediator Pattern
The mediator pattern is a software design pattern that enables indirect communication between software components, promoting loose coupling by introducing a mediator object as an intermediary.
By utilizing the Mediator pattern, components are decoupled and unaware of each other, reducing direct dependencies. This enhances flexibility and modularity, simplifying the addition or modification of components without impacting the entire system.
Now, let’s delve into how MediatR empowers the realization of these principles.
The MediatR Library
MediatR is a popular open-source library for implementing the Mediator pattern in .NET applications. It provides a simple and elegant way to handle communication between different parts of an application by encapsulating the logic of sending and handling messages.
There are two primary methods for sending messages: Publish and Send. Understanding the differences and trade-offs between these methods is crucial. This understanding will greatly assist you in making informed design decisions for your application.
Configuring an ASP.NET Core API with MediatR
To begin, let’s install the MediatR package: dotnet add package MediatR
Next, in the Program.cs
file, we are going to register MediatR:
builder.Services.AddMediatR(cfg => cfg.RegisterServicesFromAssembly(typeof(Program).Assembly));
To ensure the effective usage of MediatR, it is crucial to set up its configuration properly.
After successful installation and configuration, we can proceed with creating a new controller responsible for sending messages with MediatR:
[ApiController] [Route("api/users")] public class UserController : Controller { private readonly IMediator _mediator; public UserController(IMediator mediator) { _mediator = mediator; } }
In the UserController
, we are going to handle user-related operations within the API
. We utilize the IMediator
interface, which we inject through the constructor injection. This injection enables the controller to access MediatR functionality for effectively handling messages and requests.
Besides using the IMediator
interface, starting from the MediatR library version 9.0 this interface has been split into two separate interfaces ISender
and IPublisher
. The ISender
provides the Send()
method capability and IPublisher
the Publish()
method capability. If you want to know more about this, you can find that in one of our articles about MediatR and CQRS.
The Send Method in MediatR
The Send()
method in MediatR facilitates efficient communication between components by handling commands and queries. It is key in promoting decoupling and separation of concerns within the application, resulting in enhanced flexibility and maintainability.
To initiate the process, we first need to create a command class:
public class CreateUserCommand : IRequest<int> { public string UserName { get; set; } = string.Empty; public string Email { get; set; } = string.Empty; }
The CreateUserCommandHandler
Let’s explore the class responsible for creating a new user and returning its ID. This handler class is crucial for the user creation process:
public class CreateUserCommandHandler : IRequestHandler<CreateUserCommand, int> { private readonly IUserRepository _userRepository; public CreateUserCommandHandler(IUserRepository userRepository) => _userRepository = userRepository; public async Task<int> Handle(CreateUserCommand request, CancellationToken cancellationToken) { var user = new User { UserName = request.UserName, Email = request.Email }; return await _userRepository.CreateUserAsync(user); } }
We have a class name CreateUserCommandHandler
that implements the IRequestHandler<CreateUserCommand, int>
interface. This handler is responsible for processing the CreateUserCommand
by creating a new user with the provided username
and email
. The IUserRepository
dependency is injected into the handler’s constructor. The Handle()
method asynchronously creates the user using the repository and returns the ID of the newly created user.
Invoking and Verifying Our Request
To invoke our request, we can add the CreateUser()
action to our UserController
:
[HttpPost] [ProducesResponseType(StatusCodes.Status201Created)] public async Task<ActionResult<int>> CreateUser(CreateUserCommand command) { int userId = await _mediator.Send(command); return CreatedAtAction(nameof(CreateUser), userId); }
This action expects a CreateUserCommand
parameter and sends it to MediatR using the _mediator.Send()
method. Upon invoking the request, it retrieves the result userId
and includes it in the CreatedAtAction
response. This response serves as the identifier for the newly created user.
Once we send a request to this endpoint, we can verify that MediatR is working as expected:
The Publish Method in MediatR
The Publish()
method in MediatR serves as a one-way communication mechanism, allowing for the broadcast of messages to multiple subscribers within the application. Its primary function is to facilitate the distribution of messages without expecting any response or results in return.Â
Let’s create an event that notifies about created users:
public class UserCreatedEvent : INotification { public int UserId { get; set; } public string UserName { get; set; } = string.Empty; }
The UserCreatedEvent
class holds a UserId
and the corresponding UserName
.
The UserCreatedEventHandler
Next, let’s define the UserCreatedEventHandler
class for handling the UserCreatedEvent
. It implements the INotificationHandler
interface and receives the UserCreatedEvent
as a parameter:
public class UserCreatedEventHandler : INotificationHandler<UserCreatedEvent> { private readonly IUserRepository _userRepository; private readonly INotificationService _notificationService; public UserCreatedEventHandler(IUserRepository userRepository, INotificationService notificationService) { _userRepository = userRepository; _notificationService = notificationService; } public async Task Handle(UserCreatedEvent notification, CancellationToken cancellationToken) { var admin = await _userRepository.GetAdminUserAsync(); string message = $"New user created: ID: {notification.UserId}, UserName: {notification.UserName}"; await _notificationService.SendNotificationAsync(admin.UserId, message); } }
The Handle()
method retrieves the admin user from the repository and creates a notification message with the ID and username of the newly created user.Â
This event handler is essential for managing user creation events and executing additional actions or notifications based on these events.
Invoking and Verifying our Request
To invoke our request, we can add the NotifyUser()
action to our UserController
:
[HttpPost("notify")] [ProducesResponseType(StatusCodes.Status200OK)] public async Task<IActionResult> NotifyUser(UserCreatedEvent notification) { await _mediator.Publish(notification); return Ok(); }
The NotifyUser()
action accepts a UserCreatedEvent notification
parameter. Using the _mediator.Publish()
method, we publish the notification by executing our handler. Finally, we return an HTTP 200 OK
status code.
Next, let’s open Postman and send a new request to our endpoint notify
:
Conclusion
Throughout this article, we explored the usage of MediatR for command and event handling. We examined the differences between the Publish and Send methods and discussed their specific use cases.
The Publish method enables one-to-many communication by broadcasting messages without expecting a response. It promotes loose coupling, and dynamic subscriptions, and is well-suited for event-driven architectures.
On the flip side, the Send method facilitates one-to-one communication with an expected response. This can be used for requests or commands which expect an immediate response.
That is interesting but I realized that it missed one use case about notify, will you use the NotifyUser method for what?
Hi Vagner. The NotifyUser action method was created separately just for easier comparison between the two mentioned methods (Publish and Send). But usually, you don’t create a separate endpoint for your notifications, they are something that follows your regular actions. For example, you have an action to create an entity in the database, and right away, you want to send an email to a user/admin, then, you would use your notifications. In this article, once you understand the difference between the two, we have left the link to our popular MediatR and CQRS article, and there, you can read about this in more detail.