Table of Contents

Class DispatchBuilderExtensions

Namespace
Microsoft.Extensions.DependencyInjection
Assembly
Excalibur.Dispatch.dll

Extension methods for pipeline configuration, handler registration, and assembly scanning.

public static class DispatchBuilderExtensions
Inheritance
DispatchBuilderExtensions
Inherited Members

Methods

AddHandlersFromAssembly(IDispatchBuilder, Assembly, ServiceLifetime, bool)

Add handlers from the specified assembly with automatic discovery and DI registration.

[UnconditionalSuppressMessage("Trimming", "IL2026:Members annotated with RequiresUnreferencedCodeAttribute may break with trimming", Justification = "Handler types are preserved through assembly scanning and DI registration")]
[UnconditionalSuppressMessage("Trimming", "IL2070:'this' argument does not satisfy 'DynamicallyAccessedMemberTypes.Interfaces'", Justification = "Handler types are preserved through assembly scanning and DI registration")]
[UnconditionalSuppressMessage("Trimming", "IL2072:'target parameter' argument does not satisfy 'DynamicallyAccessedMemberTypes.PublicConstructors'", Justification = "Handler types are preserved through assembly scanning and DI registration")]
[UnconditionalSuppressMessage("Trimming", "IL2075:'this' argument does not satisfy 'DynamicallyAccessedMemberTypes.Interfaces'", Justification = "Handler types are preserved through assembly scanning and DI registration")]
public static IDispatchBuilder AddHandlersFromAssembly(this IDispatchBuilder builder, Assembly assembly, ServiceLifetime lifetime = ServiceLifetime.Transient, bool registerWithContainer = true)

Parameters

builder IDispatchBuilder

The dispatch builder.

assembly Assembly

Assembly to scan for handlers.

lifetime ServiceLifetime

Service lifetime for registered handlers. Default is Transient.

registerWithContainer bool

Whether to register the discovered handlers with the DI container. Default is true. When false, nothing from assembly is registered -- neither the concrete handler types nor their handler interfaces -- and the caller is responsible for registering every handler it wants dispatched.

Returns

IDispatchBuilder

The dispatch builder for chaining.

Examples

// Default: registers handlers with Transient lifetime
services.AddDispatch(dispatch =>
{
    dispatch.AddHandlersFromAssembly(typeof(Program).Assembly);
});

// Custom lifetime
services.AddDispatch(dispatch =>
{
    dispatch.AddHandlersFromAssembly(typeof(Program).Assembly, ServiceLifetime.Transient);
});

// Register nothing from this assembly -- you register every handler yourself (advanced scenarios)
services.AddDispatch(dispatch =>
{
    dispatch.AddHandlersFromAssembly(typeof(Program).Assembly, registerWithContainer: false);
});

Remarks

This method scans the assembly for all handler implementations and registers them:

By default, handlers are registered with the DI container so they can be resolved without explicit registration. Set registerWithContainer to false for advanced scenarios where you want to control handler registration separately. The call still marks handler registration as caller-owned, so the zero-configuration scan of the entry assembly does not run.

Scanning never displaces a handler you registered yourself, in either call order. A handler you register for a message type that expects a single handler wins over the scanned one; a handler you register for an event runs alongside the scanned handlers for that event, and is not run twice if scanning also discovers it.

AddHandlersFromAssembly(IDispatchBuilder, params Assembly[])

Add handlers from multiple assemblies with automatic discovery and DI registration.

[RequiresUnreferencedCode("Assembly scanning uses reflection to discover handler types.")]
public static IDispatchBuilder AddHandlersFromAssembly(this IDispatchBuilder builder, params Assembly[] assemblies)

Parameters

builder IDispatchBuilder

The dispatch builder.

assemblies Assembly[]

Assemblies to scan for handlers.

Returns

IDispatchBuilder

The dispatch builder for chaining.

Examples

services.AddDispatch(dispatch =>
{
    dispatch.AddHandlersFromAssembly(
        typeof(OrderHandler).Assembly,
        typeof(CustomerHandler).Assembly);
});

Remarks

This overload scans multiple assemblies using the default Transient lifetime and registers handlers with the DI container. For custom lifetime or container registration control, call the single-assembly overload per assembly.

Exceptions

ArgumentNullException

Thrown when builder or assemblies is null, or when any element in assemblies is null.

AddHandlersFromEntryAssembly(IDispatchBuilder)

Adds every message handler found in the entry assembly, discovered by scanning it.

[RequiresUnreferencedCode("Scans the entry assembly for handler types, which trimming may remove. Name your handlers -- with the source-generated registration for an ahead-of-time compatible composition -- instead.")]
[RequiresDynamicCode("Scans the entry assembly for handler types and constructs typed invokers at runtime. Name your handlers -- with the source-generated registration for an ahead-of-time compatible composition -- instead.")]
public static IDispatchBuilder AddHandlersFromEntryAssembly(this IDispatchBuilder builder)

Parameters

builder IDispatchBuilder

The dispatch builder.

Returns

IDispatchBuilder

The dispatch builder for chaining.

Remarks

This is the zero-configuration handler registration: a composition that names no handler of its own gets the handlers of the application that is running. It is a scan and it says so, so a trimmed or ahead-of-time compiled application must name its handlers instead.

Handlers are registered Transient explicitly rather than by inheriting the default of the opt-in API, because this registration is implicit: the consumer named neither a handler nor a lifetime, so what is imposed on their behalf is pinned here and does not drift with a default chosen for a different call. Scoped in particular would not merely be a stronger claim than the consumer made, it would be a harmful one — it forces a per-dispatch scope for handlers that capture nothing, because the scope resolver short-circuits on a scoped registration before the constructor walk can prove the handler root-safe, and it hides the handler from the stateless-handler singleton promotion enabled by default, which considers only transient descriptors. Transient costs no safety: the resolver still walks the constructor graph, still demands a scope for a handler that reaches a scoped dependency directly or transitively, and still biases to a scope on any branch it cannot prove.

A host with no entry assembly — one loaded into an unmanaged process — registers nothing here and does not fail.

Exceptions

ArgumentNullException

Thrown when builder is null.

AddPipeline(IDispatchBuilder, string, Action<IPipelineBuilder>)

Add a pipeline profile with specified middleware order and message kind filtering.

public static IDispatchBuilder AddPipeline(this IDispatchBuilder builder, string profileName, Action<IPipelineBuilder> configure)

Parameters

builder IDispatchBuilder

The dispatch builder.

profileName string

Name of the pipeline profile.

configure Action<IPipelineBuilder>

Pipeline configuration action.

Returns

IDispatchBuilder

The dispatch builder for chaining.