ASP.NET Core Request Pipeline: Architecture, Optimization, and Production Patterns

nc Task InvokeAsync(HttpContext context, RequestDelegate next) { // Logic using scoped _auditRepo await next(context); } }

### 3. Strategic Ordering and Short-Circuiting

The optimal pipeline order minimizes work for high-volume, low-complexity requests.

```csharp
var builder = WebApplication.CreateBuilder(args);

// 1. Exception Handling (Must be outermost)
// 2. Security Headers / HSTS
// 3. Routing (Endpoint Routing)
// 4. Static Files (Short-circuit via UseStaticFiles)
// 5. Authentication / Authorization (Only runs on matched endpoints)
// 6. Custom Middleware (e.g., Rate Limiting, Logging)
// 7. Endpoint Execution (MapControllers, MapRazorPages)

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}
else
{
    app.UseExceptionHandler("/error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles(); // Short-circuits static content automatically

app.UseRouting();

app.UseAuthentication();
app.UseAuthorization();

// Branching for high-throughput health checks
app.MapWhen(ctx => ctx.Request.Path.StartsWithSegments("/health"), healthApp =>
{
    healthApp.Run(async context =>
    {
        context.Response.StatusCode = 200;
        await context.Response.WriteAsync("OK");
    });
});

app.MapControllers();

app.Run();

4. Branching with Map and MapWhen

Branching creates isolated pipeline segments. Middleware added to a branch does not affect the main pipeline.

// Isolate API versioning pipeline
app.Map("/api/v1", v1App =>
{
    v1App.UseMiddleware<V1SpecificMiddleware>();
    v1App.MapControllers();
});

app.Map("/api/v2", v2App =>
{
    v2App.UseMiddleware<V2SpecificMiddleware>();
    v2App.MapControllers();
});

Pitfall Guide

1. Scoped Services in Middleware Constructors

Mistake: Injecting a scoped service into the middleware constructor. Impact: The middleware instance is cached and reused. The scoped service is resolved once at startup and effectively becomes a singleton. This causes data leakage between requests and thread-safety violations. Fix: Inject scoped services in the Invoke or InvokeAsync method parameters.

2. Forgetting await next(context)

Mistake: Omitting the call to the next delegate or failing to await it. Impact: The pipeline breaks. The request may hang, return an empty response, or execute subsequent middleware on the wrong thread context. Fix: Always await _next(context); unless intentionally short-circuiting.

3. Modifying Response After Headers Sent

Mistake: Attempting to set headers or status code after the response body has started flushing. Impact: System.InvalidOperationException: Headers are already sent. Fix: Set headers/status codes before invoking _next or before writing to the body. Use context.Response.HasStarted checks if necessary.

4. Synchronous Blocking in Async Pipeline

Mistake: Using .Result or .Wait() on async operations within middleware. Impact: Thread pool starvation. Under load, threads block waiting for I/O, causing throughput to collapse. Fix: Use async/await throughout the pipeline. Ensure all downstream calls are truly asynchronous.

5. Misplaced Exception Handling

Mistake: Placing UseExceptionHandler after routing or authentication. Impact: Exceptions thrown in earlier middleware may not be caught, or the exception handler itself may trigger auth failures. Fix: Place exception handling middleware as early as possible in the pipeline, typically immediately after environment checks.

6. Over-Reliance on UseWhen

Mistake: Using UseWhen for complex routing logic. Impact: Predicate evaluation adds overhead. Deeply nested conditions make the pipeline graph difficult to debug and maintain. Fix: Prefer Map for path-based branching and Endpoint Routing for complex matching. Reserve UseWhen for simple header or query-based splits.

7. Ignoring Endpoint Routing Implications

Mistake: Using legacy UseMvc patterns or ignoring UseRouting. Impact: Loss of endpoint metadata, inability to use [Authorize] on controllers, and inefficient request matching. Fix: Always use UseRouting followed by UseAuthorization and UseEndpoints (or MapControllers). This enables the modern endpoint-based middleware model.

Production Bundle

Action Checklist

• Audit Middleware Order: Verify that static files, health checks, and routing occur before authentication and logging.
• Verify DI Lifetimes: Ensure scoped services are injected via Invoke method parameters, not constructors.
• Enforce Async/Await: Scan middleware code for .Result or .Wait() calls; replace with asynchronous equivalents.
• Implement Short-Circuiting: Add MapWhen or UseStaticFiles to bypass expensive middleware for non-API requests.
• Review Exception Boundaries: Confirm UseExceptionHandler is positioned to catch errors from all critical middleware.
• Check Response Mutability: Ensure no middleware modifies headers after HasStarted is true.
• Add Pipeline Metrics: Instrument entry and exit of the pipeline to measure end-to-end latency and middleware contribution.

Decision Matrix

Configuration Template

Copy this template for a production-ready pipeline setup with best practices.

var builder = WebApplication.CreateBuilder(args);

// Services registration
builder.Services.AddRouting();
builder.Services.AddControllers();
builder.Services.AddAuthentication();
builder.Services.AddAuthorization();
builder.Services.AddHealthChecks();
// Register middleware services

var app = builder.Build();

// 1. Diagnostics & Error Handling
if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}
else
{
    app.UseExceptionHandler("/error");
    app.UseHsts();
}

// 2. Security & Protocol
app.UseHttpsRedirection();
app.UseHsts();

// 3. Static & Health (Short-Circuit Layer)
app.UseStaticFiles();
app.MapHealthChecks("/health");
app.MapHealthChecks("/ready");

// 4. Routing
app.UseRouting();

// 5. Security Middleware
app.UseAuthentication();
app.UseAuthorization();

// 6. Custom Middleware (Ordered by cost/dependency)
app.UseMiddleware<RateLimitingMiddleware>();
app.UseMiddleware<RequestCorrelationMiddleware>();

// 7. Endpoint Execution
app.MapControllers();
app.MapRazorPages();

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

app.Run();

Quick Start Guide

1. Create Middleware Class: Define a class with a constructor accepting RequestDelegate and an InvokeAsync method accepting HttpContext.

   public class MyMiddleware
   {
       private readonly RequestDelegate _next;
       public MyMiddleware(RequestDelegate next) => _next = next;
       public async Task InvokeAsync(HttpContext context)
       {
           // Pre-logic
           await _next(context);
           // Post-logic
       }
   }
   

2. Register in DI: Add the middleware to the service collection in Program.cs.

   builder.Services.AddTransient<MyMiddleware>();
   

3. Add to Pipeline: Insert the middleware in the correct order within Program.cs.

   app.UseMiddleware<MyMiddleware>();
   

4. Validate Execution: Run the application and use a tool like curl or Postman to trigger requests. Verify middleware execution via logging or breakpoints. Check that scoped services resolve correctly per request.

5. Benchmark: Use bombardier or k6 to test throughput. Compare metrics before and after adding middleware to ensure performance targets are met. Adjust ordering if latency increases disproportionately.