Dekiru.Hermes.Generator 0.0.1

Hermes - A messenger to the gods

Hermes is an implementation of the mediator pattern for .NET. It uses source generators to create a dispatcher for queries, commands and events.

How to use: Add Dekiru.Hermes to your project and register the generated dispatcher in your DI container. Registration is done via the AddHermes extension method on IServiceCollection. (As such, Hermes requires Microsoft.Extensions.DependencyInjection.)

The most basic usage is as follows:

[Handler]
public class MyHandler : IQueryHandler<MyQuery, MyResponse>
{
    public Task<MyResponse> Handle(MyQuery query, CancellationToken cancellationToken)
    {
        return Task.FromResult(new MyResponse());
    }
}

This will generate a Dispatch-method on the IDispatcher interface that takes a MyQuery and returns a Task<MyResponse>.

There are four types of interfaces that can be used to define handlers:

• ICommandHander<TCommand> - Handles commands that do not return a value.
• ICommandHandler<TCommand, TResponse> - Handles commands that return a value.
• IQueryHandler<TQuery, TResponse> - Handles queries that return a value.
• IEventHandler<TEvent> - Handles events that do not return a value. Multiple event handlers can be defined for the same event. Errors thrown by one handler will be ignored and the other handlers will still be executed.

Note on ICommandHandler<TCommand>: This interface is functionally identical to ICommandHandler<TCommand, Null>, where Null is a class representing a void return type. The choice between the two is primarily a matter of preference and code clarity. The Dispatch-method generated for ICommandHandler<TCommand> will return a Task, while the one for ICommandHandler<TCommand, TResponse> will return a Task<TResponse>. Handlers implementing ICommandHandler<TCommand> may be more readable in scenarios where the command does not need to return a value, as it clearly indicates that no response is expected. The developer can return Null.Task to reduce unnecessary allocations.

Beyond the handler interfaces, there's also an interface for middleware (IMiddleware<TRequest, TResponse>). Middleware can be used to add cross-cutting concerns to the dispatching process, such as logging, validation, or transaction management. Middleware is executed in the order it is registered on the handler.

[Handler]
[Middleware<MyMiddleware>]
public class MyHandler : IQueryHandler<MyQuery, MyResponse>
{
  ...
}

Middleware implements a Handle(TRequest request, Func<TRequest, CancellationToken, Task<TResponse>> next, CancellationToken cancellationToken) method. The next parameter is a delegate that invokes the next middleware in the pipeline, or the handler if there are no more middleware.

public class MyMiddleware : IMiddleware<MyQuery, MyResponse>
{
    public async Task<MyResponse> Handle(MyQuery request, Func<MyQuery, CancellationToken, Task<MyResponse>> next, CancellationToken cancellationToken)
    {
        // Do something before the handler is invoked
        var response = await next(request, cancellationToken);
        // Do something after the handler is invoked
        return response;
    }
}

As such, a middleware can modify or replace the request or response, or even short-circuit the pipeline by not calling next.

Middleware can come in two variants: Open or closed generics. Closed generics are defined for a specific request and response type, while open generics can be used for any request and response type.

public class MyMiddleware : IMiddleware<MyQuery, MyResponse> { ... } // Closed generic

public class MyOpenGenericMiddleware<TRequest, TResponse> : IMiddleware<TRequest, TResponse> { ... } // Open generic

Open middleware can be registered on the handler in three different ways:

• [Middleware(typeof(MyOpenGenericMiddleware<,>))] - Registers the open generic middleware for the specific request and response type of the handler.
• [Middleware<MyOpenGenericMiddleware<MyRequest, MyResponse>>] - Same as above, but using a generic type parameter.
• [Middleware<MyOpenGenericMiddleware<_, _>>] - Same as above, but using the special _-type as a placeholder. The source generator will replace the _ with the request and response type of the handler.

Closed middleware can only be registered using the first two methods.