Table of Contents

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

builder IDispatchBuilder

The 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 builder is 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

builder IDispatchBuilder

The dispatch builder to configure with keyed locking.

keyedLock IKeyedLock

The 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 builder or keyedLock is 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

builder IDispatchBuilder

The dispatch builder to configure with threading options.

configuration IConfiguration

The 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 builder or configuration is 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

builder IDispatchBuilder

The dispatch builder to configure with threading options.

configure Action<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 builder or configure is null.