Flowsy.Mediation 13.0.1

Flowsy Mediation

This package provides a simple but useful implementation of the mediator pattern for .NET applications. As of version 13, this packagke no longer depends on MediatR and provides its own implementation of the mediator pattern, which is designed to be lightweight and easy to use. For request validation, it still can use FluentValidation if you configure it to do so.

Concepts

The mediator pattern allows us to centralize communication between different parts of an application through a single mediator object in charge of dispatching requests and notifications to the appropriate components containing the logic to handle them.

A common application flow would be:

1. User requests some action to be executed.
2. The application validates the request and returns some error information to the user in case of invalid input.
3. The application executes the requested operation.
4. The application returns to the user the result of the operation or some error information if something went wrong during the process.
5. After the request has been fulfilled, the application may notify other parts of the system to trigger another related operation.

In fact, the mediator pattern is a powerful way to implement the CQRS (Command Query Responsibility Segregation) pattern, which separates the read and write operations of an application.

• Query: A request for reading data with no alteration of the application's current state.
• Command: A request for creating, updating or removing data, thus altering the application's current state.

Requests

In the context of the mediation pattern, a request is an object that represents an operation to be performed and it contains all the necessary information to execute that operation. Some requests can execute wihout returning any result, while others can return a response.

• IRequest: Represents a request without a response.
• IRequest<TResponse>: Represents a request that returns a response of type TResponse.

Request Handlers

A request handler is a component containing the logic to execute a request. It is responsible for processing the request and returning a response if applicable.

• IRequestHandler<TRequest>: Represents a handler for a request of type TRequest without a response.
• IRequestHandler<TRequest, TResponse>: Represents a handler for a request of type TRequest that returns a response of type TResponse.

Notifications

Notifications contain information about relevant events that have occurred in the application and are published by the mediation system wihtout expecting a response.

• INotification: Represents a notification that can be published to subscribers.

Notifications Handlers

A notification handler is a component that processes notifications published by the mediation system. This concept is a powerful way to trigger side effects or notify other parts of the system about changes without requiring a response.

• INotificationHandler<TNotification>: Represents a handler for a notification of type TNotification.

Middleware

Middleware components can be used to intercept and process requests and notifications before they reach the associated handler. For instance, you can use a middleware to count the number of attempts to execute a given request, or to record audit trails for the request execution.

• IRequestMiddleware<TRequest>: Represents a middleware that can intercept and process requests of type TRequest before they reach the handler.
• IRequestMiddleware<TRequest, TResponse>: Represents a middleware that can intercept and process requests of type TRequest with a response of type TResponse before they reach the handler.
• INotificationMiddleware<TNotification>: Represents a middleware that can intercept and process notifications of type TNotification before they reach the handler.

Built-in Middleware

This package provides some built-in middleware components to facilitate common tasks:

Logging

• RequestLoggingMiddleware<TRequest>: Logs information about a request of type TRequest.
• RequestLoggingMiddleware<TRequest, TResponse>: Logs information about a request of type TRequest and its response of type TResponse.
• NotificationLoggingMiddleware<TNotification>: Logs information about a notification of type TNotification.

Validation

• RequestValidationMiddleware<TRequest>: Validates requests of type TRequest.
• RequestValidationMiddleware<TRequest, TResponse>: Validates requests of type TRequest with a response of type TResponse.

Usage

1. Define Some Queries

// Queries/CustomersByRegion/CustomersByRegionQuery.cs
// using ...
using Flowsy.Mediation;
// using ...

// You can use classes or records to define your queries.
public record CustomersByRegionQuery(string CountryId, string? StateId) : IRequest<IEnumerable<CustomerDto>>;

2. Define Some Query Validators

// Queries/CustomersByRegion/CustomersByRegionQueryValidator.cs
// using ...
using Flowsy.Mediation;
using FluentValidation;
// using ...

public class CustomersByRegionQueryValidator : AbstractValidator<CustomersByRegionQuery>
{
    public CustomersByRegionQueryValidator()
    {
        RuleFor(query => query.CountryId)
            .NotEmpty()
            .WithMessage("Country identifier is required.");
    }
}

3. Define Some Query Handlers

// Queries/CustomersByRegion/CustomersByRegionQueryHandler.cs
// using ...
using Flowsy.Mediation;
// using ...

public class CustomersByRegionQueryHandler : IRequestHandler<CustomerByIdQuery, IEnumerable<CustomerDto>>
{
    private readonly ICustomerRepository _customerRepository;
    
    public CustomersByRegionQueryHandler(ICustomerRepository customerRepository)
    {
        _customerRepository = customerRepository;
    }

    protected override async Task<IEnumerable<CustomerDto>> HandleAsync(CustomersByRegionQuery request, CancellationToken cancellationToken)
    {
        var customers = await _customerRepository.GetCusomtersByRegionAsync(request.CountryId, request.StateId, cancellationToken);
        
        return customers;
    }
}

4. Define Some Commands

// Commands/CreateCustomer/CreateCustomerCommand.cs
// using ...
using Flowsy.Mediation;
// using ...

// You can use classes or records to define your commands.
public record CreateCustomerCommand(string FirstName, string LastName, string Email) : IRequest<CreateCustomerCommandResult>;

5. Define Some Command Validators

// Commands/CreateCustomer/CreateCustomerCommandValidator.cs
// using ...
using Flowsy.Mediation;
using FluentValidation;
// using ...

public class CreateCustomerCommandValidator : AbstractValidator<CreateCustomerCommand>
{
    public CreateCustomerCommandValidator()
    {
        RuleFor(command => command.FirstName)
            .NotEmpty()
            .WithMessage("First name is required.");
            
        RuleFor(command => command.Email)
            .EmailAddress()
            .WithMessage("Invalid email address")
            .DependentRules(() => 
            {
                RuleFor(command => command.Email)
                    .NotEmpty()
                    .WithMessage("Email is required.")
                    .MaximumLength(320)
                    .WithMessage("Up to 320 characters.");
            });
    }
}

6. Define Some Command Results

// Commands/CreateCustomer/CreateCustomerCommandResult.cs

// You can use classes or records to define your command results.
public record CreateCustomerCommandResult(Guid CustomerId);

7. Define Some Command Handlers

// Commands/CreateCustomer/CreateCustomerCommandHandler.cs
// using ...
using Flowsy.Mediation;
// using ...

public class CreateCustomerCommandHandler : IRequestHandler<CreateCustomerCommand, CreateCustomerCommandResult>
{
    private readonly ICustomerRepository _customerRepository;
    
    public CreateCustomerCommandHandler(ICustomerRepository customerRepository)
    {
        _customerRepository = customerRepository;
    }

    protected override async Task<CreateCustomerCommandResult> HandleAsync(CreateCustomerCommand request, CancellationToken cancellationToken)
    {
        var customer = new Customer(Guid.NewGuid(), request.FirstName, request.LastName, request.Email);
    
        await _customerRepository.CreateCustomerAsync(customer, cancellationToken);
        
        return new CreateCustomerCommandResult(customer.CustomerId); 
    }
}

8. Register and Configure Services

// Program.cs
// using ...
using Flowsy.Mediation;
using FluentValidation;
// using ...

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddMediation()
    .FromAssemblies(Assembly.GetExecutingAssembly()) // Add one or more assemblies containing your requests, notifications, validators and handlers
    // .FromAssemblies([Assembly.GetExecutingAssembly()], false) // Use this version to prevent automatic registration of FluentValidation validators
    .WithMiddleware() // Allow middleware registration
    .ForLogging(LogLevel.Debug, true, true, true) // Built-in logging middleware for requests and notifications
    .ForRequest(typeof(AuditMiddleware<>)) // Fictitious middleware for auditing requests without a response
    .ForRequest(typeof(AuditMiddleware<,>)) // Fictitious middleware for auditing requests with a response
    .ForRequest<CustomerCreationAttemptMiddleware>() // Fictitious middleware for counting attempts to create a customer
    .ForValidation() // Built-in validation middleware for requests
    .ForNotification<CustomerCreationCompletedMiddleware>(); // Fictitious middleware for handling customer creation completion notifications

//!!!!!!!!!!!
// IMPORTANT: The order of middleware registration matters, as they will be executed in the order they are registered.
//!!!!!!!!!!!

// Add other services

var app = builder.Build();

// Use services

app.Run();

9. Using the Mediator

// SomeController.cs
// using ...
using Flowsy.Mediation;
// using ...

[Route("api/[controller]")]
public class CustomersController : ControllerBase
{
    private readonly IMediator _mediator;

    public SomeController(IMediator mediator)
    {
        _mediator = mediator;
    }

    [HttpGet]
    public async Task<IActionResult> GetCustomersByRegion([FromQuery] string countryId, [FromQuery] string? stateId)
    {
        var query = new CustomersByRegionQuery(countryId, stateId);
        var customers = await _mediator.Send(query);
        
        return Ok(customers);
    }

    [HttpPost]
    public async Task<IActionResult> CreateCustomer(CreateCustomerCommand command)
    {
        var result = await _mediator.Send(command);
        
        return CreatedAtAction(nameof(GetCustomerById), new { id = result.CustomerId }, result);
    }
}