jim.mddr 2.0.0

Leer en español

Mddr - Mediator Library for CQRS in .NET

jim.mddr is a library that implements the mediator pattern to facilitate CQRS (Command Query Responsibility Segregation) architecture in .NET applications. It allows you to decouple the sending of commands and queries from their handlers, as well as the execution of pipelines and publishers, providing a flexible and extensible structure for modern development.

What is the mediator pattern and how is it used in CQRS?

The mediator pattern centralizes communication between objects, avoiding direct references between them. In CQRS, this allows commands and queries to be sent through a mediator (ISender), which resolves and executes the appropriate handler, applying pipelines and publishers as needed.

Installation and requirements

• .NET 6 or higher
• Reference to the Jim.Mddr package and its dependencies

Service registration and configuration

The library uses a builder pattern to register services in a fluent, chained way. Typical example in Program.cs:

builder.Services.AddMddr(typeof(Program).Assembly)
                .AddPipeline<Pipeline1>()
                .AddPipeline<LoggingPipeline>()
                .AddPublisher<Example1Publisher, TestRequest>()
                .AddPublisher<Example2Publisher, TestRequest>();

Main registration methods

• AddMddr(Assembly assembly):
  Registers the mediator (ISender) and all the IRequestHandler<TRequest, TResponse> handlers found in the given assembly.

• AddPipeline<TPipeline>():
  Registers a custom pipeline that can modify the execution flow of commands and queries.

• AddPublisher<TPublisher, TEntity>():
  Registers a publisher for a specific entity type. All publishers registered for an entity will be executed when that entity is published.

Example usage in endpoints

The example's Program.cs file defines two main endpoints:

• GET /Commands
  Sends a command (TestRequest) through the mediator (ISender). The mediator locates and executes the corresponding IRequestHandler for that command, returning the response generated by the handler.

• GET /Publish
  Publishes an entity (TestRequest) using the mediator (ISender). The mediator executes all the IPublisher<TestRequest> publishers registered for that object type.

app.MapGet("/Commands", async (ISender sender, CancellationToken cancellationToken) =>
{
    return await sender.SendAsync(new TestRequest(), cancellationToken);
});

app.MapGet("/Publish", async (ISender sender, CancellationToken cancellationToken) =>
{
    await sender.PublishAsync(new TestRequest(), cancellationToken);
    return Results.Ok();
});

Component implementation examples

Command handler

public class TestRequest : IRequest<TestResponse> { }

public class TestResponse
{
    public string Value { get; set; }
}

public class TestRequestHandler : IRequestHandler<TestRequest, TestResponse>
{
    public async Task<TestResponse> HandleAsync(TestRequest request, CancellationToken cancellationToken)
    {
        return await Task.FromResult(new TestResponse { Value = "Handler response" });
    }
}

Custom pipeline

public class LoggingPipeline : IPipeline
{
    public async Task<object> HandleAsync(object request, Func<Task<object>> next, CancellationToken cancellationToken)
    {
        Console.WriteLine("Pipeline start");
        var response = await next();
        Console.WriteLine("Pipeline end");
        return response;
    }
}

Entity publisher

public class Example1Publisher : IPublisher<TestRequest>
{
    public async Task PublishAsync(TestRequest entity, CancellationToken cancellationToken)
    {
        Console.WriteLine("Publisher 1 executed");
        await Task.CompletedTask;
    }
}

Extension and customization

You can add your own handlers, pipelines, and publishers by implementing the interfaces:

• IRequestHandler<TRequest, TResponse>
• IPipeline
• IPublisher<TEntity>

Then register them in the DI container using the chained builder.

Recommended tests

• Verify service registration and resolution.
• Check the execution of handlers, pipelines, and publishers.
• Validate error behavior (for example, when no handler is registered).
• Check that the correct handler and publishers are called when using the endpoints.

Integration test example:

[Fact]
public async Task CommandsEndpoint_CallsHandler()
{
    var client = _factory.CreateClient();
    var response = await client.GetAsync("/Commands");
    var content = await response.Content.ReadAsStringAsync();
    Assert.Contains("Handler response", content);
}

License

This project is licensed under the MIT License. See the LICENSE file for details.

Have questions or need specific examples? Check the internal documentation or open an