ASP.NET Core middleware patterns

});

Branching reduces pipeline depth for non-API requests by 60–80%, directly lowering allocation and thread context switches.

### Step 3: Apply Short-Circuiting Patterns
Short-circuiting terminates the pipeline early when downstream processing is unnecessary. Common use cases: static files, health checks, preflight CORS, and cached responses. Implement short-circuiting by returning `Task.CompletedTask` or calling `context.Response.CompleteAsync()` without invoking `next`.

```csharp
public sealed class CacheShortCircuitMiddleware : IMiddleware
{
    private readonly IMemoryCache _cache;

    public CacheShortCircuitMiddleware(IMemoryCache cache) => _cache = cache;

    public async Task InvokeAsync(HttpContext context)
    {
        var cacheKey = context.Request.Path.Value;
        if (_cache.TryGetValue(cacheKey, out CachedResponse? cached) && cached is not null)
        {
            context.Response.StatusCode = cached.StatusCode;
            context.Response.ContentType = cached.ContentType;
            await context.Response.WriteAsync(cached.Body);
            return; // Short-circuit
        }
        await context.Response.WriteAsync("placeholder"); // Continue pipeline
    }
}

Step 4: Enforce DI Scope Validation

ASP.NET Core validates DI scopes by default in development. In production, disable ValidateScopes only after verifying no captive dependencies exist. Use IServiceProviderIsService or explicit scope factories when middleware must resolve services dynamically.

builder.Host.UseDefaultServiceProvider(options =>
{
    options.ValidateScopes = true; // Keep enabled in staging; disable in prod only after audit
});

Architecture Rationale

• IMiddleware over convention: Guarantees per-request DI resolution, preventing scope leakage and captive dependencies.
• Branching over monolithic pipelines: Reduces execution graph width, isolates failure domains, and enables route-specific middleware stacks.
• Short-circuiting over conditional logic: Eliminates downstream delegate invocations, reducing stack depth and allocation.
• DiagnosticSource over Console/Debug: Provides zero-allocation event publishing compatible with OpenTelemetry, Application Insights, and custom telemetry pipelines.

Pitfall Guide

1. Synchronous blocking in async middleware Calling .Result or .Wait() on async operations inside Invoke blocks the thread pool. ASP.NET Core expects non-blocking I/O. Use await consistently. Blocking causes thread starvation under load, manifesting as request queue saturation.

2. Pipeline ordering violations Middleware executes in registration order. Placing UseAuthentication() before UseRouting() forces auth evaluation on every request, including static files and health checks. Correct order: Routing → Auth → Authorization → CORS → Endpoints. Violations cause 401/403 responses on public routes and unnecessary token validation overhead.

3. Closure capture in inline delegates Inline app.Use(async (ctx, next) => { ... }) captures variables from the enclosing scope. If those variables hold scoped services or large objects, they become captive dependencies, surviving beyond the request lifecycle. Use IMiddleware or explicit factory registration to avoid closure-induced memory leaks.

4. Overusing app.Use() for cross-cutting concerns Logging, metrics, and error handling are frequently stacked as sequential Use() calls. This creates a deep execution graph where each layer adds allocation and context switching. Consolidate cross-cutting concerns into a single middleware or use DiagnosticSource events to decouple observation from execution.

5. Ignoring HttpContext.Items lifecycle Items is request-scoped but mutable. Multiple middleware layers writing to the same key causes unpredictable state. Enforce key namespacing ("MyApp.Middleware.CacheHit") and treat Items as a contract, not a shared bag. Unscoped writes lead to data corruption in concurrent requests.

6. Missing exception boundary placement Exceptions bubble up the pipeline until caught. If no middleware implements a try/catch boundary, unhandled exceptions terminate the request with a 500 and no structured logging. Place a dedicated error-handling middleware early in the pipeline, but after routing, to capture route-specific context.

7. Best practices from production experience

   • Keep middleware stateless; store per-request data in HttpContext.Items or DI-scoped services.
   • Validate pipeline graph at startup using IApplicationBuilder.ApplicationServices.GetRequiredService<IHostEnvironment>() to log execution order.
   • Use DiagnosticSource for metrics; avoid Stopwatch in hot paths.
   • Test middleware in isolation with Microsoft.AspNetCore.TestHost and mock HttpContext.
   • Audit pipeline depth quarterly; targets should stay under 8 layers for API routes.

Production Bundle

Action Checklist

• Audit pipeline order: Verify Routing → Auth → Authorization → CORS → Endpoints sequence
• Replace inline delegates with IMiddleware for any middleware requiring scoped DI
• Implement Map or MapWhen for health checks, static files, and API routes
• Add short-circuit logic to cache, preflight, and health middleware
• Replace Console/Debug telemetry with DiagnosticSource or OpenTelemetry
• Validate DI scopes in staging; document any prod scope overrides
• Add centralized exception boundary middleware after routing
• Profile pipeline depth quarterly; target ≤8 layers for production routes

Decision Matrix

Configuration Template

// Program.cs - Production-Grade Middleware Pipeline
var builder = WebApplication.CreateBuilder(args);

// DI Registration
builder.Services.AddSingleton<DiagnosticSource>(new DiagnosticListener("MyApp.Pipeline"));
builder.Services.AddScoped<RequestMetricsMiddleware>();
builder.Services.AddScoped<CacheShortCircuitMiddleware>();
builder.Services.AddScoped<ErrorBoundaryMiddleware>();

var app = builder.Build();

// 1. Error boundary (early, after routing context available)
app.UseMiddleware<ErrorBoundaryMiddleware>();

// 2. Static & Health (short-circuit, isolated)
app.Map("/health", health => health.Run(async ctx => await ctx.Response.WriteAsync("OK")));
app.UseStaticFiles();

// 3. API Branch (auth, routing, endpoints)
app.MapWhen(ctx => ctx.Request.Path.StartsWithSegments("/api"), api =>
{
    api.UseRouting();
    api.UseAuthentication();
    api.UseAuthorization();
    api.UseMiddleware<CacheShortCircuitMiddleware>();
    api.UseMiddleware<RequestMetricsMiddleware>();
    api.UseEndpoints(endpoints => endpoints.MapControllers());
});

// 4. Fallback
app.Run(async ctx =>
{
    ctx.Response.StatusCode = 404;
    await ctx.Response.WriteAsync("Not Found");
});

app.Run();

Quick Start Guide

1. Register middleware as IMiddleware: Replace convention-based classes with IMiddleware implementation. Register in IServiceCollection with appropriate lifetime (AddScoped for request-scoped dependencies).
2. Branch non-API routes: Add app.Map("/health", ...) and app.UseStaticFiles() before the main pipeline. Use MapWhen for route predicates.
3. Insert short-circuit logic: In cache, health, or preflight middleware, return early without calling next. Ensure response headers and status codes are set before returning.
4. Validate with DiagnosticSource: Replace Console.WriteLine or ILogger in hot paths with _diagnostics.Write("EventName", payload). Connect to OpenTelemetry or Application Insights for production telemetry.
5. Test pipeline isolation: Use Microsoft.AspNetCore.TestHost to send requests to /health, /api/v1/resource, and static paths. Verify that auth middleware does not execute on health checks, and that cache short-circuits bypass downstream layers.

Middleware patterns are not decorative; they are execution contracts. Branch early, short-circuit aggressively, inject deterministically, and measure continuously. Production .NET applications that treat the pipeline as a graph rather than a list consistently achieve higher throughput, lower allocation, and predictable fault isolation.