ASP.NET Core error handling done well means your API clients never receive a mystery 500 response with no actionable information. Every error -- whether a validation failure, a domain rule violation, or an unexpected crash -- ideally comes back as a structured, consistent response that developers can actually parse and act on. This matters more than most teams realize until they're debugging a production incident and the API just returns Internal Server Error with an empty body.

This guide covers the full picture for .NET 10: the Problem Details standard, built-in middleware, the modern IExceptionHandler interface, and how to layer everything into a production-ready asp.net core error handling strategy that scales with your application.

The Problem Details Standard (RFC 9457)

The HTTP ecosystem has long suffered from inconsistent error formats. Every API did its own thing -- some returned { "error": "..." }, others { "message": "..." }, and plenty returned HTML error pages to JSON clients. RFC 9457 (which superseded RFC 7807) standardizes this once and for all. It defines the application/problem+json content type and a set of well-known fields that error responses commonly include.

The core fields are worth understanding before you write a line of code. The type field is a URI that identifies the error type -- it can be a real URL pointing to documentation, or the placeholder about:blank. The title gives a human-readable summary of the problem type, not the specific occurrence. The status mirrors the HTTP status code. The detail field provides specific information about this particular occurrence, meant to help the developer debug without exposing sensitive internals. The instance is a URI that identifies the specific occurrence -- usually the request path.

In .NET 10, enabling Problem Details support is a single method call. The framework provides AddProblemDetails(), and the middleware hooks in automatically when you call UseExceptionHandler() without arguments. Here is the minimal setup:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddProblemDetails(); // Enables RFC 9457 compliant responses

var app = builder.Build();

// UseExceptionHandler() with no path uses ProblemDetails when AddProblemDetails is registered
app.UseExceptionHandler();

// Converts bare status codes (404 from routing, 405 Method Not Allowed, etc.) to ProblemDetails
app.UseStatusCodePages();

app.MapControllers();
app.Run();

When an unhandled exception occurs, this combination produces a Problem Details response by default -- the exact shape can still vary based on environment settings and any customization you apply:

{
  "type": "https://tools.ietf.org/html/rfc9457",
  "title": "An error occurred while processing your request.",
  "status": 500,
  "detail": null,
  "instance": "/api/orders/42",
  "traceId": "00-a1b2c3d4e5f6-b7c8d9e0f1a2-00"
}

Note on type URIs: In production, consider using your own domain for type URIs (e.g., "https://api.yourdomain.com/errors/internal-error") rather than pointing directly at the RFC URI. This lets you host human-readable documentation at that URL and gives clients a stable, API-specific reference. The tools.ietf.org URIs shown in examples follow the RFC 9457 pattern (https://tools.ietf.org/html/rfc9457).

The traceId is automatically added by ASP.NET Core in .NET 10. It is invaluable for correlating errors across distributed systems, and you get it for free.

UseExceptionHandler: The Built-in Global Middleware

UseExceptionHandler is the workhorse of asp.net core error handling. It wraps the entire downstream pipeline in a try/catch, catches any unhandled exceptions, and gives you a controlled opportunity to produce a proper response. The simplest form passes a path -- ASP.NET Core re-executes the request at that path to generate the error response. The more powerful form, and the one preferred in .NET 10, uses a lambda that runs inline.

app.UseExceptionHandler(exceptionHandlerApp =>
{
    exceptionHandlerApp.Run(async context =>
    {
        var exceptionHandlerFeature = context.Features.Get<IExceptionHandlerFeature>();
        var exception = exceptionHandlerFeature?.Error;

        var status = exception switch
        {
            NotFoundException => StatusCodes.Status404NotFound,
            UnauthorizedAccessException => StatusCodes.Status403Forbidden,
            _ => StatusCodes.Status500InternalServerError
        };

        var problemDetails = new ProblemDetails
        {
            Status = status,
            Title = status == 500 ? "An unexpected error occurred" : exception?.Message,
            Detail = status == 500 ? null : exception?.Message,
            Instance = context.Request.Path
        };

        problemDetails.Extensions["traceId"] =
            Activity.Current?.Id ?? context.TraceIdentifier;

        context.Response.StatusCode = status;
        context.Response.ContentType = "application/problem+json";

        await context.Response.WriteAsJsonAsync(problemDetails);
    });
});

This approach works well for small applications. But as your domain grows, the exception type switching inside the lambda becomes unwieldy. A wall of if/else or a switch with dozens of cases is hard to maintain and impossible to test in isolation. That is exactly the problem IExceptionHandler solves.

IExceptionHandler: The DI-Friendly Approach (.NET 8+)

IExceptionHandler was introduced in .NET 8 and is a modern, convenient option for asp.net core error handling in .NET 10. You implement the interface in a class, register it with DI, and ASP.NET Core calls your handlers in registration order. The first handler that returns true wins -- all others are skipped. Multiple handlers chain together, each responsible for a specific exception type.

This is structurally identical to the Chain of Responsibility pattern -- each handler in the chain decides whether to handle the request or pass it along. The pattern keeps each handler focused, independently testable, and easy to add or remove.

Here is a complete example with a domain-specific handler and a generic fallback:

// Handles domain-specific exceptions
public sealed class DomainExceptionHandler : IExceptionHandler
{
    private readonly ILogger<DomainExceptionHandler> _logger;

    public DomainExceptionHandler(ILogger<DomainExceptionHandler> logger)
    {
        _logger = logger;
    }

    public async ValueTask<bool> TryHandleAsync(
        HttpContext httpContext,
        Exception exception,
        CancellationToken cancellationToken)
    {
        if (exception is not DomainException domainException)
        {
            return false; // Not our concern -- let the next handler try
        }

        _logger.LogWarning(
            domainException,
            "Domain rule violated: {ErrorCode} -- {Message}",
            domainException.ErrorCode,
            domainException.Message);

        var problemDetails = new ProblemDetails
        {
            Status = StatusCodes.Status422UnprocessableEntity,
            Title = "Business rule violation",
            Detail = domainException.Message,
            Type = "https://api.example.com/errors/domain"
        };

        problemDetails.Extensions["errorCode"] = domainException.ErrorCode;
        problemDetails.Extensions["traceId"] =
            Activity.Current?.Id ?? httpContext.TraceIdentifier;

        httpContext.Response.StatusCode = StatusCodes.Status422UnprocessableEntity;
        await httpContext.Response.WriteAsJsonAsync(problemDetails, cancellationToken);

        return true; // Handled
    }
}

// Catches everything else
public sealed class GlobalExceptionHandler : IExceptionHandler
{
    private readonly ILogger<GlobalExceptionHandler> _logger;

    public GlobalExceptionHandler(ILogger<GlobalExceptionHandler> logger)
    {
        _logger = logger;
    }

    public async ValueTask<bool> TryHandleAsync(
        HttpContext httpContext,
        Exception exception,
        CancellationToken cancellationToken)
    {
        _logger.LogError(
            exception,
            "Unhandled exception: {ExceptionType} on {Method} {Path}",
            exception.GetType().Name,
            httpContext.Request.Method,
            httpContext.Request.Path);

        var problemDetails = new ProblemDetails
        {
            Status = StatusCodes.Status500InternalServerError,
            Title = "An unexpected error occurred",
            Type = "https://tools.ietf.org/html/rfc9457"
        };

        problemDetails.Extensions["traceId"] =
            Activity.Current?.Id ?? httpContext.TraceIdentifier;

        httpContext.Response.StatusCode = StatusCodes.Status500InternalServerError;
        await httpContext.Response.WriteAsJsonAsync(problemDetails, cancellationToken);

        return true;
    }
}

Registering both in Program.cs:

// Register in the order they should be tried
builder.Services.AddExceptionHandler<DomainExceptionHandler>();
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
builder.Services.AddProblemDetails();

// In the pipeline -- no path argument needed
app.UseExceptionHandler();

The registration order is meaningful. DomainExceptionHandler is evaluated first because it was registered first. Only if it returns false does GlobalExceptionHandler get a chance. This is clean, predictable, and mirrors how the Mediator pattern dispatches requests to specific handlers -- each handler knows exactly what it is responsible for.

Customizing Problem Details Globally

Sometimes you want to add custom fields to every problem details response -- not just exception responses, but also 404s, 401s, and validation errors from [ApiController]. The CustomizeProblemDetails callback runs for all of them.

builder.Services.AddProblemDetails(options =>
{
    options.CustomizeProblemDetails = context =>
    {
        // Add traceId to every problem response
        context.ProblemDetails.Extensions["traceId"] =
            Activity.Current?.Id ?? context.HttpContext.TraceIdentifier;

        // Add server node info (helpful in multi-node deployments)
        context.ProblemDetails.Extensions["nodeId"] = Environment.MachineName;

        // ISO 8601 timestamp for client-side correlation
        context.ProblemDetails.Extensions["timestamp"] =
            DateTimeOffset.UtcNow.ToString("o");
    };
});

This approach gives you a uniform response shape across your entire API. Every error -- whether produced by routing, authentication, validation, or your own exception handlers -- will include these fields. Client applications can write a single error-handling routine that works everywhere.

In .NET 10, ProblemDetailsContext gained a SuppressDiagnosticsCallback property, giving you finer control over when diagnostics events are suppressed for handled exceptions. This is useful when you want to suppress diagnostic telemetry for expected exceptions (such as validation errors or not-found responses) while still recording them for unexpected errors.

This technique is conceptually similar to what the Decorator pattern describes in object-oriented terms: you are wrapping the base behavior (producing a problem details response) with additional cross-cutting concerns (adding trace IDs, timestamps) without modifying the core logic.

Validation Error Responses with [ApiController]

The [ApiController] attribute automates a critical part of asp.net core error handling for you. When model validation fails, it short-circuits execution before your action method runs and returns a 400 Bad Request with a ValidationProblemDetails body. You never need to write if (!ModelState.IsValid) checks in API controller actions.

The automatic validation response looks like this:

{
  "type": "https://tools.ietf.org/html/rfc9457",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "Email": ["The Email field is not a valid e-mail address."],
    "Name": ["The Name field is required."]
  },
  "traceId": "00-a1b2c3..."
}

To customize this response -- for example to return 422 instead of 400 for semantic validation failures, or to add your custom extension fields -- replace InvalidModelStateResponseFactory:

builder.Services.Configure<ApiBehaviorOptions>(options =>
{
    options.InvalidModelStateResponseFactory = context =>
    {
        var problemDetails = new ValidationProblemDetails(context.ModelState)
        {
            Type = "https://api.example.com/errors/validation",
            Title = "Validation failed",
            Status = StatusCodes.Status422UnprocessableEntity
        };

        problemDetails.Extensions["traceId"] =
            context.HttpContext.TraceIdentifier;

        return new UnprocessableEntityObjectResult(problemDetails)
        {
            ContentTypes = { "application/problem+json" }
        };
    };
});

The choice between 400 and 422 depends on how you classify the error and what semantics you want clients to rely on. Both are valid; the key is choosing deliberately and applying consistently. Use 400 for requests with bad syntax or structure, 422 for semantically invalid requests. Either way, document your convention in your API spec so consumers know what to expect.

Exception Filters vs IExceptionHandler

These two mechanisms both catch exceptions, but they operate at different levels. Understanding the distinction helps you choose the right tool for each scenario.

Exception filters (IExceptionFilter, IAsyncExceptionFilter) are MVC-scoped. They only catch exceptions thrown inside MVC action methods -- not in middleware, not in minimal API handlers, not in background services. You can apply them globally, per-controller, or per-action via attributes, which gives you fine-grained control. They are a reasonable fit when specific exceptions should map to specific responses only within certain controllers.

IExceptionHandler is pipeline-wide. It catches anything that bubbles up through the entire middleware stack -- controllers, minimal APIs, and even exceptions in other middleware. In .NET 10, IExceptionHandler is the commonly preferred approach unless you have a very specific reason to scope error handling to individual actions. For pure Web APIs, there is rarely such a reason.

If you are familiar with the Proxy pattern, you can think of IExceptionHandler as a pipeline-level proxy that intercepts every request and translates exception language into HTTP language -- a clean separation of concerns.

Logging Errors Properly

ASP.NET Core error handling and structured logging are inseparable. Every unhandled exception ideally produces a structured log entry with enough context to diagnose the problem later. The How to Set Up Serilog in ASP.NET Core guide covers Serilog setup in depth, and the Serilog in .NET complete guide covers structured logging patterns -- but a few error-handling-specific practices are worth emphasizing here.

Log the full exception object, not just exception.Message. The message omits the stack trace, inner exceptions, and contextual data that makes the difference between a 5-minute fix and a 2-hour investigation. Use the overload that accepts an Exception as the first parameter:

_logger.LogError(
    exception,
    "Order processing failed for OrderId {OrderId} -- {ExceptionType}",
    orderId,
    exception.GetType().Name);

Avoid logging and re-throwing the same exception at multiple layers. Log once, at the outermost catch point -- your global exception handler. Multiple log entries for a single exception create noise and make correlation harder. Let the structured log entry carry the full context, including the trace ID.

Development vs Production Errors

One of the most practical aspects of asp.net core error handling is environment-based configuration. In development, you want full exception details -- stack traces, inner exceptions, query strings. In production, you want the opposite: structured Problem Details with no sensitive internals exposed.

if (app.Environment.IsDevelopment())
{
    // Full stack traces and exception details -- never enable in production
    app.UseDeveloperExceptionPage();
}
else
{
    app.UseExceptionHandler(); // Clean ProblemDetails via your IExceptionHandler chain
    app.UseHsts();
}

UseDeveloperExceptionPage returns a rich HTML page (or detailed JSON for API requests that send Accept: application/json) with the full exception details. It is invaluable during development. But in production, stack traces and internal file paths can reveal exploitable information about your system. Ensure ASPNETCORE_ENVIRONMENT is set to Production in your deployment environment, and never conditionally enable developer pages based on anything other than IsDevelopment().

Frequently Asked Questions

What is the difference between UseExceptionHandler and IExceptionHandler in ASP.NET Core?

UseExceptionHandler is the middleware component you register in the request pipeline. It wraps the downstream pipeline in a try/catch and catches unhandled exceptions. When registered with no arguments and AddProblemDetails has been called, it produces a Problem Details response by default -- the exact shape can still vary based on environment settings and any customization you apply.

IExceptionHandler is an interface you implement in your own classes. These implementations are called by UseExceptionHandler when an exception occurs. Multiple handlers can be registered, and they are tried in order -- the first one to return true handles the exception and subsequent handlers are skipped. Think of UseExceptionHandler as the outer shell and IExceptionHandler implementations as the pluggable logic running inside it.

In .NET 10, the commonly preferred approach is to use both together: UseExceptionHandler() in the pipeline and one or more IExceptionHandler implementations registered with AddExceptionHandler<T>().

Should validation errors return HTTP 400 or HTTP 422?

Both status codes are defensible, and you will find respected APIs using each. RFC 9110 defines 400 Bad Request as appropriate when the server cannot process the request due to a client error -- which includes invalid syntax, missing required fields, and values outside allowed ranges. RFC 9110 defines 422 Unprocessable Content as appropriate when the request is syntactically correct but cannot be processed due to semantic errors.

The practical difference: use 400 for structural problems (missing required field, wrong data type) and 422 for business rule violations (a date range where the end is before the start, an order quantity that exceeds inventory). ASP.NET Core returns 400 by default for model validation failures. You can override this with InvalidModelStateResponseFactory if your team prefers 422. The most important thing is consistency -- pick a convention and document it in your API spec.

How do I add custom fields like errorCode to every Problem Details response?

Use the CustomizeProblemDetails callback in AddProblemDetails(). This callback receives every problem details response before it is written -- including automatic validation errors, routing 404s, and responses from your IExceptionHandler implementations. You can add any key-value pair to ProblemDetails.Extensions and it will be serialized as an additional field in the JSON response.

For exception-specific data like an errorCode that only makes sense when a domain exception is thrown, add the extension in your IExceptionHandler implementation instead. That way the field only appears when the relevant exception type is caught, rather than appearing (with a null or default value) on every response.

How do I handle NotFoundException to return 404 instead of 500?

Create a custom exception class (e.g., NotFoundException : Exception) and implement an IExceptionHandler that checks for it. When the handler receives a NotFoundException, it sets the HTTP status code to 404, writes a problem details body, and returns true.

A cleaner pattern is to add a StatusCode property to a base exception class and have a single IExceptionHandler read it. Your NotFoundException sets StatusCode = 404, your ConflictException sets StatusCode = 409, and so on. The handler maps exception status codes to HTTP status codes without knowing anything about specific exception types. This makes adding new exception types purely additive -- no handler changes needed.

Can I test IExceptionHandler implementations in isolation?

Yes, and this is one of the main reasons to prefer IExceptionHandler over inline lambda handlers. Construct your handler, create a DefaultHttpContext with a mock response stream, call TryHandleAsync with a test exception, and assert the response status code and body.

For integration tests, use WebApplicationFactory<Program> to start a real test server and configure endpoints that deliberately throw specific exceptions. Then call those endpoints with an HttpClient and assert the full response -- status code, content type, and parsed JSON body. Integration tests are especially valuable for verifying that your AddProblemDetails customizations apply consistently across all error paths.

What happens if an IExceptionHandler implementation throws an exception itself?

If your IExceptionHandler throws while trying to handle an exception, ASP.NET Core falls back to its built-in behavior. If AddProblemDetails is registered, the framework will attempt to produce a generic 500 problem details response. If it cannot do that either, it produces a bare 500 with no body.

Your exception handlers need to be defensive. Avoid calling services that could fail -- no database calls, no external HTTP calls, nothing that might throw. If you absolutely need external data in your error handler, wrap it in a try/catch. The error handling layer is not the place for complex orchestration.

How does asp.net core error handling interact with middleware short-circuiting?

UseExceptionHandler only catches exceptions that propagate through the pipeline. Middleware that short-circuits by writing a response and not calling next() does not trigger UseExceptionHandler -- it bypasses it entirely. This is intentional. Health check endpoints, rate limiters, and cached response middleware all need to short-circuit without triggering exception handling.

The implication is that middleware registered before UseExceptionHandler in the pipeline is outside the error handling safety net. Keep middleware that might produce errors after UseExceptionHandler in the registration order, which is why the recommended pipeline ordering usually puts UseExceptionHandler first.

You've got foreach loops everywhere in your C# code. Lists, arrays, dictionaries -- they all support enumeration out of the box. So why would you ever need to build a custom iterator? The answer is that built-in collections cover the common case, but when to use the iterator pattern in C# becomes a real question once your data doesn't fit neatly into a List<T>. Maybe you're reading millions of lines from a file. Maybe you're walking a tree structure. Maybe you're pulling paginated results from an API and want to hide that complexity behind a simple loop.

This article gives you a structured decision framework for recognizing when the iterator pattern earns its place in your code versus when you should lean on what .NET gives you for free. We'll walk through decision criteria, three practical scenarios with C# code, and the situations where a custom iterator adds unnecessary complexity. If you're building up your design pattern toolkit, consider checking out the strategy design pattern for another pattern that helps you swap out behavior cleanly.

Decision Criteria: When Custom Iterators Add Value

Not every data source maps to a List<T> or an array. And not every traversal is a simple front-to-back scan. The question of when to use the iterator pattern in C# boils down to a few clear signals.

Custom Data Structures That Don't Map to Standard Collections

If you've built a tree, a graph, a skip list, or any data structure that isn't a flat sequence, the built-in collection types won't expose it the way consumers expect. A custom iterator lets you present your data structure as an IEnumerable<T> so callers can use foreach without understanding the internal layout. This is especially valuable when your data structure is part of a composite design pattern where the hierarchy can be arbitrarily deep.

Lazy Evaluation of Expensive Computations

When each element in a sequence is expensive to compute -- think parsing, transforming, or generating -- materializing the entire collection upfront wastes time and memory if the consumer only needs a few elements. The iterator pattern in C# with yield return lets you compute elements one at a time, on demand. The consumer pulls what it needs, and the rest never gets computed.

Streaming Data from External Sources

Files, network streams, database cursors, and API endpoints aren't collections sitting in memory. They're sources you read from incrementally. A custom iterator wraps the read-ahead logic so callers see a clean foreach loop. This is the same principle behind how IAsyncEnumerable<T> works for async data sources in .NET.

Beyond these three signals, there's one more worth considering.

Multiple Traversal Strategies Over the Same Data

A binary tree can be traversed in-order, pre-order, or post-order. A graph can be traversed depth-first or breadth-first. If consumers of your data structure need different traversal orders, the iterator pattern lets you expose multiple IEnumerable<T> methods -- one per traversal strategy -- without forcing the consumer to understand the traversal algorithm. This pairs naturally with the strategy design pattern, where the traversal algorithm itself is interchangeable.

Scenario: Lazy File Processing

One of the clearest demonstrations of when to use the iterator pattern in C# is processing large files. If you call File.ReadAllLines(), you load the entire file into memory as a string array. For a file with millions of lines, that's a significant allocation. An iterator reads one line at a time.

using System.Collections.Generic;
using System.IO;

public static class LazyFileReader
{
    // Reads lines one at a time using yield return
    public static IEnumerable<string> ReadLines(
        string filePath)
    {
        using var reader = new StreamReader(filePath);

        while (!reader.EndOfStream)
        {
            yield return reader.ReadLine()!;
        }
    }
}

The yield return keyword is the key. Each time the consumer's foreach asks for the next element, execution resumes inside ReadLines, reads one line, and suspends again. The StreamReader stays open across iterations, and the using statement ensures it gets disposed when enumeration finishes or the consumer breaks out early.

Here's how you'd use it:

// Only one line is in memory at any given time
foreach (var line in LazyFileReader.ReadLines("server-log.txt"))
{
    if (line.Contains("ERROR"))
    {
        Console.WriteLine(line);
    }
}

Compare this to the eager approach:

// Loads the ENTIRE file into memory at once
var allLines = File.ReadAllLines("server-log.txt");

foreach (var line in allLines)
{
    if (line.Contains("ERROR"))
    {
        Console.WriteLine(line);
    }
}

With a 2 GB log file containing millions of lines, ReadAllLines allocates a massive string array plus the string data itself. The lazy iterator holds exactly one string in flight at a time. If you're only looking for error lines and breaking early, the iterator may read just a fraction of the file.

Note that .NET does include File.ReadLines() (not ReadAllLines), which uses this exact pattern internally. That's how fundamental the iterator pattern is to the .NET ecosystem -- the framework itself uses it to solve this problem.

Scenario: Tree Traversal

Trees are a natural fit for the iterator pattern in C# because they're not flat sequences. A consumer shouldn't need to understand recursion or maintain a stack just to visit every node. Multiple traversal strategies make this even more compelling.

using System.Collections.Generic;

public sealed class BinaryTreeNode<T>
{
    public T Value { get; }
    public BinaryTreeNode<T>? Left { get; }
    public BinaryTreeNode<T>? Right { get; }

    public BinaryTreeNode(
        T value,
        BinaryTreeNode<T>? left = null,
        BinaryTreeNode<T>? right = null)
    {
        Value = value;
        Left = left;
        Right = right;
    }

    // In-order: Left, Root, Right
    public IEnumerable<T> InOrder()
    {
        if (Left is not null)
        {
            foreach (var item in Left.InOrder())
            {
                yield return item;
            }
        }

        yield return Value;

        if (Right is not null)
        {
            foreach (var item in Right.InOrder())
            {
                yield return item;
            }
        }
    }

    // Pre-order: Root, Left, Right
    public IEnumerable<T> PreOrder()
    {
        yield return Value;

        if (Left is not null)
        {
            foreach (var item in Left.PreOrder())
            {
                yield return item;
            }
        }

        if (Right is not null)
        {
            foreach (var item in Right.PreOrder())
            {
                yield return item;
            }
        }
    }

    // Post-order: Left, Right, Root
    public IEnumerable<T> PostOrder()
    {
        if (Left is not null)
        {
            foreach (var item in Left.PostOrder())
            {
                yield return item;
            }
        }

        if (Right is not null)
        {
            foreach (var item in Right.PostOrder())
            {
                yield return item;
            }
        }

        yield return Value;
    }
}

Each traversal method returns IEnumerable<T> and uses yield return to lazily produce values. The caller picks the traversal strategy they need:

//       4
//      / 
//     2   6
//    /  / 
//   1  3 5  7
var tree = new BinaryTreeNode<int>(4,
    new BinaryTreeNode<int>(2,
        new BinaryTreeNode<int>(1),
        new BinaryTreeNode<int>(3)),
    new BinaryTreeNode<int>(6,
        new BinaryTreeNode<int>(5),
        new BinaryTreeNode<int>(7)));

// In-order: 1, 2, 3, 4, 5, 6, 7
foreach (var value in tree.InOrder())
{
    Console.Write($"{value} ");
}

Console.WriteLine();

// Pre-order: 4, 2, 1, 3, 6, 5, 7
foreach (var value in tree.PreOrder())
{
    Console.Write($"{value} ");
}

This is where the composite design pattern and the iterator pattern complement each other. Composite gives you a uniform interface for treating individual objects and compositions the same way. The iterator pattern gives you a uniform way to traverse that composition. When your composite structure represents a file system, an organization chart, or a UI component tree, exposing IEnumerable<T> traversals lets consumers work with the hierarchy without understanding its shape.

Scenario: Paginated API Results

APIs that return paginated results are a strong case for when to use the iterator pattern in C#. The consumer wants to iterate over all results. The iterator handles fetching page by page behind the scenes. Client code sees a simple foreach and never thinks about page tokens, offsets, or batch sizes.

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Text.Json;

public sealed class PaginatedApiIterator<T>
{
    private readonly HttpClient _httpClient;
    private readonly string _baseUrl;
    private readonly int _pageSize;

    public PaginatedApiIterator(
        HttpClient httpClient,
        string baseUrl,
        int pageSize = 50)
    {
        _httpClient = httpClient;
        _baseUrl = baseUrl;
        _pageSize = pageSize;
    }

    public IEnumerable<T> GetAll()
    {
        int page = 1;
        bool hasMore = true;

        while (hasMore)
        {
            var url = $"{_baseUrl}?page={page}" +
                      $"&pageSize={_pageSize}";

            var response = _httpClient
                .GetStringAsync(url)
                .GetAwaiter()
                .GetResult();

            var pageResult = JsonSerializer
                .Deserialize<PageResult<T>>(response);

            if (pageResult?.Items is null ||
                pageResult.Items.Count == 0)
            {
                yield break;
            }

            foreach (var item in pageResult.Items)
            {
                yield return item;
            }

            hasMore = pageResult.Items.Count == _pageSize;
            page++;
        }
    }
}

public sealed class PageResult<T>
{
    public List<T>? Items { get; set; }

    public int TotalCount { get; set; }
}

The consumer code is clean and completely unaware of pagination:

var httpClient = new HttpClient();
var iterator = new PaginatedApiIterator<UserDto>(
    httpClient,
    "https://api.example.com/users",
    pageSize: 25);

foreach (var user in iterator.GetAll())
{
    Console.WriteLine($"{user.Name} ({user.Email})");
}

There's an important note here. This synchronous example uses GetAwaiter().GetResult() for simplicity. In production, you'd use an async version with IAsyncEnumerable<T> and await foreach instead. The pattern is the same -- the iterator abstracts away the page-fetching mechanics -- but the async variant avoids blocking threads.

For a production-quality async version:

public async IAsyncEnumerable<T> GetAllAsync()
{
    int page = 1;
    bool hasMore = true;

    while (hasMore)
    {
        var url = $"{_baseUrl}?page={page}" +
                  $"&pageSize={_pageSize}";

        var response = await _httpClient
            .GetStringAsync(url);

        var pageResult = JsonSerializer
            .Deserialize<PageResult<T>>(response);

        if (pageResult?.Items is null ||
            pageResult.Items.Count == 0)
        {
            yield break;
        }

        foreach (var item in pageResult.Items)
        {
            yield return item;
        }

        hasMore = pageResult.Items.Count == _pageSize;
        page++;
    }
}

This pattern works for any paginated source -- REST APIs, database cursors, or even file-based batch processing. The key benefit is encapsulation: the consumer iterates without knowing about the pagination protocol. If the API changes its pagination scheme from page numbers to cursor tokens, you update one method and every consumer continues working unchanged. This kind of encapsulation is a core benefit you'll see across many design patterns, including the chain of responsibility pattern where each handler hides processing details from the caller.

When NOT to Use the Iterator Pattern

Knowing when to use the iterator pattern in C# means also knowing when it's the wrong tool. The pattern adds value when you need lazy evaluation, custom traversal, or data source abstraction. In other cases, it introduces complexity without a payoff.

Simple Lists and Arrays

If your data is already in a List<T>, an array, or any other built-in collection, there's no reason to use the iterator pattern in C# for a custom implementation. The foreach keyword works out of the box. These types implement IEnumerable<T> and provide efficient enumerators. Writing a custom iterator around an existing collection doesn't add value -- it adds a layer of indirection that makes debugging harder and code longer.

Random Access Requirements

Iterators are sequential by design. You move forward through a sequence, one element at a time. If your consumer needs to jump to element 47, access the last element, or index by position, an iterator is the wrong abstraction. Use an indexer, a List<T>, or an array where collection[index] gives you O(1) access.

All Elements Must Be Available at Once

Some algorithms need the full dataset in memory before they can proceed -- sorting, grouping, aggregating, or finding the median all require the complete collection. If your consumers consistently call .ToList() or .ToArray() on your IEnumerable<T> before doing any work, using the iterator pattern in C# adds overhead without benefit. You're paying the cost of the iterator state machine and then materializing everything anyway. Return a List<T> or IReadOnlyList<T> instead and make the intent clear.

There's one more situation worth flagging.

Deferred Execution Causing Subtle Bugs

Deferred execution means your iterator's body doesn't run until someone enumerates it. This is usually a feature, but it can cause problems when the data source changes between when you create the iterator and when you consume it. If you yield from a database connection and the connection gets disposed before enumeration starts, you'll get an exception at enumeration time -- not at creation time. This makes bugs harder to trace. When the lifetime of your data source doesn't align with enumeration timing, the iterator pattern in C# can work against you. Consider materializing the results eagerly or using a pattern like the flyweight pattern to share computed results efficiently.

Iterator Pattern in the .NET Ecosystem

The iterator pattern isn't just a textbook concept in C# -- it's woven into the framework at every level. Understanding the iterator pattern in C# makes you better at using the tools .NET provides.

LINQ is built on iterators. Every LINQ method like Where, Select, and Take returns an IEnumerable<T> that uses deferred execution. When you chain .Where(x => x > 5).Select(x => x * 2).Take(10), no work happens until you enumerate. Each operator is an iterator that pulls from the previous one. Understanding the iterator pattern explains why LINQ is lazy, why calling .ToList() triggers execution, and why you can compose queries without performance penalties until enumeration begins.

IAsyncEnumerable<T> extends the pattern to async. When you need to iterate over data that arrives asynchronously -- reading from a gRPC stream, consuming messages from a channel, or querying a database with streaming results -- IAsyncEnumerable<T> is the async version of the iterator pattern. The await foreach syntax works identically to foreach, and yield return inside an async method produces the async iterator state machine. If you've worked with dependency injection through IServiceCollection, you've seen how .NET wires up services behind a clean API. IAsyncEnumerable<T> does the same for async data streams -- it hides the complexity of async iteration behind a simple loop.

Channels use the pattern for producer-consumer scenarios. System.Threading.Channels provides bounded and unbounded channels where producers write and consumers read. The ChannelReader<T>.ReadAllAsync() method returns an IAsyncEnumerable<T>, letting you consume channel items with await foreach. Without understanding the iterator pattern, the relationship between channels and async enumeration isn't obvious.

System.IO.Pipelines leverages sequential reading. While pipelines use a different API than IEnumerable<T>, the conceptual model is the same: you read data incrementally from a source without loading everything into memory. The iterator pattern gives you the mental model to understand why pipelines work the way they do and when to choose them over simpler IEnumerable<T> based approaches.

The takeaway is straightforward. Understanding when to use the iterator pattern in C# isn't just about learning an academic design pattern -- you're learning the foundation that powers LINQ, async streams, channels, and half the APIs in the .NET Base Class Library.

Frequently Asked Questions

What is the difference between IEnumerable and IEnumerator in C#?

IEnumerable<T> represents a sequence that can be iterated. It has one method: GetEnumerator(), which returns an IEnumerator<T>. The enumerator is the actual cursor that tracks where you are in the sequence. It has Current (the element you're pointing at) and MoveNext() (advance to the next element). Think of IEnumerable<T> as the collection and IEnumerator<T> as the bookmark. When you use yield return in C#, the compiler generates both for you automatically, which is why you rarely implement IEnumerator<T> by hand.

Should I use yield return or implement IEnumerator manually?

Use yield return in the vast majority of cases. The C# compiler generates the state machine code that IEnumerator<T> requires, handling MoveNext, Current, Reset, and Dispose for you. Manual implementation is only justified when you need fine-grained control over the state machine -- for example, when building a high-performance enumerator that avoids heap allocations by using a struct enumerator. For everyday scenarios like file processing, tree traversal, and API pagination, yield return produces correct, readable, and maintainable code.

How does yield return work under the hood in C#?

When the C# compiler encounters yield return, it transforms your method into a state machine class that implements IEnumerable<T> and IEnumerator<T>. Each yield return becomes a state transition. Local variables become fields on the generated class so their values persist across calls to MoveNext(). When the consumer calls MoveNext(), execution resumes from where the last yield return suspended. This is why iterator methods don't execute when you call them -- they return the state machine object. Execution only begins when the consumer starts enumerating.

Can I use the iterator pattern with async code in C#?

Yes. C# supports async iterator methods that return IAsyncEnumerable<T>. You can use yield return inside an async method, and consumers iterate with await foreach. This is essential for streaming data from async sources -- databases, HTTP APIs, message queues, and gRPC streams all benefit from async iteration. The compiler generates an async state machine that handles both the await suspension points and the yield return suspension points, giving you the same lazy evaluation semantics you get with synchronous iterators.

When should I call ToList() instead of keeping an IEnumerable?

Call ToList() when you need to iterate the sequence more than once, when you need Count or index access without re-enumerating, or when the underlying data source might change or be disposed before you finish enumerating. Keep the IEnumerable<T> when you want lazy evaluation, when you might not need all elements, or when memory is a concern and you're working with large datasets. A common mistake is calling ToList() on a LINQ query deep inside a method and then returning IEnumerable<T> from the method -- you've already paid the materialization cost, so return IReadOnlyList<T> to communicate the intent clearly.

How does the iterator pattern relate to the observer pattern?

The iterator pattern and the observer pattern are duals of each other. The iterator pattern is "pull-based" -- the consumer requests the next element when it's ready. The observer pattern is "push-based" -- the producer sends elements to subscribers when they're available. In .NET, IEnumerable<T> represents the pull model and IObservable<T> represents the push model. Understanding both helps you choose the right approach for your data flow. If the consumer controls the pace, use iterators. If the producer controls the pace, use observers.

Is the iterator pattern thread-safe in C#?

Not by default. The enumerator state machine generated by yield return is not thread-safe. If multiple threads enumerate the same IEnumerable<T> instance concurrently, each gets its own enumerator (from GetEnumerator()), so that's fine. But if multiple threads share a single IEnumerator<T> and call MoveNext() concurrently, the behavior is undefined. For concurrent scenarios, use IAsyncEnumerable<T> with proper async coordination, or materialize to a thread-safe collection first. Channels in .NET provide a thread-safe producer-consumer model that integrates with IAsyncEnumerable<T> for safe concurrent iteration.

This article covers the full versioning toolkit for .NET 10 ASP.NET Core projects using the Asp.Versioning.Mvc package. You'll see URL segment versioning, query string versioning, header versioning, how to combine multiple strategies, and how to configure OpenAPI documentation for multiple versions.

Why Version Your API?

Most developers know they should version their APIs but skip it at the start because it feels like premature optimization. That reasoning holds until the first time you need to change a response shape or remove a field that a mobile app is reading. At that point, you either break the client or you have to maintain both behaviors in the same endpoint -- which quickly becomes a mess of if (legacyBehavior) branches. Implementing asp.net core api versioning early avoids this pain entirely.

Versioning gives you a clean separation. Breaking changes land in v2. Clients on v1 keep working. You can communicate a deprecation timeline, monitor traffic to know when v1 clients have migrated, and finally decommission v1 when the numbers justify it. This is how public APIs at scale -- GitHub, Stripe, AWS -- manage change without breaking their ecosystems. asp.net core api versioning gives you the same professional-grade change management that top API providers use.

The parallel client support argument is especially important for mobile apps, where you can't force users to update immediately. A v1 response might be in production on app store versions that users haven't updated for months. Your backend needs to support both while you ship improvements in v2.

The Asp.Versioning.Mvc NuGet Package

ASP.NET Core doesn't include API versioning in the framework itself. The Asp.Versioning.Mvc NuGet package (third-party, not part of the framework) -- formerly Microsoft.AspNetCore.Mvc.Versioning before it was moved to a separate project -- is a widely used, mature package for controller-based API versioning. It's maintained by the original author with active development and excellent .NET 10 support.

Install it with:

dotnet add package Asp.Versioning.Mvc
dotnet add package Asp.Versioning.Mvc.ApiExplorer

The second package is needed for OpenAPI/Swagger integration. With those in place, you configure versioning in Program.cs:

// Program.cs -- API versioning setup with Asp.Versioning.Mvc in .NET 10
using Asp.Versioning;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
    options.ApiVersionReader = new UrlSegmentApiVersionReader();
})
.AddApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
});

var app = builder.Build();

app.UseRouting();
app.UseAuthorization();
app.MapControllers();

app.Run();

ReportApiVersions = true adds api-supported-versions and api-deprecated-versions response headers to every request. This is a useful signal to API clients -- they can read the headers and notify their users when they're running on a deprecated version. AssumeDefaultVersionWhenUnspecified = true means requests that don't include a version identifier are treated as requesting the default version, which keeps unversioned clients working during a transition.

URL Segment Versioning

URL segment versioning is the most visible and widely understood asp.net core api versioning strategy. The version appears directly in the URL path: /api/v1/products versus /api/v2/products. It's easy to test in a browser, obvious in API documentation, and straightforward to reason about. The downside is that the URL changes with each version, which violates REST purist principles about stable resource identifiers -- but for pragmatic API design, this is rarely a real problem.

To use URL segment versioning, set the version reader to UrlSegmentApiVersionReader (as shown in the setup above) and configure your controllers with the version in the route template:

// URL segment versioning -- v1 and v2 controllers side by side

// V1 Products Controller
[ApiController]
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/products")]
public sealed class ProductsV1Controller : ControllerBase
{
    private readonly IProductService _productService;

    public ProductsV1Controller(IProductService productService)
    {
        _productService = productService;
    }

    [HttpGet]
    public async Task<IActionResult> GetAll()
    {
        var products = await _productService.GetAllAsync();
        // V1 returns a flat list
        return Ok(products.Select(p => new
        {
            p.Id,
            p.Name,
            p.Price
        }));
    }

    [HttpGet("{id:int}")]
    public async Task<IActionResult> GetById(int id)
    {
        var product = await _productService.GetByIdAsync(id);
        return product is null ? NotFound() : Ok(new
        {
            product.Id,
            product.Name,
            product.Price
        });
    }
}

// V2 Products Controller -- enriched response shape
[ApiController]
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/products")]
public sealed class ProductsV2Controller : ControllerBase
{
    private readonly IProductService _productService;
    private readonly ICategoryService _categoryService;

    public ProductsV2Controller(
        IProductService productService,
        ICategoryService categoryService)
    {
        _productService = productService;
        _categoryService = categoryService;
    }

    [HttpGet]
    public async Task<IActionResult> GetAll()
    {
        var products = await _productService.GetAllAsync();
        // V2 includes category details and inventory
        return Ok(products.Select(p => new
        {
            p.Id,
            p.Name,
            p.Price,
            p.CategoryId,
            CategoryName = p.Category?.Name,
            p.StockQuantity,
            p.IsAvailable
        }));
    }

    [HttpGet("{id:int}")]
    public async Task<IActionResult> GetById(int id)
    {
        var product = await _productService.GetByIdAsync(id);
        return product is null ? NotFound() : Ok(product);
    }
}

Notice that v1 and v2 are entirely separate controllers. This is the cleanest approach -- each version has its own controller with its own logic, and you can evolve them independently. Some teams prefer to put both versions in a single controller using [MapToApiVersion], which is covered below.

This kind of version-by-behavior design maps well to broader architectural patterns. When you're thinking about how features and versions interact with your system boundaries, modular monolith architecture offers a useful lens for organizing the internal structure.

Query String Versioning

Query string versioning appends the version as a URL parameter: /api/products?api-version=1.0. It's less visually prominent than URL segment versioning, which some teams prefer. It keeps the base resource path stable across versions and is easy to add to existing requests without restructuring URLs.

// Query string versioning configuration
builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
    options.ApiVersionReader = new QueryStringApiVersionReader("api-version");
});

// Controller attributes remain the same -- only the route template changes
[ApiController]
[ApiVersion("1.0")]
[Route("api/products")] // No version in route -- version comes from query string
public sealed class ProductsController : ControllerBase
{
    // ...
}

The default parameter name is api-version, which is conventional. You can rename it by passing a different string to QueryStringApiVersionReader. One trade-off: the route template doesn't include the version, so both v1 and v2 controllers point to the same path. The routing framework disambiguates them using the [ApiVersion] attribute and the query string value.

Header Versioning

Header versioning reads the API version from a custom HTTP header, typically X-Api-Version. The URL stays completely clean -- /api/products -- and the version is a protocol-level concern expressed in the headers. This is the most "RESTful" approach in the strict sense, but it's the least discoverable. Browsers can't version requests through headers without developer tools, and tools like Postman require an explicit header configuration step.

// Header versioning configuration
builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
    options.ApiVersionReader = new HeaderApiVersionReader("X-Api-Version");
});

Header versioning pairs well with API gateway setups where the gateway can inject or rewrite version headers based on routing rules. Internal microservices behind an API gateway often use header versioning because the URL namespace is already managed by the gateway, and headers are a natural extension point for routing metadata.

Combining Multiple Version Readers

Limiting your API to a single versioning strategy means clients are forced to use that exact mechanism. A more flexible approach is to support multiple strategies simultaneously. The ApiVersionReader.Combine() method accepts multiple readers and uses whichever one the incoming request provides. If multiple readers find a version identifier, the first match wins.

// Supporting URL, query string, and header versioning simultaneously
builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
    options.ApiVersionReader = ApiVersionReader.Combine(
        new UrlSegmentApiVersionReader(),
        new QueryStringApiVersionReader("api-version"),
        new HeaderApiVersionReader("X-Api-Version")
    );
});

This is useful during migrations. If you're moving from query string versioning to URL segment versioning, running both readers simultaneously gives clients time to update their requests without a hard cutover.

MapToApiVersion: Multiple Versions in One Controller

Sometimes you want to handle two API versions in a single controller -- for example, when the change between v1 and v2 is minor and doesn't justify a separate class. The [MapToApiVersion] attribute lets you map individual actions to specific versions.

// Single controller handling both v1 and v2 with [MapToApiVersion]
[ApiController]
[ApiVersion("1.0")]
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/orders")]
public sealed class OrdersController : ControllerBase
{
    private readonly IOrderService _orderService;

    public OrdersController(IOrderService orderService)
    {
        _orderService = orderService;
    }

    // This action handles BOTH v1 and v2 requests (same behavior)
    [HttpGet]
    public async Task<IActionResult> GetAll() =>
        Ok(await _orderService.GetAllAsync());

    // V1 response -- simple flat structure
    [HttpGet("{id:int}")]
    [MapToApiVersion("1.0")]
    public async Task<IActionResult> GetByIdV1(int id)
    {
        var order = await _orderService.GetByIdAsync(id);
        if (order is null) return NotFound();

        return Ok(new { order.Id, order.Status, order.Total });
    }

    // V2 response -- includes line items and shipping info
    [HttpGet("{id:int}")]
    [MapToApiVersion("2.0")]
    public async Task<IActionResult> GetByIdV2(int id)
    {
        var order = await _orderService.GetByIdAsync(id);
        if (order is null) return NotFound();

        return Ok(order); // Full object with all fields
    }
}

This pattern keeps related logic co-located when the difference between versions is small. Use it judiciously -- if the version difference grows significantly, the controller becomes harder to read, and separate controllers are cleaner.

Design patterns can help manage the complexity of multiple versions sharing behavior. The facade design pattern is useful for exposing a simplified interface that internally delegates to different version-specific implementations, keeping the controller action thin.

Version Deprecation

Marking a version as deprecated tells clients it will eventually be removed without removing it immediately. The [ApiVersion] attribute accepts a Deprecated property:

[ApiVersion("1.0", Deprecated = true)]
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/customers")]
public sealed class CustomersController : ControllerBase
{
    // ...
}

When ReportApiVersions = true is set and a client requests a deprecated version, the response includes both api-supported-versions and api-deprecated-versions headers. This lets client developers see which versions are available and which are on their way out. Pair this with communication through your API changelog and documentation to give clients adequate notice before decommissioning.

Swagger/OpenAPI Multi-Version Configuration

Having multiple API versions without corresponding documentation creates confusion. Before diving into the wiring, it's worth distinguishing three separate pieces that work together here:

• Built-in ASP.NET Core OpenAPI metadata -- the Microsoft.AspNetCore.OpenApi package handles metadata generation from your controllers and endpoints. Built-in OpenAPI support first arrived in .NET 9 and is supported in .NET 10.
• Swashbuckle (third-party, not part of the framework) -- provides the Swagger UI and the SwaggerGen middleware that renders your OpenAPI metadata as an interactive documentation page.
• Asp.Versioning.Mvc.ApiExplorer -- the companion package that teaches the API explorer about your version groups so each version gets its own generated document.

Asp.Versioning.Mvc.ApiExplorer enables the API explorer to generate separate OpenAPI documents per version. The Swashbuckle integration needs a small amount of wiring:

// OpenAPI multi-version setup with Swashbuckle in .NET 10
using Asp.Versioning.ApiExplorer;
using Microsoft.Extensions.Options;
using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;

// In Program.cs after AddApiVersioning():
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
builder.Services.ConfigureOptions<ConfigureSwaggerOptions>();

var app = builder.Build();

app.UseSwagger();
app.UseSwaggerUI(options =>
{
    // Dynamically add a Swagger UI endpoint per API version
    var provider = app.Services.GetRequiredService<IApiVersionDescriptionProvider>();
    foreach (var description in provider.ApiVersionDescriptions)
    {
        options.SwaggerEndpoint(
            $"/swagger/{description.GroupName}/swagger.json",
            $"My API {description.GroupName.ToUpperInvariant()}");
    }
});

// ConfigureSwaggerOptions generates one Swagger doc per API version
public sealed class ConfigureSwaggerOptions
    : IConfigureNamedOptions<SwaggerGenOptions>
{
    private readonly IApiVersionDescriptionProvider _provider;

    public ConfigureSwaggerOptions(IApiVersionDescriptionProvider provider)
    {
        _provider = provider;
    }

    public void Configure(SwaggerGenOptions options)
    {
        foreach (var description in _provider.ApiVersionDescriptions)
        {
            options.SwaggerDoc(description.GroupName, new OpenApiInfo
            {
                Title = "My API",
                Version = description.ApiVersion.ToString(),
                Description = description.IsDeprecated
                    ? "This API version is deprecated. Please migrate to a newer version."
                    : "Current stable version."
            });
        }
    }

    public void Configure(string? name, SwaggerGenOptions options) =>
        Configure(options);
}

With this setup, Swagger UI shows a dropdown to switch between API versions. Each version shows only the endpoints relevant to that version -- v1 shows the v1 endpoints, v2 shows the v2 endpoints. This is a significant improvement over a single flat document that includes everything.

Default Version and Assumed Default

Two settings work together to handle unversioned requests gracefully in asp.net core api versioning. DefaultApiVersion sets which version is returned when the system needs to fall back. AssumeDefaultVersionWhenUnspecified = true means a request that provides no version identifier is treated as requesting the default version rather than returning a 400 error.

These settings are your safety net during migration. If you add versioning to an existing API that has clients with hardcoded URLs (no version in the path or query string), setting the default to v1 and enabling assumed default means those clients continue to work transparently. They're effectively pinned to v1 until they explicitly request v2.

The logging infrastructure that sits beneath your versioned API matters for diagnosing which versions clients are using. Serilog in .NET covers structured logging that lets you log the API version on each request and query that data in your log aggregation tool -- critical for understanding migration progress across your client base.

Conclusion

ASP.NET Core API versioning with Asp.Versioning.Mvc gives you a clean, declarative system for managing change in your API. There is no single universal best strategy -- URL segment, query string, and header versioning each suit different client types and organizational conventions. URL segment versioning is the most visible and broadly understood starting point. Query string and header versioning offer alternatives that suit specific client types or organizational preferences. Combined readers let you support multiple strategies simultaneously, and [MapToApiVersion] keeps related version logic co-located when separation isn't warranted.

The full OpenAPI multi-version setup completes the picture -- your versioned API is well-documented and easy for new clients to explore. Add deprecation markers early and communicate them clearly, and you'll have a versioning system that actually helps clients migrate rather than just announcing changes after the fact.

For a deeper look at how version management fits into broader application architecture decisions, the complete guide to monolith architecture in C# and modular monolith patterns provide useful framing for where versioning fits in the larger picture.

Frequently Asked Questions

What is the best versioning strategy for ASP.NET Core APIs?

URL segment versioning is the most commonly recommended starting point because it's immediately visible, easy to test in any HTTP client, and unambiguous in logs and analytics. When you see /api/v2/orders in a log entry, you know exactly which version handled that request. There's no header inspection or query string parsing required.

That said, there's no universal "best" strategy -- it depends on your client types and constraints. If your API is primarily consumed by mobile apps where URLs are hardcoded into app store versions, query string versioning gives you more flexibility without forcing URL changes. If you're building a microservice behind an API gateway, header versioning is often cleaner because the gateway can manage version routing transparently.

The practical recommendation is to start with URL segment versioning unless you have a specific reason not to, and use ApiVersionReader.Combine() if you need to support multiple strategies during a transition.

Can I add versioning to an existing API without breaking existing clients?

Yes -- this is exactly the use case for AssumeDefaultVersionWhenUnspecified = true combined with setting DefaultApiVersion to match the version your existing endpoints implicitly implement. Existing clients that don't send a version identifier continue to receive the v1 behavior. You can add v2 alongside it without touching any existing routes.

The key is to introduce versioning attributes to your existing controllers without changing their behavior. Add [ApiVersion("1.0")] to your controllers, configure the defaults, and deploy. Existing clients see no difference. Then you can introduce v2 at your own pace, communicate the change to clients, and eventually deprecate v1.

Should I version every endpoint or just breaking changes?

Version the API surface as a whole rather than individual endpoints. Versioning at the endpoint level creates an inconsistent experience where different resources of the same API are at different versions, which is confusing for clients. When v2 of your products endpoint is ready, it's cleaner to release a v2 of the API that includes the new products behavior along with the unchanged endpoints from v1.

The practical approach is to build v2 as a full copy of v1 that includes your breaking changes. Non-breaking additions -- new optional fields, new endpoints -- can be added to v1 directly. Breaking changes -- removed fields, changed response shapes, different semantics -- go in v2. This keeps v1 stable for existing clients while v2 gets the new behavior.

How do I deprecate an API version and notify clients?

Mark the version with [ApiVersion("1.0", Deprecated = true)] on your controllers. This causes the framework to include it in the api-deprecated-versions response header when ReportApiVersions = true is set. Clients that check this header can detect they're on a deprecated version.

Beyond the header, communication matters more than the technical mechanism. Document the deprecation timeline in your API changelog and on the Swagger UI page (include a note in the OpenApiInfo.Description). If you have client contact information, direct outreach is more reliable than expecting clients to monitor response headers. Set a realistic sunset date -- six to twelve months is common -- and stick to it.

How does versioning interact with OpenAPI documentation?

With Asp.Versioning.Mvc.ApiExplorer and Swashbuckle, each API version gets its own generated OpenAPI document. Swagger UI shows a dropdown to switch between versions, and each document contains only the endpoints and schemas relevant to that version. Deprecated versions can include a note in the OpenApiInfo description.

The wiring requires implementing IConfigureNamedOptions<SwaggerGenOptions> to iterate over the available version descriptions and create a SwaggerDoc entry for each, as shown in the code example above. Once that's in place, the endpoint filtering happens automatically -- Swashbuckle reads the ApiVersion attributes and assigns each endpoint to the appropriate document.

What happens when a client requests a version that doesn't exist?

By default, the framework returns a 400 Bad Request with a problem details response indicating that the requested API version is unsupported. The response includes the api-supported-versions header so the client knows which versions are available. This is much more informative than a 404 or a generic error message.

You can customize this behavior by implementing a custom IErrorResponseProvider if your API has a specific error format requirement. The default behavior follows the RFC 9110 problem details format, which is appropriate for most APIs and consistent with what the ASP.NET Core Web API fundamentals docs recommend.

Can I use API versioning with minimal APIs?

Yes. Asp.Versioning.Http provides versioning support for minimal APIs. The configuration in Program.cs is similar, but instead of [ApiVersion] attributes on controllers, you call .WithApiVersionSet() and .HasApiVersion() extension methods on endpoints or route groups.

The minimal API versioning syntax looks like this: create an ApiVersionSet using app.NewApiVersionSet("My API").Build(), then apply it to endpoints with .WithApiVersionSet(versionSet).HasApiVersion(1, 0). Route groups can apply a version set at the group level, which cascades to all endpoints in the group. The framework can handle version negotiation and routing the same way regardless of whether you're using controllers or minimal APIs.

Reading about design patterns in the abstract only gets you so far. A chain of responsibility pattern real world example in C# with real infrastructure concerns is what cements the concept into something you can actually use at work. This article walks through a complete HTTP request processing pipeline -- the kind you'd build for an API gateway -- where each handler in the chain decides whether a request should proceed or get rejected. By the end, you'll have a fully implemented chain covering rate limiting, authentication, authorization, validation, and routing -- all configurable through dependency injection.

The Problem: HTTP Request Processing Pipeline

Imagine you're building an API gateway that sits in front of several backend services. Every incoming request needs to pass through several stages before it reaches its destination: rate limiting checks the caller's quota, authentication verifies the JWT token, and authorization confirms the right permissions.

After those security gates, the request still needs body validation and routing to the correct backend service. Without a structured approach, this logic collapses into a massive nested if/else block:

public sealed class MonolithicGateway
{
    public async Task<GatewayResponse> ProcessAsync(
        GatewayRequest request)
    {
        if (IsRateLimited(request.ClientId))
            return new GatewayResponse(429, "Rate limit exceeded");

        if (!IsValidToken(request.AuthToken))
            return new GatewayResponse(401, "Invalid token");

        if (!HasPermission(request.UserId, request.Resource))
            return new GatewayResponse(403, "Forbidden");

        if (!IsValidPayload(request.Body))
            return new GatewayResponse(400, "Invalid request body");

        return await RouteToServiceAsync(request);
    }
}

This works for five checks. But real API gateways accumulate dozens of concerns over time -- logging, tracing, CORS, request transformation. Each new concern makes the method longer and harder to test. The chain of responsibility pattern solves this by turning each concern into an independent handler that can be composed, reordered, and tested in isolation.

Designing the Handler Base

The foundation of our chain of responsibility pattern real world example in C# is a pair of types: a request/response model and an abstract handler that defines the chaining mechanism. Let's start with the request and response:

namespace Gateway.Pipeline;

public sealed class GatewayRequest
{
    public required string ClientId { get; init; }

    public required string AuthToken { get; init; }

    public required string UserId { get; init; }

    public required string Resource { get; init; }

    public required string HttpMethod { get; init; }

    public required string Path { get; init; }

    public string? Body { get; init; }
}

public sealed class GatewayResponse
{
    public int StatusCode { get; init; }

    public string Message { get; init; }

    public GatewayResponse(int statusCode, string message)
    {
        StatusCode = statusCode;
        Message = message;
    }
}

Now for the abstract handler that all concrete implementations will extend:

namespace Gateway.Pipeline;

public abstract class RequestHandler
{
    private RequestHandler? _next;

    public RequestHandler SetNext(RequestHandler next)
    {
        _next = next;
        return next;
    }

    public virtual async Task<GatewayResponse> HandleAsync(
        GatewayRequest request)
    {
        if (_next is not null)
        {
            return await _next.HandleAsync(request);
        }

        return new GatewayResponse(
            500,
            "No handler processed the request");
    }
}

The SetNext method wires handlers together and returns the next handler for fluent chaining. The HandleAsync method provides default pass-through behavior -- if a concrete handler doesn't short-circuit, it delegates to the next handler. If you've worked with the strategy design pattern, you'll notice a similar emphasis on isolating behavior behind a common contract -- except here, handlers are linked sequentially rather than swapped interchangeably.

Implementing the Handler Chain

With the base class in place, let's build five concrete handlers. Each one examines the request, either rejects it or passes it along.

RateLimitHandler

The first handler checks whether the client has exceeded their allowed request rate:

using System.Collections.Concurrent;

namespace Gateway.Pipeline.Handlers;

public sealed class RateLimitHandler : RequestHandler
{
    private readonly ConcurrentDictionary<string, ClientRateInfo>
        _clients = new();
    private readonly int _maxRequests;
    private readonly TimeSpan _window;

    public RateLimitHandler(
        int maxRequests = 100,
        TimeSpan? window = null)
    {
        _maxRequests = maxRequests;
        _window = window ?? TimeSpan.FromMinutes(1);
    }

    public override async Task<GatewayResponse> HandleAsync(
        GatewayRequest request)
    {
        var info = _clients.GetOrAdd(
            request.ClientId,
            _ => new ClientRateInfo());

        if (info.IsExpired(_window))
        {
            info.Reset();
        }

        info.IncrementCount();

        if (info.Count > _maxRequests)
        {
            return new GatewayResponse(
                429,
                "Rate limit exceeded");
        }

        return await base.HandleAsync(request);
    }
}

public sealed class ClientRateInfo
{
    public int Count { get; private set; }

    public DateTimeOffset WindowStart { get; private set; }
        = DateTimeOffset.UtcNow;

    public bool IsExpired(TimeSpan window) =>
        DateTimeOffset.UtcNow - WindowStart > window;

    public void Reset()
    {
        Count = 0;
        WindowStart = DateTimeOffset.UtcNow;
    }

    public void IncrementCount() => Count++;
}

When the client is within their limit, the handler calls base.HandleAsync(request) to pass the request down the chain. When the limit is exceeded, it short-circuits with a 429 response.

AuthenticationHandler

The authentication handler validates the JWT token attached to the request:

namespace Gateway.Pipeline.Handlers;

public sealed class AuthenticationHandler : RequestHandler
{
    private readonly ITokenValidator _tokenValidator;

    public AuthenticationHandler(
        ITokenValidator tokenValidator)
    {
        _tokenValidator = tokenValidator;
    }

    public override async Task<GatewayResponse> HandleAsync(
        GatewayRequest request)
    {
        if (string.IsNullOrEmpty(request.AuthToken))
        {
            return new GatewayResponse(
                401,
                "Missing authentication token");
        }

        var isValid = await _tokenValidator
            .ValidateAsync(request.AuthToken);

        if (!isValid)
        {
            return new GatewayResponse(
                401,
                "Invalid or expired token");
        }

        return await base.HandleAsync(request);
    }
}

public interface ITokenValidator
{
    Task<bool> ValidateAsync(string token);
}

The ITokenValidator interface keeps the handler testable -- this is the same inversion of control principle that makes the whole chain composable.

AuthorizationHandler

The authorization handler checks whether the user has permission to access the requested resource:

namespace Gateway.Pipeline.Handlers;

public sealed class AuthorizationHandler : RequestHandler
{
    private readonly IAuthorizationService _authService;

    public AuthorizationHandler(
        IAuthorizationService authService)
    {
        _authService = authService;
    }

    public override async Task<GatewayResponse> HandleAsync(
        GatewayRequest request)
    {
        var isAuthorized = await _authService
            .IsAuthorizedAsync(
                request.UserId,
                request.Resource,
                request.HttpMethod);

        if (!isAuthorized)
        {
            return new GatewayResponse(
                403,
                "Insufficient permissions");
        }

        return await base.HandleAsync(request);
    }
}

public interface IAuthorizationService
{
    Task<bool> IsAuthorizedAsync(
        string userId,
        string resource,
        string httpMethod);
}

The pattern is consistent across every handler: check a condition, return an error response if it fails, or delegate to the next handler.

InputValidationHandler

The validation handler examines the request body for write operations and passes read operations through:

namespace Gateway.Pipeline.Handlers;

public sealed class InputValidationHandler : RequestHandler
{
    private readonly IRequestBodyValidator _bodyValidator;

    public InputValidationHandler(
        IRequestBodyValidator bodyValidator)
    {
        _bodyValidator = bodyValidator;
    }

    public override async Task<GatewayResponse> HandleAsync(
        GatewayRequest request)
    {
        var requiresBody = request.HttpMethod is
            "POST" or "PUT" or "PATCH";

        if (requiresBody &&
            string.IsNullOrWhiteSpace(request.Body))
        {
            return new GatewayResponse(
                400,
                "Request body is required");
        }

        if (requiresBody)
        {
            var validation = await _bodyValidator
                .ValidateAsync(
                    request.Path,
                    request.Body!);

            if (!validation.IsValid)
            {
                return new GatewayResponse(
                    400,
                    $"Validation failed: " +
                    $"{validation.ErrorMessage}");
            }
        }

        return await base.HandleAsync(request);
    }
}

public interface IRequestBodyValidator
{
    Task<ValidationResult> ValidateAsync(
        string path,
        string body);
}

public sealed class ValidationResult
{
    public bool IsValid { get; init; }

    public string? ErrorMessage { get; init; }

    public static ValidationResult Success() =>
        new() { IsValid = true };

    public static ValidationResult Failure(string error) =>
        new() { IsValid = false, ErrorMessage = error };
}

Not every handler needs to act on every request -- GET and DELETE requests skip body validation entirely.

RequestRoutingHandler

The final handler routes the validated request to the appropriate backend service:

namespace Gateway.Pipeline.Handlers;

public sealed class RequestRoutingHandler : RequestHandler
{
    private readonly IServiceRouter _router;

    public RequestRoutingHandler(IServiceRouter router)
    {
        _router = router;
    }

    public override async Task<GatewayResponse> HandleAsync(
        GatewayRequest request)
    {
        var result = await _router.RouteAsync(
            request.Path,
            request.HttpMethod,
            request.Body);

        return new GatewayResponse(
            result.StatusCode,
            result.ResponseBody);
    }
}

public interface IServiceRouter
{
    Task<RouteResult> RouteAsync(
        string path,
        string httpMethod,
        string? body);
}

public sealed class RouteResult
{
    public required int StatusCode { get; init; }

    public required string ResponseBody { get; init; }
}

This handler intentionally does not call base.HandleAsync -- it's the end of the chain. If you're familiar with the composite design pattern, the distinction is worth noting: composite delegates recursively to children, while chain of responsibility delegates along a flat sequence with explicit short-circuiting.

Building and Configuring the Chain

Having five handlers is great, but you need a clean way to assemble them. A factory class combined with IServiceCollection registration gives you a flexible, configuration-driven pipeline:

using Microsoft.Extensions.DependencyInjection;

namespace Gateway.Pipeline;

public static class PipelineServiceExtensions
{
    public static IServiceCollection AddGatewayPipeline(
        this IServiceCollection services)
    {
        services.AddSingleton<RateLimitHandler>();
        services.AddSingleton<AuthenticationHandler>();
        services.AddSingleton<AuthorizationHandler>();
        services.AddSingleton<InputValidationHandler>();
        services.AddSingleton<RequestRoutingHandler>();
        services.AddSingleton<IPipelineFactory,
            PipelineFactory>();

        return services;
    }
}

public interface IPipelineFactory
{
    RequestHandler CreatePipeline();
}

public sealed class PipelineFactory : IPipelineFactory
{
    private readonly IServiceProvider _serviceProvider;

    public PipelineFactory(
        IServiceProvider serviceProvider)
    {
        _serviceProvider = serviceProvider;
    }

    public RequestHandler CreatePipeline()
    {
        var handlers = new RequestHandler[]
        {
            _serviceProvider
                .GetRequiredService<RateLimitHandler>(),
            _serviceProvider
                .GetRequiredService<AuthenticationHandler>(),
            _serviceProvider
                .GetRequiredService<AuthorizationHandler>(),
            _serviceProvider
                .GetRequiredService<InputValidationHandler>(),
            _serviceProvider
                .GetRequiredService<RequestRoutingHandler>(),
        };

        for (int i = 0; i < handlers.Length - 1; i++)
        {
            handlers[i].SetNext(handlers[i + 1]);
        }

        return handlers[0];
    }
}

The factory resolves each handler from the DI container and chains them in a loop. The order in the array is the order of execution -- if you need to insert a new handler, you add one line to the array. This separation between construction and execution is the same principle behind inversion of control. Using the factory from application code is straightforward:

var pipeline = pipelineFactory.CreatePipeline();
var response = await pipeline.HandleAsync(request);

Adding Resilience and Observability

A chain of responsibility pattern real world example in C# isn't complete without addressing production concerns. Let's enhance the pipeline with structured logging, metrics, and circuit breaker support.

The cleanest approach is an observability-aware base handler that wraps each handler with cross-cutting concerns:

using System.Diagnostics;

using Microsoft.Extensions.Logging;

namespace Gateway.Pipeline;

public abstract class ObservableHandler : RequestHandler
{
    private readonly ILogger _logger;
    private readonly string _handlerName;

    protected ObservableHandler(ILogger logger)
    {
        _logger = logger;
        _handlerName = GetType().Name;
    }

    public override async Task<GatewayResponse> HandleAsync(
        GatewayRequest request)
    {
        var stopwatch = Stopwatch.StartNew();

        _logger.LogInformation(
            "Handler {HandlerName} processing " +
            "request for {Path}",
            _handlerName,
            request.Path);

        try
        {
            var response = await ProcessAsync(request);
            stopwatch.Stop();

            _logger.LogInformation(
                "Handler {HandlerName} completed " +
                "in {ElapsedMs}ms with status {StatusCode}",
                _handlerName,
                stopwatch.ElapsedMilliseconds,
                response.StatusCode);

            return response;
        }
        catch (Exception ex)
        {
            stopwatch.Stop();

            _logger.LogError(
                ex,
                "Handler {HandlerName} failed " +
                "after {ElapsedMs}ms",
                _handlerName,
                stopwatch.ElapsedMilliseconds);

            return new GatewayResponse(
                500,
                $"Internal error in {_handlerName}");
        }
    }

    protected abstract Task<GatewayResponse> ProcessAsync(
        GatewayRequest request);
}

This base class wraps every handler execution with timing, structured logging, and exception handling. Concrete handlers override ProcessAsync instead of HandleAsync -- the observable base adds instrumentation transparently. If you've worked with the observer design pattern, the concept is similar: external observers react to handler execution without modifying core logic.

For circuit breaker support, create a state object that any handler calling external services can check:

namespace Gateway.Pipeline.Handlers;

public sealed class CircuitBreakerState
{
    private int _failureCount;
    private DateTimeOffset _lastFailure;

    public int FailureThreshold { get; init; } = 5;

    public TimeSpan RecoveryWindow { get; init; }
        = TimeSpan.FromSeconds(30);

    public bool IsOpen =>
        _failureCount >= FailureThreshold &&
        DateTimeOffset.UtcNow - _lastFailure
            < RecoveryWindow;

    public void RecordFailure()
    {
        _failureCount++;
        _lastFailure = DateTimeOffset.UtcNow;
    }

    public void Reset() => _failureCount = 0;
}

This state object can be injected into any handler that calls external services. When the circuit is open, the handler returns a 503 immediately instead of forwarding the request to a service that's likely down.

Testing the Complete Pipeline

Testing is where the chain of responsibility pattern shines. Because each handler is a separate class with injected dependencies, you can write focused tests for individual handlers and the full chain.

First, test helpers and stub dependencies:

using Xunit;

namespace Gateway.Pipeline.Tests;

public static class TestRequestFactory
{
    public static GatewayRequest CreateValid() =>
        new()
        {
            ClientId = "client-1",
            AuthToken = "valid-token",
            UserId = "user-1",
            Resource = "/api/orders",
            HttpMethod = "GET",
            Path = "/api/orders",
            Body = null,
        };
}

public sealed class StubTokenValidator : ITokenValidator
{
    private readonly bool _isValid;

    public StubTokenValidator(bool isValid) =>
        _isValid = isValid;

    public Task<bool> ValidateAsync(string token) =>
        Task.FromResult(_isValid);
}

public sealed class StubAuthorizationService
    : IAuthorizationService
{
    private readonly bool _isAuthorized;

    public StubAuthorizationService(bool isAuthorized) =>
        _isAuthorized = isAuthorized;

    public Task<bool> IsAuthorizedAsync(
        string userId,
        string resource,
        string httpMethod) =>
        Task.FromResult(_isAuthorized);
}

public sealed class StubServiceRouter : IServiceRouter
{
    public Task<RouteResult> RouteAsync(
        string path,
        string httpMethod,
        string? body) =>
        Task.FromResult(new RouteResult
        {
            StatusCode = 200,
            ResponseBody = "OK",
        });
}

public sealed class StubRequestBodyValidator
    : IRequestBodyValidator
{
    private readonly bool _isValid;

    public StubRequestBodyValidator(bool isValid) =>
        _isValid = isValid;

    public Task<ValidationResult> ValidateAsync(
        string path,
        string body) =>
        Task.FromResult(
            _isValid
                ? ValidationResult.Success()
                : ValidationResult.Failure(
                    "Invalid body"));
}
}

Now, individual handler tests:

namespace Gateway.Pipeline.Tests;

public sealed class AuthenticationHandlerTests
{
    [Fact]
    public async Task HandleAsync_MissingToken_Returns401()
    {
        var handler = new AuthenticationHandler(
            new StubTokenValidator(true));

        var request = new GatewayRequest
        {
            ClientId = "c1",
            AuthToken = string.Empty,
            UserId = "u1",
            Resource = "/api/orders",
            HttpMethod = "GET",
            Path = "/api/orders",
        };

        var response = await handler.HandleAsync(request);

        Assert.Equal(401, response.StatusCode);
    }

    [Fact]
    public async Task HandleAsync_ValidToken_DelegatesToNext()
    {
        var handler = new AuthenticationHandler(
            new StubTokenValidator(true));

        var routing = new RequestRoutingHandler(
            new StubServiceRouter());

        handler.SetNext(routing);

        var request = TestRequestFactory.CreateValid();

        var response = await handler.HandleAsync(request);

        Assert.Equal(200, response.StatusCode);
    }
}

Full chain integration tests verify the handlers work together:

namespace Gateway.Pipeline.Tests;

public sealed class FullPipelineTests
{
    private RequestHandler BuildChain(
        bool tokenValid = true,
        bool authorized = true)
    {
        var rateLimit = new RateLimitHandler(
            maxRequests: 100);

        var auth = new AuthenticationHandler(
            new StubTokenValidator(tokenValid));

        var authz = new AuthorizationHandler(
            new StubAuthorizationService(authorized));

        var validation = new InputValidationHandler(
            new StubRequestBodyValidator(true));

        var routing = new RequestRoutingHandler(
            new StubServiceRouter());

        rateLimit.SetNext(auth);
        auth.SetNext(authz);
        authz.SetNext(validation);
        validation.SetNext(routing);

        return rateLimit;
    }

    [Fact]
    public async Task
        HandleAsync_ValidRequest_Returns200()
    {
        var pipeline = BuildChain();
        var request = TestRequestFactory.CreateValid();

        var response = await pipeline
            .HandleAsync(request);

        Assert.Equal(200, response.StatusCode);
        Assert.Equal("OK", response.Message);
    }

    [Fact]
    public async Task
        HandleAsync_InvalidToken_ShortCircuitsAt401()
    {
        var pipeline = BuildChain(tokenValid: false);
        var request = TestRequestFactory.CreateValid();

        var response = await pipeline
            .HandleAsync(request);

        Assert.Equal(401, response.StatusCode);
    }

    [Fact]
    public async Task
        HandleAsync_Unauthorized_ShortCircuitsAt403()
    {
        var pipeline = BuildChain(authorized: false);
        var request = TestRequestFactory.CreateValid();

        var response = await pipeline
            .HandleAsync(request);

        Assert.Equal(403, response.StatusCode);
    }

    [Fact]
    public async Task
        HandleAsync_ExceedsRateLimit_Returns429()
    {
        var rateLimit = new RateLimitHandler(
            maxRequests: 2);

        var routing = new RequestRoutingHandler(
            new StubServiceRouter());

        rateLimit.SetNext(routing);

        var request = TestRequestFactory.CreateValid();

        await rateLimit.HandleAsync(request);
        await rateLimit.HandleAsync(request);
        var response = await rateLimit
            .HandleAsync(request);

        Assert.Equal(429, response.StatusCode);
    }
}

The BuildChain helper accepts parameters that control which stubs succeed or fail, making it trivial to test every short-circuit point without duplicating setup code. Compare this to the monolithic gateway -- you'd need to mock every dependency simultaneously and verify behavior through a single sprawling method.

If you're interested in how the proxy design pattern or the decorator design pattern handle similar concerns with different structural tradeoffs, those patterns are worth comparing.

Frequently Asked Questions

How is the chain of responsibility pattern different from middleware in ASP.NET Core?

ASP.NET Core middleware and the chain of responsibility pattern share the same fundamental idea: a request flows through a sequence of processing steps, and any step can short-circuit the pipeline. The key difference is structural. Middleware uses a delegate-based pipeline managed by the framework, while the chain of responsibility pattern uses explicit object references with a SetNext method. The chain of responsibility pattern gives you stronger type safety and is portable to any context -- not just HTTP request processing.

When should I use the chain of responsibility pattern instead of a simple switch statement?

Use the chain of responsibility pattern when the processing stages are independently complex, need to be reordered or reconfigured, or when new stages are added frequently. A switch statement works fine when you're dispatching to a fixed, well-known set of handlers that rarely change. Once you find yourself adding new cases every sprint and the method is growing past a screen's length, the chain gives you a much cleaner extension path.

Can handlers in the chain modify the request before passing it along?

Yes. Handlers can enrich or transform the request before delegating to the next handler. For example, an authentication handler could attach a parsed user identity to the request object after validating the token. Use a mutable context object that handlers can write to, but keep modifications documented so future developers know which handler produces which data.

How do I handle errors that occur deep in the handler chain?

Use the ObservableHandler base class shown in this article, which catches exceptions at each handler level and logs exactly which handler failed. For production systems, combining per-handler exception handling with a global error boundary gives you both specificity and safety.

What's the performance impact of a long handler chain?

Each handler adds one async method call and one null check. This overhead is negligible compared to the actual work each handler performs -- database lookups, HTTP calls, token validation. Profile before optimizing, and focus on the I/O-bound operations inside your handlers rather than the chain structure itself.

Should each handler be a singleton or transient in the DI container?

It depends on whether the handler holds state. The RateLimitHandler tracks per-client request counts, so it needs to be a singleton. Stateless handlers like InputValidationHandler can be transient. When in doubt, register as singleton and ensure your handler is thread-safe.

How do I add a new handler without modifying existing code?

Register the new handler in the DI container, then add it to the array in PipelineFactory.CreatePipeline() at the position where you want it to execute. No existing handler code changes. This is the Open/Closed Principle in action -- the chain is open for extension (new handlers) but closed for modification (existing handlers remain untouched).

Wrapping Up This Chain of Responsibility Pattern Example

This implementation demonstrates the chain of responsibility pattern handling a real infrastructure concern -- API gateway request processing -- with five handlers that each focus on a single responsibility. We started with a monolithic method that tangled every concern together and ended with independent, testable handlers that snap together in a configurable pipeline.

The pattern scales gracefully. Adding a new concern means writing one handler class and inserting it into the factory's array. Removing one means deleting a single line. Take this implementation, swap the stubs for real JWT validators and authorization services, and you have a production-ready gateway pipeline.