ASP.NET Core middleware order

n. Browsers send preflight OPTIONS requests that should not require authentication. If Authorization precedes CORS, preflight requests will be rejected with 401, breaking cross-origin functionality.

// Layer 5: CORS & Auth
app.UseCors("DefaultPolicy");
app.UseAuthentication();
app.UseAuthorization();

Step 6: Endpoints

Endpoints are the innermost layer. UseEndpoints executes the matched endpoint. This must be last to ensure all security, routing, and policy checks have completed.

// Layer 6: Endpoints
app.MapControllers();
app.MapRazorPages();

Architecture Decisions

• Short-Circuiting: Middleware like UseStaticFiles and UseDefaultFiles should be positioned to short-circuit requests that do not require dynamic processing. This reduces memory allocation and CPU usage.
• Response Path Symmetry: Custom middleware that modifies the response (e.g., compression, logging) must be placed such that the response modification occurs after the endpoint generates content but before the response is finalized.
• Conditional Middleware: Use app.UseWhen to apply middleware only to specific paths or conditions, avoiding pipeline bloat.

Pitfall Guide

Production environments reveal subtle failures caused by middleware misordering. The following pitfalls are drawn from real-world incident reports.

1. Static Files Leaking Behind Authentication:

   • Mistake: Placing UseStaticFiles after UseAuthorization.
   • Impact: Static files are served without authentication checks, potentially exposing sensitive assets.
   • Fix: Place UseStaticFiles before UseAuthorization. If static files require auth, use UseStaticFiles with a custom OnPrepareResponse or serve them via a controller/action with [Authorize].

2. CORS Preflight Rejection:

   • Mistake: Placing UseAuthorization before UseCors.
   • Impact: Browsers send OPTIONS requests for CORS. Authorization middleware rejects these requests with 401, causing CORS failures in clients.
   • Fix: Ensure UseCors precedes UseAuthorization.

3. Exception Handler Shadowing:

   • Mistake: Placing UseExceptionHandler after middleware that catches and handles exceptions internally.
   • Impact: The global error handler never sees exceptions thrown by downstream components.
   • Fix: UseExceptionHandler must be the first middleware registered.

4. Logging Order and Performance:

   • Mistake: Placing request logging middleware after UseStaticFiles.
   • Impact: Static file requests are not logged, creating gaps in telemetry. Alternatively, placing verbose logging before short-circuiting middleware logs requests that are never processed, inflating log volume.
   • Fix: Place logging early if you need full request visibility, or use UseWhen to scope logging to dynamic requests.

5. Response Body Modification Failures:

   • Mistake: Middleware attempts to read or modify the response body after UseEndpoints without enabling buffering.
   • Impact: InvalidOperationException or missing response content. The response body stream may be forward-only.
   • Fix: Use app.Use(async (context, next) => { context.Response.EnableBuffering(); await next(); ... }); to allow multiple reads of the response stream.

6. Environment-Specific Leakage:

   • Mistake: Registering UseDeveloperExceptionPage unconditionally.
   • Impact: Stack traces and sensitive data exposed in production.
   • Fix: Wrap environment-specific middleware in if (app.Environment.IsDevelopment()).

7. Routing and Endpoint Order Dependency:

   • Mistake: Using UseEndpoints before UseRouting.
   • Impact: Runtime exception. Endpoints cannot be matched without routing.
   • Fix: UseRouting must always precede UseEndpoints.

Production Bundle

Action Checklist

• Audit Pipeline Order: Verify middleware registration follows the Defense-in-Depth pattern: Exception -> Security -> Static -> Routing -> CORS -> Auth -> Endpoints.
• Verify Short-Circuiting: Confirm UseStaticFiles and UseDefaultFiles are positioned to short-circuit requests before routing and auth.
• Check CORS/Auth Sequence: Ensure UseCors executes before UseAuthorization to support preflight requests.
• Validate Exception Handler Scope: Test that a thrown exception in an endpoint is caught by UseExceptionHandler.
• Implement Response Buffering: If any middleware modifies the response body, ensure buffering is enabled and applied before the endpoint.
• Review Conditional Middleware: Replace broad middleware registration with UseWhen or MapWhen where applicable to reduce overhead.
• Test Response Path: Verify that response-modifying middleware executes in the correct reverse order.
• Security Header Audit: Ensure security headers are applied to static file responses, not just dynamic endpoints.

Decision Matrix

Configuration Template

Copy this template for a production-grade Program.cs in .NET 8+.

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddControllersWithViews();
builder.Services.AddRazorPages();
builder.Services.AddCors(options =>
{
    options.AddPolicy("Default", policy => policy.AllowAnyOrigin().AllowAnyMethod().AllowAnyHeader());
});

var app = builder.Build();

// 1. Exception Handling (Outermost)
if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}
else
{
    app.UseExceptionHandler("/Home/Error");
    app.UseHsts();
}

// 2. Security Headers & Redirection
app.UseHttpsRedirection();

// 3. Static Files (Short-circuiting)
app.UseStaticFiles();

// 4. Routing
app.UseRouting();

// 5. CORS (Before Auth for Preflight)
app.UseCors("Default");

// 6. Authentication & Authorization
app.UseAuthentication();
app.UseAuthorization();

// 7. Endpoints (Innermost)
app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

app.MapRazorPages();

app.Run();

Quick Start Guide

1. Create Project: Run dotnet new webapi -n MiddlewareOrderDemo and open Program.cs.
2. Insert Custom Middleware: Create a simple middleware that logs request start and end.

   app.Use(async (context, next) =>
   {
       Console.WriteLine($"[Request] {context.Request.Path}");
       await next();
       Console.WriteLine($"[Response] {context.Response.StatusCode}");
   });
   

3. Order Verification: Place the custom middleware in different positions relative to UseRouting and MapControllers. Observe console output. Note how placement affects whether static requests or 404s are logged.
4. Test Short-Circuiting: Add a wwwroot/index.html. Request the file. Verify that if UseStaticFiles is before your middleware, the middleware is skipped. If after, it runs.
5. Validate Security: Attempt to access a protected controller without auth. Verify that UseAuthorization blocks the request and UseExceptionHandler can catch errors if you force one in the controller.

Middleware order is the foundation of ASP.NET Core application stability. By enforcing lifecycle symmetry and adhering to the Defense-in-Depth pattern, teams eliminate silent failures, secure static assets, and optimize request throughput. Treat the pipeline as code, not configuration, and review its order with every architectural change.