Dispatcher
A mediator you can read in one sitting

What it looks like

The PoC in the solution dispatches one command twice — once happily, once where the main handler throws.

Pre Handling command: John
Second Pre Handling command: John
Handling command: John
Post Handled command: John

Pre Handling command: John Doe
Second Pre Handling command: John Doe
Failed handling command: John Doe, Exception: Invalid name

What it does

One call, four stages. Each stage asks the container for GetServices<THandler>(), so a stage can hold zero, one or many handlers — every one of them runs.

  await dispatcher.DispatchAsync(new MyCommand { Name = "John" }, cancellationToken)

  +------------------------------ try ------------------------------+
  |  1  IPreCommandHandler<TCommand>     all of them, awaited       |
  |  2  ICommandHandler<TCommand>        the actual work            |
  |  3  IPostCommandHandler<TCommand>    all of them, awaited       |
  +----------------------------- catch -----------------------------+
                                    |
                                    v
    4  IFailCommandHandler<TCommand>.HandleAsync(command, exception)

Why write this yourself?

Because the pattern is older than the libraries — and the best-known library is no longer free for every kind of project.

The code, piece by piece

Everything below is the real source in the download — eight small files in one class library.

1. The command

A command is a marker plus an identity. The identity is handy in logs and traces.

namespace Caldro.Dispatcher.Interfaces
{
    public interface ICommand
    {
        public string Id { get; }
    }
}

2. The handler contract

One async method, cancellation-aware. Note the in keyword: it makes the type parameter contravariant, so a handler written for a base command can serve a more specific one — the C# generic-variance trick that mediator libraries advertise.

public interface ICommandHandler<in TCommand> where TCommand : ICommand
{
    Task HandleAsync(TCommand command, CancellationToken cancellationToken = default);
}

3. The dispatcher interface

public interface ICommandDispatcher
{
    Task DispatchAsync<TCommand>(TCommand command, CancellationToken cancellationToken = default)
        where TCommand : ICommand;
}

4. The dispatcher itself — the whole engine

This is the file that does the work. No base class to inherit, no behaviour pipeline to learn, no licence check.

using Caldro.Dispatcher.Interfaces;
using Microsoft.Extensions.DependencyInjection;

namespace Caldro.Dispatcher;

public class CommandDispatcher : ICommandDispatcher
{
    private readonly IServiceProvider _serviceProvider;

    public CommandDispatcher(IServiceProvider serviceProvider)
    {
        _serviceProvider = serviceProvider;
    }

    public async Task DispatchAsync<TCommand>(TCommand command, CancellationToken cancellationToken = default)
        where TCommand : ICommand
    {
        try
        {
            var preHandlers = _serviceProvider.GetServices<IPreCommandHandler<TCommand>>();
            await Task.WhenAll(preHandlers.Select(h => h.HandleAsync(command, cancellationToken)));

            var handlers = _serviceProvider.GetServices<ICommandHandler<TCommand>>();
            await Task.WhenAll(handlers.Select(h => h.HandleAsync(command, cancellationToken)));

            var postHandlers = _serviceProvider.GetServices<IPostCommandHandler<TCommand>>();
            await Task.WhenAll(postHandlers.Select(h => h.HandleAsync(command, cancellationToken)));
        }
        catch (Exception exception)
        {
            var failHandlers = _serviceProvider.GetServices<IFailCommandHandler<TCommand>>();
            await Task.WhenAll(failHandlers.Select(h => h.HandleAsync(command, exception, cancellationToken)));
        }
    }
}

• GetServices, not GetService — a stage runs every registered handler, not just the first one the container returns.
• One try for three stages — pre, main and post share a single catch, so a failure anywhere lands in the fail stage. A throwing pre-handler therefore stops the actual work from running.
• Task.WhenAll — the handlers of a stage start together and are awaited together, so a stage is as slow as its slowest handler and the order inside a stage is not defined (see ideas).
• Nothing is rethrown — after the fail handlers have run, the exception is swallowed. Handy for fire-and-forget commands, surprising for anything else (again: see ideas).

5. The three hook interfaces

Pre, post and fail are the same shape as the main handler — except that the fail stage also receives the exception.

public interface IPreCommandHandler<in TCommand> where TCommand : ICommand
{
    Task HandleAsync(TCommand command, CancellationToken cancellationToken = default);
}

public interface IPostCommandHandler<in TCommand> where TCommand : ICommand
{
    Task HandleAsync(TCommand command, CancellationToken cancellationToken = default);
}

public interface IFailCommandHandler<in TCommand> where TCommand : ICommand
{
    Task HandleAsync(TCommand command, Exception exception, CancellationToken cancellationToken = default);
}

6. Registration — finding the handlers

One extension method scans an assembly and wires up all four stages.

using System.Reflection;
using Caldro.Dispatcher.Interfaces;
using Microsoft.Extensions.DependencyInjection;

namespace Caldro.Dispatcher
{
    public static class CommandHandlerRegistration
    {
        public static void RegisterDispatcher(this IServiceCollection services, Assembly assembly)
        {
            services.AddTransient<ICommandDispatcher, CommandDispatcher>();

            RegisterHandlersByInterface(services, assembly, typeof(IPreCommandHandler<>));
            RegisterHandlersByInterface(services, assembly, typeof(ICommandHandler<>));
            RegisterHandlersByInterface(services, assembly, typeof(IPostCommandHandler<>));
            RegisterHandlersByInterface(services, assembly, typeof(IFailCommandHandler<>));
        }

        private static void RegisterHandlersByInterface(IServiceCollection services, Assembly assembly, Type handlerInterfaceType)
        {
            var handlerTypes = assembly.GetTypes()
                .Where(t => t.GetInterfaces().Any(i => i.IsGenericType && i.GetGenericTypeDefinition() == handlerInterfaceType) && !t.IsInterface && !t.IsAbstract);

            foreach (var handlerType in handlerTypes)
            {
                var interfaces = handlerType.GetInterfaces()
                    .Where(i => i.IsGenericType && i.GetGenericTypeDefinition() == handlerInterfaceType);

                foreach (var @interface in interfaces)
                {
                    services.AddTransient(@interface, handlerType);
                }
            }
        }
    }
}

• It registers the closed interface — services.AddTransient(typeof(ICommandHandler<MyCommand>), typeof(MyCommandHandler)). That is exactly the type the dispatcher asks for, so no generic type factory is needed at dispatch time.
• Interfaces and abstract classes are skipped, and so are open generic handlers such as class Logging<TCommand> : IPreCommandHandler<TCommand> — a genuinely useful thing to add (see ideas).
• @interface — the variable needs the @ because interface is a C# keyword. A small detail that is easy to trip over.
• One scan at startup — the reflection cost is paid once while the container is built; dispatching itself is just container lookups.

How to use it

Three steps to write, one line to register, one call to dispatch.

The whole picture in one file

using Caldro.Dispatcher.Interfaces;
using Microsoft.Extensions.DependencyInjection;

// 1 - a command
public class MyCommand : ICommand
{
    public string Id { get; } = Guid.NewGuid().ToString();
    public string? Name { get; set; }
}

// 2 - as many handler stages as you like
public class MyPreCommandHandler : IPreCommandHandler<MyCommand>
{
    public Task HandleAsync(MyCommand command, CancellationToken cancellationToken = default)
    {
        Console.WriteLine($"Pre: {command.Name}");
        return Task.CompletedTask;
    }
}

public class MyCommandHandler : ICommandHandler<MyCommand>
{
    public Task HandleAsync(MyCommand command, CancellationToken cancellationToken = default)
    {
        if (command.Name == "John Doe")
        {
            throw new InvalidOperationException("Invalid name");
        }

        Console.WriteLine($"Handling: {command.Name}");
        return Task.CompletedTask;
    }
}

public class MyFailCommandHandler : IFailCommandHandler<MyCommand>
{
    public Task HandleAsync(MyCommand command, Exception exception, CancellationToken cancellationToken = default)
    {
        Console.WriteLine($"Failed: {command.Name}, {exception.Message}");
        return Task.CompletedTask;
    }
}

// 3 - register once: finds the dispatcher and all four stages in the assembly
var services = new ServiceCollection();
services.RegisterDispatcher(typeof(MyCommand).Assembly);

// 4 - dispatch
var provider = services.BuildServiceProvider();
var dispatcher = provider.GetRequiredService<ICommandDispatcher>();

await dispatcher.DispatchAsync(new MyCommand { Name = "John" });
await dispatcher.DispatchAsync(new MyCommand { Name = "John Doe" });   // throws inside -> fail handler runs

Swap MyCommand for anything that implements ICommand, and ServiceCollection for the container you already use: the registration is plain IServiceCollection, so ASP.NET Core, worker services, console apps and test hosts all behave the same way.

Key features

Small, but not toy-sized.

18 tests, no surprises

xUnit and Moq. The interesting ones are the ordering and failure tests, because those are the promises the dispatcher makes.

dotnet test

Test summary: total: 18; failed: 0; succeeded: 18; skipped: 0

Ideas — what I would add next

The boilerplate is deliberately minimal, so the interesting work is still open. If you extend it, these are the gaps I would close first.

About this project

Why it came to be.