ModernMediator

Introduction

ModernMediator is a feature-rich mediator pattern library for .NET that facilitates decoupled communication between components in your applications. This tutorial will guide you through every major feature of the library, helping you understand when and how to use each capability.

By the end of this tutorial, you will understand:

• Request/Response pattern for commands and queries
• Pipeline Behaviors and Pre/Post Processors for cross-cutting concerns
• Streaming with IAsyncEnumerable for efficient data delivery
• Source Generators for Native AOT compatibility and compile-time safety
• Exception handling strategies and error policies
• Pub/Sub with Callbacks for multi-handler response aggregation
• Subscription options including weak/strong references, filters, and covariance
• UI Dispatchers for thread-safe updates across WPF, WinForms, MAUI, Avalonia, and ASP.NET Core
• Registration strategies including assembly scanning and manual DI registration
• Async-first design with true parallelism and cancellation support

Request/Response Pattern

Request/Response is the foundational pattern in ModernMediator. It models a simple interaction: you want something, and you expect an answer.

How It Works

1. Define a request class implementing IRequest<TResponse>
2. Define a handler implementing IRequestHandler<TRequest, TResponse>
3. The handler's Handle method receives the request and returns the response
4. Call mediator.Send<TResponse>(request) to execute

Benefits

Streaming

Streaming allows a handler to return results incrementally rather than all at once. Instead of waiting for an entire collection to be built and returned, the consumer receives items as they become available.

In .NET, this is powered by IAsyncEnumerable<T>, a feature that lets you await foreach over items as they're yielded, one at a time.

How It Works

1. Define a streaming request implementing IStreamRequest<TItem>
2. Define a handler implementing IStreamRequestHandler<TRequest, TItem>
3. The handler's method uses yield return to emit items
4. Call mediator.CreateStream<TItem>(request) to get the IAsyncEnumerable<TItem>
5. Consume with await foreach

Benefits

Pub/Sub with Callbacks

In traditional Publish/Subscribe, a publisher broadcasts a message and multiple subscribers can receive it. It's fire-and-forget, the publisher doesn't know or care who handles the message, and no response comes back.

Pub/Sub with Callbacks extends this pattern by allowing subscribers to respond. The publisher still broadcasts to multiple subscribers, but now it can collect a response from each one.

This is a hybrid: the one-to-many broadcast of pub/sub combined with the response capability of request/response.

Pattern Comparison

Common Use Cases

Pipeline Behaviors

Pipeline Behaviors are middleware for your mediator. They wrap around the entire request/response flow, allowing you to execute logic both before and after the handler runs, all within a single class.

Think of them like layers of an onion: the request passes through each behavior on the way in, hits the handler at the center, then passes back through each behavior on the way out.

How It Works

1. Implement IPipelineBehavior<TRequest, TResponse>
2. The Handle method receives the request and a next delegate
3. Call await next(request, cancellationToken) to continue the pipeline and get the response
4. Add logic before and/or after the next(request, cancellationToken) call

Common Use Cases

• Logging: log before, log result after
• Validation: reject bad requests before they reach the handler
• Performance timing: start stopwatch before, stop after
• Transaction management: begin before, commit/rollback after
• Exception handling: wrap next(request, cancellationToken) in try/catch

Pre/Post Processors

Pre/Post Processors are a simpler, more focused alternative to full pipeline behaviors. Instead of wrapping the handler, they run strictly before or strictly after it.

When to Use Processors vs Behaviors

Exception Handlers

Exception Handlers provide a centralized way to deal with exceptions that occur during request processing. Instead of wrapping every Send call in try/catch blocks throughout your application, you define exception handling logic once and it applies across your mediator pipeline.

How It Works

1. Implement IExceptionHandler<TRequest, TResponse, TException>
2. The handler receives the request, the exception, and can determine the outcome
3. You can suppress the exception, rethrow it, return a fallback response, or transform it

Common Use Cases

ValueTask Pipeline

The ValueTask pipeline is a zero-allocation fast path for handlers that complete synchronously. When a handler returns a cached or pre-computed result, the entire pipeline avoids allocating a Task object on the heap.

Implement IValueTaskRequestHandler<TRequest, TResponse> instead of IRequestHandler, and call sender.SendAsync<TResponse>(request) instead of Send. The corresponding pipeline behavior interface is IValueTaskPipelineBehavior<TRequest, TResponse>.

Benefits

Built-in Behaviors

ModernMediator ships with four production-ready pipeline behaviors that cover the most common cross-cutting concerns. Each is registered via a single fluent method call on the configuration builder.

Recommended Registration Order

Behaviors execute in registration order, first registered is outermost. Register built-in behaviors in this sequence so each layer wraps the one inside it correctly:

Result<T> Pattern

Result<T> is a readonly struct that represents either a success value or an error, without throwing exceptions. It enables explicit error handling through return values instead of exceptions, making failure paths visible in method signatures.

Results support implicit conversions from both T (success) and ResultError (failure), so handlers can simply return value or return new ResultError("message"). The Map, GetValueOrDefault, and pattern-matching APIs make consuming results ergonomic.

Benefits

Endpoint Generation

The [Endpoint] attribute on a request record tells the ModernMediator.AspNetCore source generator to emit a Minimal API endpoint at compile time. At startup, a single call to app.MapMediatorEndpoints() wires all generated endpoints into the ASP.NET Core routing pipeline.

The generator validates your endpoint declarations at build time. The MM200 diagnostic warns when an invalid HTTP method is specified, catching configuration errors before deployment. (MM200 is the AspNetCore endpoint generator's compile-time code; the unrelated runtime code [MM201] covers dispatcher overload mismatch and is documented in Dispatcher Overload Mismatch.)

Benefits

Telemetry

ModernMediator includes built-in OpenTelemetry support via MediatorTelemetry. An ActivitySource emits distributed traces for every request, and a Meter records RequestCounter and RequestDuration metrics. These integrate with any OpenTelemetry-compatible backend (Jaeger, Zipkin, Prometheus, Azure Monitor, etc.).

Enable telemetry by calling AddTelemetry() during registration. The TelemetryBehavior pipeline behavior wraps each request in an Activity span and records timing metrics automatically.

What Gets Recorded

ISender / IPublisher / IStreamer

ModernMediator follows the Interface Segregation Principle by splitting capabilities into focused interfaces. Instead of depending on the full IMediator, components can depend only on the capability they need.

Injecting the narrowest interface makes dependencies explicit and prevents misuse, a service that only sends commands cannot accidentally publish notifications.

ModernMediator routes notifications along two delivery paths: IPublisher.Publish invokes DI-resolved INotificationHandler<T> instances, while the sync IMediator.Publish<T> and async IMediator.PublishAsync<T> overloads invoke runtime Subscribe<T> and SubscribeAsync<T> callbacks. Both paths participate uniformly in the configured ErrorPolicy and observe the HandlerError event with the same HandlerErrorEventArgs shape, so choosing the narrowest interface for a given component does not cost the developer anything in the unified error-handling story.

Source Generators

Source Generators are a C# compiler feature that generates additional code at compile time. Instead of discovering handlers and wiring things up at runtime using reflection, the generator inspects your code during compilation and writes the registration code for you.

The result: your application starts with all mediator wiring already baked in.

Benefits

Compile-Time Diagnostics

ModernMediator's source generator doesn't just wire things up, it validates your code and reports problems as compiler warnings or errors.

CachingMode (Eager vs Lazy)

CachingMode controls when ModernMediator resolves and caches handler instances. This affects both startup performance and first-request latency.

When to Use Each

Weak/Strong References

When you subscribe a handler to the mediator, the mediator must hold a reference to that handler so it can invoke it later. The type of reference determines whether the handler can be garbage collected.

In long-lived applications, especially UI applications, handlers are often tied to objects with shorter lifespans (views, view models, components). If the mediator holds strong references, those objects can never be garbage collected, causing memory leaks.

When to Use Each

Predicate Filters

Predicate filters allow a subscriber to conditionally receive messages based on the message content. Instead of receiving every published message of a given type, the handler only receives messages that pass its filter.

When subscribing, you provide a predicate function, a condition that evaluates the message and returns true or false. The handler is only invoked when the predicate returns true.

Example Scenarios

Covariance

Covariance allows a handler subscribed to a base type to receive messages of derived types. It's inheritance-aware message routing.

If you have a class hierarchy (Animal with Dog and Cat as subclasses), a handler subscribed to Animal will receive Dog messages, Cat messages, and Animal messages. The subscription covers the entire hierarchy below it.

Practical Examples

Covariance enables powerful patterns: a logging handler subscribed to a base event type logs all events; an audit handler for EntityChanged captures all entity modifications; a base exception handler catches anything more specific handlers miss.

UI Dispatchers

UI frameworks have a fundamental rule: only the main thread (the UI thread) can update the user interface. When work happens on a background thread, as it often does with async handlers, the results must be marshaled back to the UI thread before updating any controls.

Dispatchers automatically route handler responses back to the appropriate thread. Your handlers can run on any thread, but when they complete, the dispatcher ensures the result arrives on the UI thread, ready to bind to your views.

Platform-Specific Threading Models

Benefits

Assembly Scanning and Manual DI Registration

Assembly Scanning

Assembly scanning is automatic discovery. At startup, ModernMediator scans your compiled assemblies, finds all classes implementing handler interfaces, and registers them with the dependency injection container automatically.

Manual DI Registration

Manual registration is explicit wiring. You write code that specifically registers each handler with the dependency injection container. Nothing is automatic, every handler appears in your configuration.

Choosing Between Them

Async-First Design

ModernMediator is built from the ground up for async operations. Async isn't an afterthought or an adapter over synchronous code, it's the primary execution model.

True Async Handlers

When you use SubscribeAsync, handlers are genuinely asynchronous. When multiple handlers exist for a notification, they execute concurrently using Task.WhenAll. The mediator awaits all handlers together, not one after another.

Cancellation Support

All async operations in ModernMediator accept and respect CancellationToken. When a cancellation is requested, handlers can exit early and the mediator propagates the cancellation appropriately.

Parallel Execution

When a notification is published to multiple subscribers, handlers execute concurrently rather than sequentially. This maximizes throughput for independent operations.

Error Handling

Beyond IExceptionHandler for custom exception handling logic, ModernMediator also provides policies and events for broader error management.

Three Error Policies

Error policies define how the mediator behaves when a handler throws an exception, especially in multi-handler scenarios like pub/sub.

HandlerError Event

HandlerError is a universal observation channel. It fires for every handler exception under every ErrorPolicy, regardless of which dispatch path produced the exception. The policy governs propagation and aggregation; the event governs observation. The same subscription receives events from handlers registered as INotificationHandler<T> and resolved via DI, and from runtime callbacks registered via Subscribe<T> or SubscribeAsync<T>.

Subscribers receive a HandlerErrorEventArgs with the following properties:

Cooperative cancellation is treated as distinct from a handler fault. When the publish token's IsCancellationRequested is true and a handler throws OperationCanceledException, the event does not fire and the policy does not apply. The exception propagates from Publish unconditionally.

For consumers who want to route contained subscriber exceptions to a specific observability system rather than the default ILogger route, register an ISubscriberExceptionSink implementation in the service collection. The sink receives the same HandlerErrorEventArgs the HandlerError event fires with, but routes through DI rather than an event subscription, so the implementation is registered once at composition time and can take any constructor dependencies the container can resolve. (v2.2)

Exception Unwrapping

When handlers are invoked through reflection or dynamic dispatch, exceptions get wrapped in TargetInvocationException or AggregateException. Stack traces become cluttered with framework noise, making debugging harder.

Exceptions are automatically unwrapped before being thrown or passed to exception handlers. You see the original exception with a clean stack trace pointing directly to your code.

Dispatcher Overload Mismatch (MM009 / MM201)

A request handler implements either IRequestHandler<TRequest, TResponse> (Task-based) or IValueTaskRequestHandler<TRequest, TResponse> (ValueTask-based). The dispatcher exposes a parallel pair of methods: Send for Task handlers and SendAsync for ValueTask handlers. Calling the wrong method for a given handler is the dispatcher overload mismatch, and v2.2 surfaces it through two complementary channels.

MM009 (compile-time) is a Roslyn analyzer warning emitted by ModernMediator.Generators. The analyzer walks Send / SendAsync invocations, recovers the request type from the argument, and looks it up against a per-compilation registry of handler declarations. When the consumer's call site does not match the handler's interface, the analyzer surfaces the warning at the invocation in the IDE error list, before the runtime check ever fires.

MM201 (runtime) is an InvalidOperationException with a bracketed prefix, thrown by the dispatcher when no handler is registered for the requested interface but a handler exists under the alternate interface. The runtime check covers the cross-assembly case the analyzer cannot see: a handler registered in a precompiled NuGet dependency that the consumer's compilation does not contain a syntactic declaration for.

Both codes describe the same condition; the codes are intentionally distinct because the channels are distinct. MM009 in build output points to the source-gen detector; [MM201] in an exception message points to the runtime check. Consumers who want stricter enforcement can promote MM009 to error via <WarningsAsErrors> or an .editorconfig severity override.

MM202 (runtime) is the second occupant of the MM2xx slot established by ADR-008. It surfaces from a different path than MM201: the source-generator-emitted Send and CreateStream extension methods throw an InvalidOperationException with the [MM202] prefix when IServiceProvider.GetService returns null for the expected IRequestHandler<,> or IStreamRequestHandler<,>. The message points at AddModernMediatorGenerated() as the corrective action, typically the symptom of a missing call to the generated registration helper after assembly scanning was disabled or replaced.

Example

Given a handler registered as IValueTaskRequestHandler:

public sealed record GetUserQuery(int Id) : IRequest<User>;

public sealed class GetUserHandler : IValueTaskRequestHandler<GetUserQuery, User>
{
    public ValueTask<User> Handle(GetUserQuery request, CancellationToken ct) => /* ... */;
}

The wrong call site triggers MM009 at compile time:

// MM009: GetUserQuery is registered as IValueTaskRequestHandler;
//        call SendAsync instead of Send.
var user = await mediator.Send(new GetUserQuery(42));

If the same condition reaches runtime (for example, the handler lives in a precompiled assembly the analyzer cannot inspect), MM201 fires:

// InvalidOperationException:
// [MM201] No IRequestHandler<GetUserQuery, User> is registered, but
// IValueTaskRequestHandler<GetUserQuery, User> is. Call SendAsync instead of Send.
var user = await mediator.Send(new GetUserQuery(42));

See ADR-009 (runtime check) and ADR-010 (source-gen analyzer) for the design rationale and the relationship between the two codes.

Validation Overloads

v2.2 expands AddModernMediatorValidation with overloads that accept either a single Assembly or a marker type via typeof(T).Assembly, matching the registration ergonomics of RegisterServicesFromAssembly / RegisterServicesFromAssemblyContaining. The single call scans the supplied assembly for FluentValidation validators, registers them in the container, and wires ValidationBehavior<TRequest, TResponse> into the pipeline. Validators are resolved per-request and run before the handler executes; failures short-circuit with a ValidationException (or, when the request returns a Result<T>, a failure result that carries the validation errors).

The overload set lets a consumer register validators from the executing assembly with one line:

services.AddModernMediatorValidation(typeof(Program).Assembly);

Or from a marker type when validators live in a separate project:

services.AddModernMediatorValidation(typeof(MyValidatorMarker).Assembly);

The behavior package (ModernMediator.FluentValidation) is a separate NuGet reference; the core ModernMediator package does not pull in FluentValidation by default.

Audit Behavior

AuditBehavior captures a structured record of every request that passes through the pipeline, including the request type, current user identity, correlation ID, duration, and whether the request succeeded or failed. Records are dispatched asynchronously to any IAuditWriter implementation, so writing to Serilog, a database, or a custom sink requires no changes to the behavior itself.

Individual request types can opt out of auditing by decorating the request record with [NoAudit]. Audit drain is handled by a hosted background service registered automatically by AddAudit<TWriter>(), which processes records from an in-memory channel without blocking the request pipeline.

What Gets Recorded

Available Writers

Idempotency Behavior

IdempotencyBehavior prevents duplicate processing of requests that have already been handled. A request marked with [Idempotent] is identified by a fingerprint derived from the request content and type. If a matching fingerprint exists in the configured IIdempotencyStore and has not expired, the cached response is returned immediately, the handler never runs.

This is essential for operations that must not be applied twice: payments, order submissions, inventory adjustments, or any command where retries from network failures could cause duplicate side effects.

Store Options

Circuit Breaker Behavior

CircuitBreakerBehavior protects your application from repeatedly calling a handler that is known to be failing. When a request type decorated with [CircuitBreaker] accumulates enough consecutive failures, the circuit opens. While open, subsequent requests for that type are rejected immediately with CircuitBreakerOpenException, no handler invocation occurs.

After a configured timeout, the circuit moves to half-open and allows a single probe request through. If it succeeds, the circuit closes and normal operation resumes. If it fails, the circuit reopens.

Circuit States

Retry Behavior

RetryBehavior automatically retries a failing handler a configurable number of times before allowing the exception to propagate. The delay between attempts is controlled by a RetryDelayStrategy, allowing you to implement immediate retry, fixed delay, linear backoff, or exponential backoff depending on the failure characteristics of the handler.

Apply the [Retry] attribute to any request type to opt in. Requests without the attribute are unaffected.

Delay Strategies

Current User Accessor

ICurrentUserAccessor is an abstraction that pipeline behaviors use to resolve the identity of the current user without depending on a specific platform or authentication mechanism. The AuditBehavior uses it to populate the UserId field on every audit record.

HttpContextCurrentUserAccessor (in ModernMediator.AspNetCore) is the built-in implementation for ASP.NET Core. It resolves UserId from the NameIdentifier claim and UserName from the Name claim via IHttpContextAccessor. It is auto-registered when you call config.AddAudit<TWriter>(o => o.UseHttpContextIdentity(services)). For applications that do not use the audit pipeline but still want the accessor available, register it manually via services.AddSingleton<ICurrentUserAccessor, HttpContextCurrentUserAccessor>().

For non-ASP.NET Core applications, implement ICurrentUserAccessor directly and register it with the DI container before calling AddAudit().

Summary

ModernMediator provides a comprehensive set of features for building decoupled, maintainable applications in .NET. This tutorial has covered the core capabilities that make the library powerful and flexible.

Features Covered

• Request/Response Pattern: The foundational one-to-one message handling pattern for commands and queries
• Pipeline Behaviors: Middleware that wraps handler execution for cross-cutting concerns
• Pre/Post Processors: Simpler alternatives to behaviors when you only need before or after logic
• Streaming: Memory-efficient, responsive data delivery using IAsyncEnumerable
• Source Generators: Compile-time handler discovery for Native AOT compatibility
• Exception Handlers: Centralized exception handling without scattered try/catch blocks
• CachingMode: Control over handler resolution timing with Eager and Lazy options
• Pub/Sub with Callbacks: Multi-handler broadcasting with response aggregation
• Weak/Strong References: Memory management control for subscription lifecycles
• Predicate Filters: Conditional message reception based on content
• Covariance: Inheritance-aware message routing for flexible subscriptions
• UI Dispatchers: Thread-safe response delivery across WPF, WinForms, MAUI, Avalonia, and ASP.NET Core
• Assembly Scanning and Manual DI Registration: Flexible handler registration strategies
• Async-First Design: True parallelism with Task.WhenAll and full cancellation support
• Error Handling: Configurable policies, centralized events, and clean exception unwrapping
• ValueTask Pipeline: Zero-allocation fast path via IValueTaskRequestHandler and SendAsync
• Built-in Behaviors: Production-ready Logging, Timeout, Validation, and Telemetry behaviors
• Result<T> Pattern: Readonly struct for explicit success/error handling without exceptions
• Endpoint Generation: Source-generated Minimal API endpoints via [Endpoint] attribute
• Telemetry: OpenTelemetry traces and metrics with ActivitySource and Meter
• Interface Segregation: ISender, IPublisher, and IStreamer for focused dependencies
• Audit Behavior: per-request audit recording dispatched to any IAuditWriter; Serilog and EF Core writers available as separate packages
• Idempotency Behavior: duplicate request prevention via [Idempotent] attribute with pluggable store; in-memory, distributed cache, and EF Core stores included
• Circuit Breaker Behavior: per-request-type circuit breaker via [CircuitBreaker] attribute with closed/open/half-open state management
• Retry Behavior: automatic retry with configurable count and delay strategy (None, Fixed, Linear, Exponential) via [Retry] attribute
• Current User Accessor: ICurrentUserAccessor abstraction with HttpContextCurrentUserAccessor for ASP.NET Core claim resolution

ModernMediator combines these features into a cohesive library that supports applications from simple desktop tools to complex distributed systems, with first-class support for modern .NET capabilities including Native AOT compilation.