ASP.NET Core Web API Introduction - Middleware Order

TLDR

• The execution order of Middleware is crucial; incorrect ordering can lead to functional failures or unexpected behavior.
• UseRouting must be placed before UseRateLimiter (unless using global filters only).
• UseCors must be placed after UseRouting and before UseAuthentication and UseResponseCaching.
• If UseStaticFiles involves cross-origin access or culture-specific requirements, its order relative to UseCors or UseRequestLocalization must be adjusted accordingly.
• UseAuthentication must always be placed before UseAuthorization.
• Endpoint routing (such as MapControllers or MapRazorPages) must be placed at the very end of the pipeline.

Core Middleware Functionality

In ASP.NET Core, Middleware forms the request processing pipeline. Below are the functions and purposes of common Middleware:

• UseDeveloperExceptionPage: Reports application runtime errors.
• UseExceptionHandler: Intercepts exceptions thrown by subsequent Middleware in the pipeline.
• UseHsts: Adds the Strict-Transport-Security header, forcing browsers to use HTTPS connections only.
• UseHttpsRedirection: Redirects HTTP requests to HTTPS.
• UseStaticFiles: Handles static file requests.
• UseRouting: Handles route resolution.
• UseAuthentication: Authenticates user identity.
• UseAuthorization: Authorizes users to access resources.
• UseSession: Handles session state.
• UseEndpoints: Adds endpoints to the request pipeline.

TIP

UseHsts and UseHttpsRedirection are both used to handle HTTPS; the former is executed on the browser side, while the latter is handled by server-side code.

Recommended Middleware Execution Order and Considerations

The following is the recommended registration order for Middleware. Please note that some Middleware have strict dependencies on order:

var app = builder.Build();

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

app.UseHttpsRedirection();

// When issues occur: When static files involve cross-origin access (CORS), culture characteristics (Localization), or compression caching.
// If CORS is required, UseStaticFiles must be placed after UseCors;
// If culture characteristics are involved, it must be placed after UseRequestLocalization;
// If compressed files need to be cached, it must be placed after UseResponseCompression and UseResponseCaching.
app.UseStaticFiles();
app.UseCookiePolicy();

// When issues occur: When rate limiting or route resolution is required.
// UseRouting must be placed before UseRateLimiter.
app.UseRouting();
app.UseRateLimiter();

// When issues occur: When handling multi-language or cross-origin requests.
// UseRequestLocalization must be before any Middleware that checks culture characteristics.
// UseCors must be placed after UseRouting and before UseAuthentication and UseResponseCaching.
app.UseRequestLocalization();
app.UseCors();

// When issues occur: When identity authentication and authorization are required.
// UseAuthentication must strictly be placed before UseAuthorization.
app.UseAuthentication();
app.UseAuthorization();

// When issues occur: When session state is required.
// Must be placed after UseCookiePolicy and before endpoint routing Middleware.
app.UseSession();

// When issues occur: When performance optimization is required.
// If cached compressed responses are needed, the order of these two can be adjusted.
app.UseResponseCompression();
app.UseResponseCaching();

// When issues occur: When requests are not correctly routed to Controllers or Pages.
// All Map methods related to endpoint routing must be placed at the very end of the pipeline.
app.MapRazorPages();
app.MapDefaultControllerRoute();

app.Run();

Change Log

• 2024-04-08 Initial version created.