FBC.Mediator 0.1.0

FBC.Mediator

A lightweight, high-performance Mediator pattern implementation for .NET projects. Provides command/query dispatching, request handler caching, and endpoint registration for ASP.NET Core Minimal APIs. Supports .NET 8, 9 and 10.

Features

Installation

dotnet add package FBC.Mediator

Quick Start

1. Define Your Request and Handler

public sealed class CreateItem
{
    public record Command(string Name) : IRequest<long>;

    internal sealed class Handler(ILogger<Handler> logger) : IRequestHandler<Command, long>
    {
        public async Task<long> Handle(Command request, CancellationToken token = default)
        {
            logger.LogInformation("Creating item: {Name}", request.Name);
            await Task.Delay(100, token);
            return new Random().Next(1, 1000);
        }
    }
}

2. Define Your Endpoint

public sealed class CreateItemEndPoint : IEndpoint
{
    public void AddRoutes(IEndpointRouteBuilder app)
    {
        app.MapPost("/items/create", async (CreateItem.Command command, IMediator mediator, CancellationToken token) =>
        {
            var itemId = await mediator.Send(command, token);
            return Results.Ok(itemId);
        })
        .WithTags("Items")
        .WithName("CreateItem")
        .WithSummary("Creates a new item.")
        .Produces<long>(StatusCodes.Status200OK)
        .Produces(StatusCodes.Status400BadRequest);
    }
}

3. Register in DI and Map Endpoints

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMediator(typeof(Program).Assembly);

var app = builder.Build();

app.UseMediatorEndpoints();

app.Run();

Core Concepts

Request Types

All requests implement a marker interface that tells the mediator what type of response to expect:

// Request with response
public record GetUserQuery(int Id) : IRequest<UserDto>;

// Void request (no response)
public record DeleteUserCommand(int Id) : IRequest;

The base interface hierarchy:

Request Handlers

Each request must have exactly one handler:

// Handler for typed response
public class GetUserHandler : IRequestHandler<GetUserQuery, UserDto>
{
    public async Task<UserDto> Handle(GetUserQuery request, CancellationToken token = default)
    {
        // your logic here
    }
}

// Handler for void request
public class DeleteUserHandler : IRequestHandler<DeleteUserCommand>
{
    public async Task Handle(DeleteUserCommand request, CancellationToken token = default)
    {
        // your logic here
    }
}

IMediator

The central dispatcher. Inject it anywhere via DI:

public interface IMediator
{
    Task<TResponse> Send<TResponse>(IRequest<TResponse> request, CancellationToken cancellationToken = default);
    Task Send(IRequest request, CancellationToken cancellationToken = default);
}

IEndpoint

Interface for defining ASP.NET Core Minimal API endpoints:

public interface IEndpoint
{
    void AddRoutes(IEndpointRouteBuilder app);
}

Each IEndpoint implementation groups related routes together. All implementations are auto-discovered and registered by AddMediator().

Features in Detail

Nested Request/Handler Pattern

The recommended pattern is to nest the handler inside the request class for clean organization:

public sealed class CreateItem
{
    public record Command(string Name) : IRequest<long>;

    internal sealed class Handler(ILogger<Handler> logger) : IRequestHandler<Command, long>
    {
        public async Task<long> Handle(Command request, CancellationToken token = default)
        {
            logger.LogInformation("Creating item: {Name}", request.Name);
            return 42;
        }
    }
}

Key points:

• Request and handler are co-located for discoverability.
• Handler can be internal since the mediator resolves it via DI.
• Swagger automatically renders nested types as CreateItem_Command.

Separate Handler Classes

Handlers do not need to be nested. You can place them in separate files or projects:

// In Application layer
public record GetUserById(int Id) : IRequest<UserDto>;

// In a different file or project
public class GetUserByIdHandler(IDbContext db) : IRequestHandler<GetUserById, UserDto>
{
    public async Task<UserDto> Handle(GetUserById request, CancellationToken token = default)
    {
        return await db.Users.FindAsync(request.Id, token);
    }
}

Void Requests

Use IRequest for operations that don't return a value:

public sealed class SendNotification
{
    public record Command(string Message) : IRequest;

    internal sealed class Handler(ILogger<Handler> logger) : IRequestHandler<Command>
    {
        public async Task Handle(Command request, CancellationToken token = default)
        {
            logger.LogInformation("Sending notification: {Message}", request.Message);
            await Task.CompletedTask;
        }
    }
}

Endpoint for a void request:

public sealed class SendNotificationEndPoint : IEndpoint
{
    public void AddRoutes(IEndpointRouteBuilder app)
    {
        app.MapPost("/notifications/send", async (SendNotification.Command command, IMediator mediator, CancellationToken token) =>
        {
            await mediator.Send(command, token);
            return Results.Ok();
        })
        .WithTags("Notifications")
        .WithName("SendNotification")
        .Produces(StatusCodes.Status200OK);
    }
}

Using IMediator Directly (Without Endpoints)

You can inject IMediator into any service, controller, or background job:

public class OrderService(IMediator mediator)
{
    public async Task<long> PlaceOrder(string itemName, CancellationToken token)
    {
        var command = new CreateItem.Command(itemName);
        return await mediator.Send(command, token);
    }
}

Multi-Assembly Registration

If your handlers and endpoints live in different projects, pass all assemblies:

builder.Services.AddMediator(
    typeof(Program).Assembly,            // Web API project
    typeof(CreateItemHandler).Assembly,  // Application layer
    typeof(UserEndpoints).Assembly       // Endpoints library
);

If no assemblies are passed, AddMediator() scans all currently loaded assemblies via AppDomain.CurrentDomain.GetAssemblies().

Handler Caching (Performance)

FBCMediator uses a static ConcurrentDictionary to cache compiled expression trees:

1. First request - Reflection discovers the handler type, builds an Expression tree, compiles it to a delegate, and caches the result.
2. Subsequent requests - The cached compiled delegate is invoked directly with zero reflection overhead.
3. Thread-safe - ConcurrentDictionary ensures safe concurrent access.

Swagger / OpenAPI Support

FBC.Mediator automatically configures Swagger's SchemaIdSelector so that nested record/class types are displayed correctly:

No extra configuration needed - just add Swagger as usual:

builder.Services.AddSwaggerGen();

Full Program.cs Example

using FBC.Mediator;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

builder.Services.AddMediator(typeof(Program).Assembly);

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();
app.UseMediatorEndpoints();

app.Run();

API Reference

Extension Methods

DI Registrations by AddMediator

Interfaces

Requirements

• .NET 8.0, 9.0, or 10.0
• ASP.NET Core (via Microsoft.AspNetCore.App framework reference)

License

MIT