Class ThreadingDispatchBuilderExtensions
- Namespace
- Microsoft.Extensions.DependencyInjection
- Assembly
- Excalibur.Dispatch.dll
Extension methods for configuring threading and concurrency features in the Dispatch message processing pipeline. Provides fluent API for enabling parallel processing, thread pooling, keyed locking, and performance optimization.
public static class ThreadingDispatchBuilderExtensions
- Inheritance
-
ThreadingDispatchBuilderExtensions
- Inherited Members
Remarks
These extensions enable fine-grained control over message processing concurrency, allowing applications to optimize throughput, resource utilization, and system responsiveness based on specific workload characteristics and infrastructure constraints.
Threading configuration should be coordinated with other system resources including: - Database connection pooling limits - External service rate limits and capacity - Memory availability and garbage collection patterns - CPU utilization and thermal constraints.
Methods
UseThreading(IDispatchBuilder)
Adds essential threading services to the Dispatch message processing pipeline. Enables concurrent message processing, thread pool management, and synchronization primitives.
public static IDispatchBuilder UseThreading(this IDispatchBuilder builder)
Parameters
builderIDispatchBuilderThe dispatch builder to configure with threading capabilities.
Returns
- IDispatchBuilder
The dispatch builder for fluent configuration chaining.
Remarks
This method registers core threading services including: - Parallel message processing coordinators - Thread-safe message queuing mechanisms - Synchronization primitives for resource coordination - Performance monitoring and metrics collection.
Should be called early in the configuration pipeline before other features that depend on concurrent processing capabilities.
Exceptions
- ArgumentNullException
Thrown when
builderis null.
WithKeyedLock(IDispatchBuilder, IKeyedLock)
Registers a custom keyed lock implementation for coordinating access to shared resources. Enables fine-grained synchronization based on message keys, entity IDs, or other business identifiers.
public static IDispatchBuilder WithKeyedLock(this IDispatchBuilder builder, IKeyedLock keyedLock)
Parameters
builderIDispatchBuilderThe dispatch builder to configure with keyed locking.
keyedLockIKeyedLockThe keyed lock implementation to register as a singleton service.
Returns
- IDispatchBuilder
The dispatch builder for fluent configuration chaining.
Remarks
Keyed locking enables sophisticated coordination patterns including: - Entity-level locking to prevent concurrent modification conflicts - Partition-based locking for scalable resource access control - Business rule enforcement through synchronized processing - Integration with external locking services (Redis, database locks, etc.)
The provided implementation should be thread-safe and efficient, as it will be used concurrently across the entire message processing pipeline.
Exceptions
- ArgumentNullException
Thrown when
builderorkeyedLockis null.
WithThreadingOptions(IDispatchBuilder, IConfiguration)
Configures threading options from configuration sources (appsettings.json, environment variables, etc.). Enables externalized configuration management for threading parameters in deployment scenarios.
[RequiresDynamicCode("Configuration binding requires dynamic code generation for property reflection and value conversion.")]
public static IDispatchBuilder WithThreadingOptions(this IDispatchBuilder builder, IConfiguration configuration)
Parameters
builderIDispatchBuilderThe dispatch builder to configure with threading options.
configurationIConfigurationThe configuration section containing threading options.
Returns
- IDispatchBuilder
The dispatch builder for fluent configuration chaining.
Remarks
This method enables configuration binding from external sources, supporting: - Environment-specific configuration files (appsettings.Development.json, appsettings.Production.json) - Environment variable overrides for containerized deployments - Configuration providers (Azure Key Vault, AWS Systems Manager, Kubernetes ConfigMaps) - Hot configuration reloading in supported hosting environments.
Configuration binding follows standard .NET conventions for property mapping and type conversion. See ThreadingOptions documentation for available settings.
Binding threading options also registers the threading DI services (the keyed-lock singleton, the
options validator, and BackgroundExecutionMiddleware as a resolvable service) as part of this
call - a separate UseThreading(IDispatchBuilder) call is not required for the options/keyed-lock services.
This does not add background execution to the message pipeline: that middleware only
runs handlers in the background once UseBackgroundExecution(IDispatchBuilder)
is called to insert it.
Exceptions
- ArgumentNullException
Thrown when
builderorconfigurationis null.
WithThreadingOptions(IDispatchBuilder, Action<ThreadingOptions>)
Configures threading options using a delegate for programmatic configuration. Provides maximum flexibility for dynamic threading parameter adjustment based on runtime conditions.
public static IDispatchBuilder WithThreadingOptions(this IDispatchBuilder builder, Action<ThreadingOptions> configure)
Parameters
builderIDispatchBuilderThe dispatch builder to configure with threading options.
configureAction<ThreadingOptions>A delegate that receives a ThreadingOptions instance for configuration.
Returns
- IDispatchBuilder
The dispatch builder for fluent configuration chaining.
Remarks
This overload enables programmatic configuration of threading parameters, allowing applications to adjust concurrency settings based on: - Runtime environment detection (CPU cores, memory) - Application-specific performance requirements - Dynamic load balancing and auto-scaling scenarios.
The configure delegate is executed during service registration, enabling access to dependency injection services for complex configuration logic.
Configuring threading options also registers the threading DI services (the keyed-lock singleton, the
options validator, and BackgroundExecutionMiddleware as a resolvable service) as part of this
call - a separate UseThreading(IDispatchBuilder) call is not required for the options/keyed-lock services.
Registration is idempotent and safe to combine with UseThreading(IDispatchBuilder). This does not
add background execution to the message pipeline: that middleware only runs handlers in the background
once UseBackgroundExecution(IDispatchBuilder) is called to insert it.
Exceptions
- ArgumentNullException
Thrown when
builderorconfigureis null.