Middleware Ordering & Built-in Middleware

Why Ordering Matters

The Recommended Middleware Order

// Recommended order:
app.UseExceptionHandler();    // 1. Catch all exceptions
app.UseHsts();                // 2. HTTP Strict Transport Security
app.UseHttpsRedirection();    // 3. Redirect HTTP to HTTPS
app.UseStaticFiles();         // 4. Serve static assets
app.UseRouting();             // 5. Match route patterns
app.UseCors();                // 6. Cross-Origin
app.UseAuthentication();      // 7. Who are you?
app.UseAuthorization();       // 8. Are you allowed?
app.UseRateLimiter();         // 9. Throttle
app.UseOutputCache();         // 10. Cache responses
// Map endpoints here
app.MapControllers();
app.Run();

Exception Handling First

// Development: detailed error page
if (app.Environment.IsDevelopment())
    app.UseDeveloperExceptionPage();
else
{
    // Production: generic error page + structured response
    app.UseExceptionHandler("/error");
    app.UseHsts();
}

// OR: use ProblemDetails globally (recommended .NET 8+)
builder.Services.AddProblemDetails();
app.UseExceptionHandler();
// All unhandled exceptions -> RFC 7807 ProblemDetails JSON

Static Files Before Routing

app.UseStaticFiles(); // serves wwwroot/* without going through auth
app.UseRouting();     // expensive: runs route matching

// If you put UseStaticFiles AFTER UseRouting, the route
// matcher runs unnecessarily for every .js/.css request.
// Serve static files first for better performance.

Authentication Before Authorization

// WRONG ORDER — authorization runs before user is populated:
app.UseAuthorization();  // user is null → everything allowed!
app.UseAuthentication(); // too late

// CORRECT:
app.UseAuthentication(); // populates context.User
app.UseAuthorization();  // checks context.User against policies

CORS Before Authentication

builder.Services.AddCors(opts =>
    opts.AddPolicy("Frontend", p =>
        p.WithOrigins("https://myapp.com")
         .AllowAnyHeader()
         .AllowAnyMethod()));

app.UseRouting();
app.UseCors("Frontend"); // before auth — handles OPTIONS pre-flight
app.UseAuthentication();
app.UseAuthorization();

Common Built-In Middleware

// Compression: compresses responses (must be before static files)
builder.Services.AddResponseCompression();
app.UseResponseCompression();

// Request localization: sets culture from Accept-Language header
builder.Services.AddLocalization();
app.UseRequestLocalization();

// Health checks: /health endpoint
builder.Services.AddHealthChecks();
app.MapHealthChecks("/health");

// Forwarded headers: trust X-Forwarded-For from reverse proxy
app.UseForwardedHeaders();

Routing Middleware Deep Dive

app.UseRouting(); // matches route, stores in context

// Between UseRouting and Map*: middleware can read route data
app.Use(async (ctx, next) =>
{
    var endpoint = ctx.GetEndpoint();
    var routeName = endpoint?.DisplayName;
    Console.WriteLine($"Matched: {routeName}");
    await next(ctx);
});

// All auth and other middleware go here
app.UseAuthentication();
app.UseAuthorization();

// Execute the matched endpoint
app.MapControllers();
app.MapGet("/", () => "Home");

Response Compression Placement

// Correct placement for response compression:
app.UseExceptionHandler();
app.UseResponseCompression(); // before static files
app.UseStaticFiles();          // compressed static files
app.UseRouting();
// ... rest of pipeline

Real-World: Full Production Pipeline

var app = builder.Build();

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

app.UseResponseCompression();
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseCors("AllowFrontend");
app.UseAuthentication();
app.UseAuthorization();
app.UseRateLimiter();
app.UseOutputCache();

app.MapHealthChecks("/health").AllowAnonymous();
app.MapControllers();

app.Run();

Quick Check

Recap: Middleware Ordering & Built-In Middleware