DispatchR Documentation

DispatchR uses the Chain of Responsibility pattern for pipeline behaviors. Instead of a delegate next(), you must inject the NextPipeline handler and call its Handle method.

To create a generic pipeline behavior that applies to all requests of a specific return type (e.g., all ValueTask requests), use the following pattern:

// Specific behavior
public sealed class LoggingBehaviorDispatchR : IPipelineBehavior<PingDispatchR, ValueTask<int>>
{
    public required IRequestHandler<PingDispatchR, ValueTask<int>> NextPipeline { get; set; }

    public ValueTask<int> Handle(PingDispatchR request, CancellationToken cancellationToken)
    {
        return NextPipeline.Handle(request, cancellationToken);
    }
}

// Generic behavior for all ValueTask requests
public class GenericPipelineBehavior<TRequest, TResponse>() : IPipelineBehavior<TRequest, ValueTask<TResponse>>
    where TRequest : class, IRequest<TRequest, ValueTask<TResponse>>
{
    public required IRequestHandler<TRequest, ValueTask<TResponse>> NextPipeline { get; set; }
    
    public ValueTask<TResponse> Handle(TRequest request, CancellationToken cancellationToken)
    {
        return NextPipeline.Handle(request, cancellationToken);
    }
}

DispatchR implements pipeline behaviors by chaining them at resolution time through Dependency Injection. When a request is made, the DI container resolves a set of objects (the handler and its associated pipeline behaviors).

DispatchR then iterates through these resolved objects and uses a SetNext mechanism to link them into a chain. This design avoids the use of static lists or heavy reflection during the actual request execution, contributing to its high performance.

Key characteristics:

• DI Caching: Handlers are cached via DI. In scoped scenarios, the handler object is constructed once and reused.
• Chaining: The first object in the resolved set is the actual handler, and subsequent objects are the pipeline behaviors that wrap the handler.

// Conceptual logic of how pipelines are chained during DI resolution
services.AddScoped(handlerInterface, sp =>
{
    var pipelinesWithHandler = Unsafe.As<IRequestHandler[]>(sp.GetKeyedServices<IRequestHandler>(key));
    
    IRequestHandler lastPipeline = pipelinesWithHandler[0];
    for (int i = 1; i < pipelinesWithHandler.Length; i++)
    {
        var pipeline = pipelinesWithHandler[i];
        pipeline.SetNext(lastPipeline);
        lastPipeline = pipeline;
    }

    return lastPipeline;
});

To use DispatchR, register it in your service collection using AddDispatchR. You can register handlers by providing an assembly, or use a configuration delegate for fine-grained control over pipelines, notifications, and handler filtering.

Quick Registration

By default, this enables automatic registration of pipelines and notifications:

builder.Services.AddDispatchR(typeof(MyCommand).Assembly, withPipelines: true, withNotifications: true);

Advanced Configuration

Use the ConfigurationOptions delegate to specify assemblies, define the order of pipeline behaviors, or include/exclude specific handlers. This is useful when working with environments like .NET Aspire where you might need to limit handler registration.

Manual Registration

If you need complete control or want to bypass the automatic assembly scanning, you can disable automatic registration and add your pipelines, notification handlers, or stream pipeline behaviors manually using standard DI registration.

// Quick setup
builder.Services.AddDispatchR(typeof(MyCommand).Assembly, withPipelines: true, withNotifications: true);

// Advanced setup
builder.Services.AddDispatchR(options =>
{
    options.Assemblies.Add(typeof(DispatchRSample.Ping).Assembly);
    options.RegisterPipelines = true;
    options.RegisterNotifications = true;
    options.PipelineOrder = 
    [
        typeof(DispatchRSample.FirstPipelineBehavior),
        typeof(DispatchRSample.SecondPipelineBehavior),
        typeof(DispatchRSample.GenericPipelineBehavior<,>)
    ];
    options.IncludeHandlers = null;
    options.ExcludeHandlers = null;
});

// Manual registration
builder.Services.AddDispatchR(typeof(MyCommand).Assembly, withPipelines: false, withNotifications: false);
builder.Services.AddScoped<IPipelineBehavior<MyCommand, int>, PipelineBehavior>();
builder.Services.AddScoped<IPipelineBehavior<MyCommand, int>, ValidationBehavior>();
builder.Services.AddScoped<IStreamPipelineBehavior<MyStreamCommand, int>, ValidationBehavior>();
builder.Services.AddScoped<INotificationHandler<Event>, EventHandler>();

Stream requests allow for asynchronous streaming of results using IAsyncEnumerable<T>.

1. Request: Implement IStreamRequest<TRequest, TResponse>.
2. Handler: Implement IStreamRequestHandler<TRequest, TResponse> returning IAsyncEnumerable<TResponse>.
3. Pipeline: Implement IStreamPipelineBehavior<TRequest, TResponse> using the Chain of Responsibility pattern by calling NextPipeline.Handle.

// Request
public sealed class CounterStreamRequestDispatchR : IStreamRequest<CounterStreamRequestDispatchR, int> { }

// Handler
public sealed class CounterStreamHandlerDispatchR : IStreamRequestHandler<CounterStreamRequestDispatchR, int>
{
    public async IAsyncEnumerable<int> Handle(CounterStreamRequestDispatchR request, CancellationToken cancellationToken)
    {
        yield return 1;
    }
}

// Pipeline
public sealed class CounterPipelineStreamHandler : IStreamPipelineBehavior<CounterStreamRequestDispatchR, string>
{
    public required IStreamRequestHandler<CounterStreamRequestDispatchR, string> NextPipeline { get; set; }
    
    public async IAsyncEnumerable<string> Handle(CounterStreamRequestDispatchR request, [EnumeratorCancellation] CancellationToken cancellationToken)
    {
        await foreach (var response in NextPipeline.Handle(request, cancellationToken).ConfigureAwait(false))
        {
            yield return response;
        }
    }
}

Notifications are one-way messages that do not return a value. Implement INotification for the event and INotificationHandler<TNotification> for the handler.

For cross-cutting concerns like logging or auditing, you can implement an open-generic handler that intercepts every notification type by using a generic constraint on INotification.

// Notification
public sealed record Event(Guid Id) : INotification;

// Specific Handler
public sealed class EventHandler(ILogger<Event> logger) : INotificationHandler<Event>
{
    public ValueTask Handle(Event notification, CancellationToken cancellationToken)
    {
        return ValueTask.CompletedTask;
    }
}

// Open-generic handler for ALL notifications
public sealed class AllNotificationsLogger<TNotification>(ILogger<AllNotificationsLogger<TNotification>> logger)
    : INotificationHandler<TNotification>
    where TNotification : INotification
{
    public ValueTask Handle(TNotification notification, CancellationToken cancellationToken)
    {
        logger.LogInformation("Received notification of type {NotificationType}", typeof(TNotification).Name);
        return ValueTask.CompletedTask;
    }
}