Chain of Responsibility Pattern Best Practices in C#: Code Organization and Maintainability
You understand the chain of responsibility pattern. You've built a handler pipeline, linked a few processors together, and watched a request flow through the chain. But getting from "it works" to "it works well in a production codebase" is where the real challenge begins. Chain of responsibility pattern best practices in C# go beyond wiring up handlers -- they cover how to design handlers that stay focused, how to build chains that are explicit and configurable, and how to keep the whole pipeline testable and observable as your application grows.
This guide digs into the practical side of using the pattern well. We'll cover single-responsibility handlers, type-safe generics, explicit chain construction, end-of-chain strategies, observability, and testing approaches. If you need a refresher on the pattern fundamentals and how it compares to other structural approaches, check out how patterns like the decorator or template method tackle similar pipeline problems -- then come back when you're ready to level up your handler chains.
Keep Handlers Single-Responsibility
Among all chain of responsibility pattern best practices in C#, enforcing one concern per handler is the most impactful.Each handler should check one thing, do one thing, or transform one thing. When a handler starts doing authorization AND validation AND logging, you've lost the composability that makes the pattern valuable.
Here's what a bloated handler looks like. Consider an IOrderHandler that processes purchase orders:
using System;
public sealed record Order(
string CustomerId,
decimal Total,
bool IsFraudulent);
public interface IOrderHandler
{
void Handle(Order order);
}
// Bad: One handler doing too much
public sealed class KitchenSinkOrderHandler : IOrderHandler
{
private readonly IOrderHandler? _next;
public KitchenSinkOrderHandler(IOrderHandler? next)
{
_next = next;
}
public void Handle(Order order)
{
// Authentication concern
if (string.IsNullOrWhiteSpace(order.CustomerId))
{
throw new UnauthorizedAccessException(
"Customer ID is required.");
}
// Validation concern
if (order.Total <= 0)
{
throw new ArgumentException(
"Order total must be positive.");
}
// Fraud detection concern
if (order.IsFraudulent)
{
Console.WriteLine(
$"[FRAUD] Blocked order for " +
$"{order.CustomerId}");
return;
}
_next?.Handle(order);
}
}
Now split each concern into its own handler:
using System;
public sealed class AuthenticationOrderHandler : IOrderHandler
{
private readonly IOrderHandler? _next;
public AuthenticationOrderHandler(IOrderHandler? next)
{
_next = next;
}
public void Handle(Order order)
{
if (string.IsNullOrWhiteSpace(order.CustomerId))
{
throw new UnauthorizedAccessException(
"Customer ID is required.");
}
_next?.Handle(order);
}
}
public sealed class ValidationOrderHandler : IOrderHandler
{
private readonly IOrderHandler? _next;
public ValidationOrderHandler(IOrderHandler? next)
{
_next = next;
}
public void Handle(Order order)
{
if (order.Total <= 0)
{
throw new ArgumentException(
"Order total must be positive.",
nameof(order));
}
_next?.Handle(order);
}
}
public sealed class FraudDetectionOrderHandler : IOrderHandler
{
private readonly IOrderHandler? _next;
public FraudDetectionOrderHandler(IOrderHandler? next)
{
_next = next;
}
public void Handle(Order order)
{
if (order.IsFraudulent)
{
Console.WriteLine(
$"[FRAUD] Blocked order for " +
$"{order.CustomerId}");
return;
}
_next?.Handle(order);
}
}
With focused handlers, you gain three significant advantages. First, you can reorder the chain -- maybe fraud detection should run before validation in some scenarios. Second, each handler is trivial to test because it has exactly one code path to verify. Third, adding a new concern means adding a new handler class, not modifying an existing one that's already doing too much.
If a handler's Handle method is growing beyond 15-20 lines of meaningful logic, that's a signal you should split it. The chain of responsibility pattern works best when each link in the chain is small, focused, and independently understandable.
Use Generics for Type-Safe Chains
Another essential chain of responsibility pattern best practice in C# is using generics for type safety. Hardcoding specific types into your handler interfaces limits reuse and introduces runtime errors when the wrong request type gets pushed through a chain. A generic handler interface gives you compile-time safety across all your pipelines.
Here's the foundation:
public interface IHandler<TRequest, TResponse>
{
TResponse Handle(TRequest request);
}
public interface IChainHandler<TRequest, TResponse>
: IHandler<TRequest, TResponse>
{
IChainHandler<TRequest, TResponse>? Next { get; set; }
}
Now each handler is strongly typed to its specific request and response:
using System;
public sealed record PaymentRequest(
string CardNumber,
decimal Amount,
string Currency);
public sealed record PaymentResult(
bool Success,
string Message);
public sealed class CurrencyValidationHandler
: IChainHandler<PaymentRequest, PaymentResult>
{
private static readonly string[] SupportedCurrencies =
["USD", "EUR", "GBP"];
public IChainHandler<PaymentRequest, PaymentResult>?
Next { get; set; }
public PaymentResult Handle(PaymentRequest request)
{
if (Array.IndexOf(
SupportedCurrencies,
request.Currency) < 0)
{
return new PaymentResult(
false,
$"Unsupported currency: " +
$"{request.Currency}");
}
return Next is not null
? Next.Handle(request)
: new PaymentResult(true, "Processed.");
}
}
public sealed class AmountLimitHandler
: IChainHandler<PaymentRequest, PaymentResult>
{
private readonly decimal _maxAmount;
public IChainHandler<PaymentRequest, PaymentResult>?
Next { get; set; }
public AmountLimitHandler(decimal maxAmount)
{
_maxAmount = maxAmount;
}
public PaymentResult Handle(PaymentRequest request)
{
if (request.Amount > _maxAmount)
{
return new PaymentResult(
false,
$"Amount exceeds limit of {_maxAmount}.");
}
return Next is not null
? Next.Handle(request)
: new PaymentResult(true, "Processed.");
}
}
The compiler catches mistakes before they ever reach production. You can't accidentally pass a PaymentRequest into a chain that expects an Order. This is the same kind of type safety you'd get from strongly-typed dependency injection with IServiceCollection, applied to your handler pipeline.
Generics also open the door for cross-cutting middleware-style handlers that work across multiple request types, using constraints to share behavior without sacrificing type safety.
Make Chain Construction Explicit
One of the most overlooked chain of responsibility pattern best practices in C# is making chain assembly visible and intentional. Hidden chain construction -- where handlers magically get wired up in some startup method buried deep in the codebase -- makes debugging painful and ordering mistakes invisible.
A builder pattern for chain assembly solves this:
using System;
using System.Collections.Generic;
public sealed class ChainBuilder<TRequest, TResponse>
{
private readonly List<
Func<IChainHandler<TRequest, TResponse>>>
_factories = [];
public ChainBuilder<TRequest, TResponse> AddHandler(
Func<IChainHandler<TRequest, TResponse>> factory)
{
_factories.Add(factory);
return this;
}
public IHandler<TRequest, TResponse> Build()
{
if (_factories.Count == 0)
{
throw new InvalidOperationException(
"Chain must have at least one handler.");
}
var handlers = new List<
IChainHandler<TRequest, TResponse>>();
foreach (var factory in _factories)
{
handlers.Add(factory());
}
for (int i = 0; i < handlers.Count - 1; i++)
{
handlers[i].Next = handlers[i + 1];
}
return handlers[0];
}
}
Usage becomes fluent and self-documenting:
var chain = new ChainBuilder<PaymentRequest, PaymentResult>()
.AddHandler(() => new CurrencyValidationHandler())
.AddHandler(() => new AmountLimitHandler(10_000m))
.AddHandler(() => new FraudScreeningHandler())
.Build();
PaymentResult result = chain.Handle(
new PaymentRequest("4111111111111111", 500m, "USD"));
Reading this code, the chain order is obvious. Currency validation runs first, then amount limits, then fraud screening. No need to trace through constructor calls or DI registrations to understand the pipeline. If you're using inversion of control containers, you can still build the chain in your composition root -- but make the ordering explicit rather than relying on registration order.
The builder also gives you a natural place to add validation. Want to enforce that every chain ends with a specific handler type? Add that check in Build(). Want to prevent duplicate handler types? Add that check too.
Handle the End of the Chain Gracefully
What happens when a request reaches the last handler and no handler has fully processed it? End-of-chain handling is a chain of responsibility pattern best practice in C# that separates robust pipelines from brittle ones.There are three common strategies, and the right choice depends on your domain.
Option 1: Default handler at the end. Place a catch-all handler that provides a sensible default:
public sealed class DefaultPaymentHandler
: IChainHandler<PaymentRequest, PaymentResult>
{
public IChainHandler<PaymentRequest, PaymentResult>?
Next { get; set; }
public PaymentResult Handle(PaymentRequest request)
{
return new PaymentResult(
true,
"Payment processed with default handler.");
}
}
Option 2: Throw an exception. When reaching the end of the chain means something went wrong, fail loudly:
public sealed class UnhandledRequestHandler
: IChainHandler<PaymentRequest, PaymentResult>
{
public IChainHandler<PaymentRequest, PaymentResult>?
Next { get; set; }
public PaymentResult Handle(PaymentRequest request)
{
throw new InvalidOperationException(
$"No handler processed the payment " +
$"for card ending in " +
$"{request.CardNumber[^4..]}.");
}
}
Option 3: Return a typed result indicating no handler matched. This is the most flexible approach and avoids exceptions for expected scenarios:
public sealed class NoMatchPaymentHandler
: IChainHandler<PaymentRequest, PaymentResult>
{
public IChainHandler<PaymentRequest, PaymentResult>?
Next { get; set; }
public PaymentResult Handle(PaymentRequest request)
{
return new PaymentResult(
false,
"No handler was able to process " +
"this payment request.");
}
}
The default handler approach works well when you have a natural fallback behavior. The exception approach is best for pipelines where every request must be handled -- an unhandled request represents a bug. The result-based approach fits event-driven architectures where not every handler needs to act on every request.
Whatever strategy you choose, make it explicit. Don't let null reference exceptions be your end-of-chain strategy. Wire a terminal handler into your builder so the behavior is documented and testable. This is similar to how the proxy pattern handles access decisions -- be deliberate about what happens at the boundary.
Add Observability to Your Chain
In production, you need to know which handler processed a request, how long each handler took, and whether the chain completed successfully. Without observability, debugging a chain with five or six handlers becomes guesswork.
Here's a logging handler that wraps any existing handler and adds timing information using ILogger:
using System;
using System.Diagnostics;
using Microsoft.Extensions.Logging;
public sealed class ObservableHandler<TRequest, TResponse>
: IChainHandler<TRequest, TResponse>
{
private readonly IChainHandler<TRequest, TResponse>
_inner;
private readonly ILogger _logger;
private readonly string _handlerName;
public IChainHandler<TRequest, TResponse>?
Next { get; set; }
public ObservableHandler(
IChainHandler<TRequest, TResponse> inner,
ILogger logger,
string handlerName)
{
_inner = inner
?? throw new ArgumentNullException(nameof(inner));
_logger = logger
?? throw new ArgumentNullException(nameof(logger));
_handlerName = handlerName;
}
public TResponse Handle(TRequest request)
{
_logger.LogInformation(
"Handler {HandlerName} started processing.",
_handlerName);
var stopwatch = Stopwatch.StartNew();
try
{
var result = _inner.Handle(request);
stopwatch.Stop();
_logger.LogInformation(
"Handler {HandlerName} completed " +
"in {ElapsedMs}ms.",
_handlerName,
stopwatch.ElapsedMilliseconds);
return result;
}
catch (Exception ex)
{
stopwatch.Stop();
_logger.LogError(
ex,
"Handler {HandlerName} failed " +
"after {ElapsedMs}ms.",
_handlerName,
stopwatch.ElapsedMilliseconds);
throw;
}
}
}
You can integrate this into the chain builder so observability becomes opt-in per handler:
using Microsoft.Extensions.Logging;
public sealed class ObservableChainBuilder<TRequest, TResponse>
{
private readonly List<
Func<IChainHandler<TRequest, TResponse>>>
_factories = [];
private readonly ILogger _logger;
public ObservableChainBuilder(ILogger logger)
{
_logger = logger;
}
public ObservableChainBuilder<TRequest, TResponse>
AddHandler(
string name,
Func<IChainHandler<TRequest, TResponse>> factory)
{
_factories.Add(() =>
{
var handler = factory();
return new ObservableHandler<TRequest, TResponse>(
handler, _logger, name);
});
return this;
}
public IHandler<TRequest, TResponse> Build()
{
if (_factories.Count == 0)
{
throw new InvalidOperationException(
"Chain must have at least one handler.");
}
var handlers = new List<
IChainHandler<TRequest, TResponse>>();
foreach (var factory in _factories)
{
handlers.Add(factory());
}
for (int i = 0; i < handlers.Count - 1; i++)
{
handlers[i].Next = handlers[i + 1];
}
return handlers[0];
}
}
With this in place, every handler invocation produces structured log output showing the handler name and elapsed time. When something goes wrong in production, you can trace exactly which handler failed and how long the chain ran before the failure. This approach is conceptually similar to how the observer pattern provides visibility into system events -- you're making the pipeline's internal behavior externally visible.
Testing Handler Chains
Testability is one of the strongest chain of responsibility pattern best practices in C#, and it's a major selling point of a well-structured implementation.Each handler depends on an interface for the next handler in the chain, making isolation straightforward. Here are the key testing strategies and how to apply them.
Unit Test Each Handler in Isolation
Test each handler independently by setting Next to null or to a mock. Verify the handler's specific behavior without worrying about the rest of the chain:
using Xunit;
public sealed class CurrencyValidationHandlerTests
{
[Fact]
public void Handle_UnsupportedCurrency_ReturnsFailure()
{
// Arrange
var handler = new CurrencyValidationHandler();
var request = new PaymentRequest(
"4111111111111111", 100m, "JPY");
// Act
var result = handler.Handle(request);
// Assert
Assert.False(result.Success);
Assert.Contains("Unsupported", result.Message);
}
[Fact]
public void Handle_SupportedCurrency_DelegatesToNext()
{
// Arrange
var handler = new CurrencyValidationHandler();
var nextHandler = new StubHandler(
new PaymentResult(true, "Next handled it."));
handler.Next = nextHandler;
var request = new PaymentRequest(
"4111111111111111", 100m, "USD");
// Act
var result = handler.Handle(request);
// Assert
Assert.True(result.Success);
Assert.Equal("Next handled it.", result.Message);
}
}
Use Stubs to Verify Delegation
A simple stub handler lets you confirm that a handler correctly delegates to the next link:
public sealed class StubHandler
: IChainHandler<PaymentRequest, PaymentResult>
{
private readonly PaymentResult _result;
public IChainHandler<PaymentRequest, PaymentResult>?
Next { get; set; }
public bool WasCalled { get; private set; }
public PaymentRequest? ReceivedRequest { get; private set; }
public StubHandler(PaymentResult result)
{
_result = result;
}
public PaymentResult Handle(PaymentRequest request)
{
WasCalled = true;
ReceivedRequest = request;
return _result;
}
}
Integration Test the Full Chain
After testing handlers individually, verify the assembled chain behaves correctly end to end:
using Xunit;
public sealed class PaymentChainIntegrationTests
{
[Fact]
public void FullChain_ValidRequest_ProcessesSuccessfully()
{
// Arrange
var chain =
new ChainBuilder<PaymentRequest, PaymentResult>()
.AddHandler(
() => new CurrencyValidationHandler())
.AddHandler(
() => new AmountLimitHandler(10_000m))
.AddHandler(
() => new DefaultPaymentHandler())
.Build();
var request = new PaymentRequest(
"4111111111111111", 500m, "USD");
// Act
var result = chain.Handle(request);
// Assert
Assert.True(result.Success);
}
[Fact]
public void FullChain_InvalidCurrency_StopsAtValidation()
{
// Arrange
var chain =
new ChainBuilder<PaymentRequest, PaymentResult>()
.AddHandler(
() => new CurrencyValidationHandler())
.AddHandler(
() => new AmountLimitHandler(10_000m))
.AddHandler(
() => new DefaultPaymentHandler())
.Build();
var request = new PaymentRequest(
"4111111111111111", 500m, "JPY");
// Act
var result = chain.Handle(request);
// Assert
Assert.False(result.Success);
Assert.Contains("Unsupported", result.Message);
}
}
Test That Chain Ordering Matters
Ordering bugs are subtle. A test that verifies the chain behaves differently when handlers are reordered catches these issues early:
using Xunit;
public sealed class ChainOrderingTests
{
[Fact]
public void Handle_AmountBeforeCurrency_RejectsOnAmount()
{
// Arrange: amount check first
var chain =
new ChainBuilder<PaymentRequest, PaymentResult>()
.AddHandler(
() => new AmountLimitHandler(100m))
.AddHandler(
() => new CurrencyValidationHandler())
.Build();
var request = new PaymentRequest(
"4111111111111111", 500m, "JPY");
// Act
var result = chain.Handle(request);
// Assert: rejected by amount, never reaches
// currency check
Assert.False(result.Success);
Assert.Contains("limit", result.Message);
}
[Fact]
public void Handle_CurrencyBeforeAmount_RejectsOnCurrency()
{
// Arrange: currency check first
var chain =
new ChainBuilder<PaymentRequest, PaymentResult>()
.AddHandler(
() => new CurrencyValidationHandler())
.AddHandler(
() => new AmountLimitHandler(100m))
.Build();
var request = new PaymentRequest(
"4111111111111111", 500m, "JPY");
// Act
var result = chain.Handle(request);
// Assert: rejected by currency, never reaches
// amount check
Assert.False(result.Success);
Assert.Contains("Unsupported", result.Message);
}
}
A few testing guidelines worth following. Always verify delegation -- every handler test should confirm the next handler was (or wasn't) called depending on the handler's logic. Test short-circuit behavior specifically -- if a handler should stop the chain for certain inputs, verify that the next handler never sees the request. Keep unit tests fast by avoiding real I/O in handlers -- this is where inversion of control pays off, because you can inject mock dependencies into each handler.
Frequently Asked Questions
How do I decide between chain of responsibility and middleware pipelines in ASP.NET Core?
ASP.NET Core middleware is a chain of responsibility implementation. If your processing logic is HTTP-specific -- authentication, routing, response compression -- use the built-in middleware pipeline. If you need a chain for domain-level processing that's independent of HTTP -- like order validation, approval workflows, or document processing -- build your own chain of responsibility. The patterns are structurally identical; the difference is the context in which they run.
Should handlers be stateless or is mutable state acceptable?
Handlers should be stateless whenever possible. Stateless handlers are inherently thread-safe, easy to test, and safe to register as singletons in your DI container. If a handler needs state -- like a cache or a counter -- isolate that state carefully and use thread-safe data structures from System.Collections.Concurrent. But step back and ask whether the state belongs in the handler at all, or in a service the handler depends on.
How does the chain of responsibility pattern differ from the decorator pattern?
Both patterns chain objects together, but the intent is different. The decorator pattern wraps an object to enhance its behavior -- every decorator in the stack participates. Chain of responsibility passes a request along until one handler decides to process it, potentially stopping the chain. Think of decorators as layers that all contribute, and chain of responsibility as a series of checkpoints where one handler takes ownership.
Can I combine chain of responsibility with dependency injection?
Yes, and it works well. Register each handler in IServiceCollection, then use a factory or builder in your composition root to assemble the chain. The key consideration is handler lifetimes -- if handlers are transient, you build a new chain per request. If they're singletons, make sure they're thread-safe and stateless. The builder pattern shown earlier integrates naturally with DI by accepting factory delegates that resolve handlers from the container.
What naming convention should I use for handlers?
Follow the {Concern}{Entity}Handler pattern: ValidationOrderHandler, FraudDetectionPaymentHandler, AuthenticationRequestHandler. Front-loading the concern makes it easy to scan a list of handlers and understand their purpose. Avoid vague names like OrderProcessor or RequestMiddleware that don't communicate what the handler actually does.
How do I handle async operations in a chain of responsibility?
Define an async handler interface that returns Task<TResponse> and use async/await throughout the chain. Each handler awaits its internal work and then awaits the next handler if delegation is needed. The chain builder works identically -- you're just swapping synchronous method calls for asynchronous ones. Make sure all handlers in the chain are async to avoid mixing sync and async code, which can cause deadlocks in certain hosting environments.
When should I use chain of responsibility instead of a simple if/else chain?
A simple if/else chain is fine when the logic is small, stable, and unlikely to change. Switch to chain of responsibility when the conditions are complex, when different teams or modules contribute handlers, when you need the ability to reorder or reconfigure the processing pipeline without modifying existing code, or when you want each processing step to be independently testable. The overhead of the pattern isn't justified for trivial branching, but it pays off as the number of conditions grows and the logic behind each condition becomes more involved.
Wrapping Up Chain of Responsibility Best Practices
Applying these chain of responsibility pattern best practices in C# will help you build handler pipelines that remain clean and maintainable as your application scales. The key themes are consistent: keep each handler focused on a single concern, use generics for type safety, make chain construction explicit and visible, handle the end of the chain deliberately, add observability for production debugging, and test both individual handlers and the assembled chain.
The pattern shines when you treat handlers as small, composable processing steps rather than monolithic blocks of conditional logic. Each handler should be something you can add, remove, or reorder without ripple effects across the system. When you centralize chain construction in a builder and follow consistent naming conventions, the entire team can understand and extend the pipeline without tracing through scattered wiring code. These chain of responsibility pattern best practices aren't about over-engineering -- they're about setting up your pipeline so it scales with your codebase instead of against it.
These best practices are guidelines shaped by real-world experience, not rigid rules. Start simple with a few focused handlers, add observability when you need production visibility, and reach for the builder pattern when manual construction becomes unwieldy. If you're exploring how other patterns approach similar pipeline and structural challenges, the bridge pattern offers a different perspective on separating abstractions from implementations that can complement your chain of responsibility designs.