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
builderIDispatchBuilderThe dispatch builder.
assemblyAssemblyAssembly to scan for handlers.
lifetimeServiceLifetimeService lifetime for registered handlers. Default is Transient.
registerWithContainerboolWhether to register the discovered handlers with the DI container. Default is
true. Whenfalse, nothing fromassemblyis 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:
- IDispatchHandler<TMessage> - General dispatch handlers
- IActionHandler<TAction> and IActionHandler<TAction, TResult> - Action handlers
- IEventHandler<TEvent> - Event handlers
- IDocumentHandler<TDocument> - Document handlers
- IStreamingDocumentHandler<TDocument, TOutput> - Streaming output handlers
- IStreamConsumerHandler<TDocument> - Stream consumer handlers
- IStreamTransformHandler<TInput, TOutput> - Stream transform handlers
- IProgressDocumentHandler<TDocument> - Progress-reporting handlers
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
builderIDispatchBuilderThe dispatch builder.
assembliesAssembly[]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
builderorassembliesis null, or when any element inassembliesis 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
builderIDispatchBuilderThe 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
builderis 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
builderIDispatchBuilderThe dispatch builder.
profileNamestringName of the pipeline profile.
configureAction<IPipelineBuilder>Pipeline configuration action.
Returns
- IDispatchBuilder
The dispatch builder for chaining.