ASP.NET Core Middleware

Middleware is software that's assembled into an app pipeline to handle requests and responses. Each middleware:

• Chooses whether to pass the request to the next middleware in the pipeline.
• Can perform work before and after the next middleware in the pipeline.

Request delegates are used to build the request pipeline. The request delegates handle each HTTP request.

Request delegates are configured using Run, Map, and Use extension methods. An individual request delegate can be specified inline as an anonymous method (called inline middleware) or defined in a reusable class. These inline anonymous methods or reusable classes are called middleware or middleware components. Each middleware in the request pipeline is responsible for invoking the next middleware in the pipeline or short-circuiting the pipeline. When a middleware short-circuits, it's called a terminal middleware because it prevents further middleware from processing the request.

For more information on the difference between request pipelines in ASP.NET Core and ASP.NET 4.x with additional middleware samples, see Migrate HTTP modules to ASP.NET Core middleware.

Role of middleware by app type

Server-side Blazor, Razor Pages, and MVC process browser requests on the server with middleware. The guidance in this article applies to these types of apps.

Standalone Blazor WebAssembly apps run entirely on the client and don't process requests with a middleware pipeline. The guidance in this article doesn't apply to standalone Blazor WebAssembly apps.

Middleware code analysis

For more information on ASP.NET Core's compiler platform analyzers that inspect app code for quality, see Code analysis in ASP.NET Core apps.

Create a middleware pipeline with WebApplication

The ASP.NET Core request pipeline consists of a sequence of request delegates, called one after the other. The following diagram demonstrates the concept. The thread of execution follows the black arrows.

Each delegate can perform operations before and after the next delegate. Exception-handling delegates should be called early in the pipeline, so they can catch exceptions that occur in later stages of the pipeline.

Note

To experiment locally with the code examples in this section, create an ASP.NET Core app using the ASP.NET Core Empty project template. If using the .NET CLI, the template short name is web (dotnet new web).

The simplest ASP.NET Core app calls Run to set up a single terminal middleware as an anonymous function request delegate to handle requests without a request pipeline.

In the following example:

• The call to RunExtensions.Run is invoked on every request and writes "Hello world!" to the response.
• The call to WebApplication.Run at the end of the code block runs the app and blocks the calling thread until host shutdown.

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.Run(async context =>
{
    await context.Response.WriteAsync("Hello world!");
});

app.Run();

Response when accessing the app in a browser at its launch URL:

Hello world!

Chain multiple request delegates together with Use. The next parameter represents the next delegate in the pipeline. You can typically perform actions both before and after the next delegate.

The following example demonstrates:

• Two Use calls, each writing to the console:
  • Where work can be performed that can write to the response (context.Response, HttpResponse).
  • Where work can be performed that doesn't write to the response after the next parameter is invoked.
• A terminal request delegate with a call to RunExtensions.Run that writes "Hello world!" to the response.
• A final Use call, which never executes because it follows the Run terminal request delegate.
• A call to WebApplication.Run at the end of the code block to run the app and block the calling thread until host shutdown.

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.Use(async (context, next) =>
{
    Console.WriteLine("Work that can write to the response. (1)");
    await next.Invoke(context);
    Console.WriteLine("Work that doesn't write to the response. (1)");
});

app.Use(async (context, next) =>
{
    Console.WriteLine("Work that can write to the response. (2)");
    await next.Invoke(context);
    Console.WriteLine("Work that doesn't write to the response. (2)");
});

app.Run(async context =>
{
    await context.Response.WriteAsync("Hello world!");
});

app.Use(async (context, next) =>
{
    Console.WriteLine("This statement isn't reached. (3)");
    await next.Invoke(context);
    Console.WriteLine("This statement isn't reached. (3)");
});

app.Run();

In the app's console window when the app is run:

Work that can write to the response. (1)
Work that can write to the response. (2)
Work that doesn't write to the response. (2)
Work that doesn't write to the response. (1)

Short-circuiting the request pipeline is often desirable because it avoids unnecessary work. For example, Static File Middleware can act as a terminal middleware by processing a request for a static file and short-circuiting the rest of the pipeline. Middleware added to the pipeline before the terminal middleware still processes code after their next.Invoke statements. If you don't plan to call next.Invoke because your goal is to terminate the pipeline, use a Run delegate instead of calling the Use extension method.

Don't call next.Invoke during or after the response is sent to the client. After an HttpResponse is started, changes result in an exception. For example, setting headers or a response status code throw an exception after the response starts. Writing to the response body after calling next may:

• Cause a protocol violation, such as writing more bytes to the response than the stated response's content length (Content-Length header value).
• Corrupt the body format, such as writing an HTML footer to a CSS file.

To determine if the response has started, check the value of HasStarted.

For more information, see Short-circuit middleware after routing.

Run delegate

A Run delegate doesn't receive a next parameter. The first Run delegate always terminates the pipeline. Run is also a convention, and some middleware may expose Run methods that execute at the end of the pipeline.

Any Use or Run delegates after the first Run delegate aren't called.

Branch the middleware pipeline

Map extensions are used as a convention to branch the request processing pipeline. Map branches the request pipeline based on matches of the given request path. If the request path starts with the given path, the branch is executed.

In the following example, HandleMap1 is called for requests to /map1, and HandleMap2 is called for requests to /map2:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.Map("/map1", HandleMap1);
app.Map("/map2", HandleMap2);

app.Run(async context =>
{
    await context.Response.WriteAsync("Hello from the non-Map delegate!");
});

app.Run();

private static void HandleMap1(IApplicationBuilder app)
{
    app.Run(async context =>
    {
        await context.Response.WriteAsync("Map 1");
    });
}

private static void HandleMap2(IApplicationBuilder app)
{
    app.Run(async context =>
    {
        await context.Response.WriteAsync("Map 2");
    });
}

The following table shows the requests and responses using the preceding code.

Request	Response
/	Hello from the non-Map delegate.
/map1	Map 1
/map2	Map 2
/map3	Hello from the non-Map delegate.

When Map is used, the matched path segments are removed from HttpRequest.Path and appended to HttpRequest.PathBase for each request.

Map can match multiple segments at once:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.Map("/map1/segment1", HandleMultipleSegments);

app.Run(async context =>
{
    await context.Response.WriteAsync("Hello from the non-Map delegate.");
});

app.Run();

private static void HandleMultipleSegments(IApplicationBuilder app)
{
    app.Run(async context =>
    {
        await context.Response.WriteAsync("Processing '/map1/segment1'");
    });
}

The following table shows the requests and responses using the preceding code.

Request	Response
/	Hello from the non-Map delegate.
/map1/segment1	Processing '/map1/segment1'

Map supports nesting:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.Map("/level1", level1App => {
    level1App.Map("/level2a", level2AApp => {
        app.Run(async context =>
        {
            await context.Response.WriteAsync("Processing '/level1/level2a'");
        });
    });
    level1App.Map("/level2b", level2BApp => {
        app.Run(async context =>
        {
            await context.Response.WriteAsync("Processing '/level1/level2b'");
        });
    });
});

app.Run(async context =>
{
    await context.Response.WriteAsync("Hello from the non-Map delegate!");
});

app.Run();

The following table shows the requests and responses using the preceding code.

Request	Response
/	Hello from the non-Map delegate.
/level1/level2a	Processing '/level1/level2a'
/level1/level2b	Processing '/level1/level2b'

MapWhen branches the request pipeline based on the result of the given predicate. Any predicate of type Func<HttpContext, bool> can be used to map requests to a new branch of the pipeline. In the following example, a predicate is used to detect the presence of a query string variable named "branch":

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapWhen(context => context.Request.Query.ContainsKey("branch"), HandleBranch);

app.Run(async context =>
{
    await context.Response.WriteAsync("Hello from the non-Map delegate.");
});

app.Run();

private static void HandleBranch(IApplicationBuilder app)
{
    app.Run(async context =>
    {
        var branchVer = context.Request.Query["branch"];
        await context.Response.WriteAsync($"Branch used = '{branchVer}'");
    });
}

The following table shows the requests and responses using the preceding code.

Request	Response
/	Hello from the non-Map delegate.
/?branch=main	Branch used = 'main'

UseWhen can branch the request pipeline based on the result of the given predicate. Unlike MapWhen, the branch is rejoined to the main pipeline if it doesn't contain a terminal middleware:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.UseWhen(context => context.Request.Query.ContainsKey("branch"),
    appBuilder => HandleBranchAndRejoin(appBuilder));

app.Run(async context =>
{
    await context.Response.WriteAsync("Hello from the non-Map delegate.");
});

app.Run();

void HandleBranchAndRejoin(IApplicationBuilder app)
{
    var logger = app.ApplicationServices.GetRequiredService<ILogger<Program>>(); 

    app.Use(async (context, next) =>
    {
        var branchVer = context.Request.Query["branch"];
        logger.LogInformation("Branch used = {branchVer}", branchVer.ToString());

        Console.WriteLine("Work that can write to the response.");
        await next.Invoke(context);
        Console.WriteLine("Work that doesn't write to the response.");
    });
}

In the preceding example, a response of "Hello from the non-Map delegate." is written for all requests. If the request includes a query string variable named "branch," its value is logged before the main pipeline is rejoined.

Middleware order

The order that middleware appears in the app's Program file defines the order in which middleware are invoked on a request with the reverse order for the response.

You have full control over the order of middleware and the ability to add custom middleware for request processing scenarios, keeping in mind that the order of middleware can be critical for security, performance, and functionality.

The following examples demonstrate middleware order for common app scenarios. Each middleware extension method is exposed on WebApplicationBuilder through the Microsoft.AspNetCore.Builder namespace:

1. Exception/error handling
   • When the app runs in the Development environment:
     • Developer Exception Page Middleware (UseDeveloperExceptionPage) reports app runtime errors.
     • Database Error Page Middleware (UseDatabaseErrorPage) reports database runtime errors.
   • When the app runs in the Production environment:
     • Exception Handler Middleware (UseExceptionHandler) catches exceptions thrown in the following middlewares.
     • HTTP Strict Transport Security Protocol (HSTS) Middleware (UseHsts) adds the Strict-Transport-Security header.
2. HTTPS Redirection Middleware (UseHttpsRedirection) redirects HTTP requests to HTTPS.
3. Static File Middleware (if required, UseStaticFiles) returns static files and short-circuits further request processing.
4. Cookie Policy Middleware (UseCookiePolicy) conforms the app to the EU General Data Protection Regulation (GDPR).
5. Routing Middleware (UseRouting) to route requests.
6. Authentication Middleware (UseAuthentication) attempts to authenticate the user before they're allowed access to secure resources.
7. Authorization Middleware (UseAuthorization) authorizes a user to access secure resources.
8. Antiforgery Middleware (UseAntiforgery) adds antiforgery middleware to the pipeline UseAntiforgery must be placed after calls to UseAuthentication and UseAuthorization.
9. Session Middleware (Razor Pages and MVC only, UseSession) establishes and maintains session state. If the app uses session state, call Session Middleware after Cookie Policy Middleware and before Razor Pages/MVC Middleware.
10. Endpoint Routing Middleware

• MapRazorComponents to add Razor component endpoints to the request pipeline.
• MapRazorPages to add Razor Pages endpoints to the request pipeline.
• MapControllerRoute to add controller endpoints to the request pipeline.

Typical Blazor Web App middleware pipeline:

app.UseWebAssemblyDebugging(); // Development environment with client-side rendering
app.UseMigrationsEndPoint(); // Development environment with ASP.NET Core Identity

app.UseExceptionHandler("/Error", createScopeForErrors: true); // Non-Development environment
app.UseHsts(); // Non-Development environment with HTTPS protocol

app.UseStatusCodePagesWithReExecute("/not-found", createScopeForStatusCodePages: true);

app.UseHttpsRedirection(); // With HTTPS protocol

app.UseAntiforgery();

app.MapStaticAssets();

app.MapRazorComponents<App>(); // With additional extension methods for render modes

app.MapAdditionalIdentityEndpoints(); // With ASP.NET Core Identity

app.Run();

Typical Razor Pages/MVC middleware pipeline:

app.UseMigrationsEndPoint(); // Development environment with ASP.NET Core Identity

app.UseExceptionHandler("/Error"); // Non-Development environment
app.UseHsts(); // Non-Development environment with HTTPS protocol

app.UseHttpsRedirection(); // With HTTPS protocol

// app.UseCookiePolicy();
app.UseRouting(); // If not called, runs at the beginning of the pipeline by default
// app.UseRateLimiter();
// app.UseRequestLocalization();
// app.UseCors();

// app.UseAuthentication(); // Called internally for ASP.NET Core Identity
app.UseAuthorization();
// app.UseSession();
// app.UseResponseCompression();
// app.UseResponseCaching();

app.MapStaticAssets();

app.MapControllerRoute(...); // For MVC controllers

app.MapRazorPages(); // For Razor Pages pages

app.MapControllers(); // With authentication in a Razor Pages app

app.Run();

In the preceding code:

• CORS Middleware (UseCors), Authentication Middleware (UseAuthentication), and Authorization Middleware (UseAuthorization) must appear in the order shown.
• CORS Middleware (UseCors) must appear before Response Caching Middleware (UseResponseCaching) to add CORS headers on every request, including cached responses. For more information, see It is not clear that UseCORS must come before UseResponseCaching (dotnet/aspnetcore #23218.
• Request Localization Middleware (UseRequestLocalization) must appear before any middleware that might check the request culture, for example, Static File Middleware (UseStaticFiles).
• Rate Limiting Middleware (UseRateLimiter) must be called after Routing Middleware (UseRouting) when rate limiting endpoint-specific APIs are used. For example, if the [EnableRateLimiting] attribute is used, Rate Limiting Middleware must be called after Routing Middleware. When calling only global limiters, Rate Limiting Middleware can be called before Routing Middleware.

In some scenarios, middleware has different ordering. For example, caching and compression ordering depends on the app's specification. In the following order, CPU usage might be reduced by caching the compressed response, but the app might end up caching multiple representations of a resource using different compression algorithms, such as Gzip or Brotli:

app.UseResponseCaching();
app.UseResponseCompression();

Static assets are typically served early in the pipeline so that the app can short-circuit request processing to improve performance.

Authentication doesn't short-circuit unauthenticated requests. Although Authentication Middleware authenticates requests, authorization occurs after the framework selects a Razor component in a Blazor Web App, a page in a Razor Pages app, or a controller and action in an MVC app.

For information about Single Page Applications, see the guides for the React and Angular project templates.

UseCors and UseStaticFiles order

For more information on ordering UseCors and UseStaticFiles, see Enable Cross-Origin Requests (CORS) in ASP.NET Core.

Forwarded Headers Middleware order

Run Forwarded Headers Middleware before other middleware to ensure that the middleware relying on forwarded headers information can consume the header values for processing. To run Forwarded Headers Middleware after Diagnostics and Error Handling Middleware, see Forwarded Headers Middleware order.

Built-in middleware

The latest release of ASP.NET Core ships with the following middleware. The UI stack column indicates the typical UI stack where the middleware is used [All, Blazor Web App (BWA), Razor Pages and MVC (RP/MVC)]. The Order column provides notes on middleware placement in the request processing pipeline and under what conditions the middleware may terminate request processing. When a middleware short-circuits the request processing pipeline and prevents further downstream middleware from processing a request, it's called a terminal middleware. For more information on short-circuiting, see the Create a middleware pipeline with WebApplication section.

Middleware	Description	UI stack	Order
Antiforgery	Provides anti-request-forgery support.	All	After authentication and authorization, before endpoints.
Authentication	Provides authentication support.	All	Before HttpContext.User is required. Terminal for OAuth callbacks.
Authorization	Provides authorization support.	All	Immediately after the Authentication Middleware.
Cookie Policy	Tracks consent from users for storing personal information and enforces minimum standards for cookie fields, such as secure and SameSite.	All	Before middleware that issues cookies. Examples: Authentication, Session, MVC (TempData).
CORS	Configures Cross-Origin Resource Sharing.	All	Before middleware that use CORS. UseCors must go before UseResponseCaching. For more information, see It is not clear that UseCORS must come before UseResponseCaching (dotnet/aspnetcore #23218.
Developer Exception Page	Generates a page with error information that is intended for use only in the Development environment.	All	Before middleware that generate errors. The project templates automatically register this middleware as the first middleware in the pipeline when the environment is Development.
Diagnostics	Several separate middlewares that provide a developer exception page, exception handling, status code pages, and the default web page for new apps.	All	Before middleware that generate errors. Terminal for exceptions or serving the default web page for new apps.
Forwarded Headers	Forwards proxied headers onto the current request.	All	Before middleware that consume the updated fields. Examples: scheme, host, client IP, method.
Health Check	Checks the health of an ASP.NET Core app and its dependencies, such as checking database availability.	All	Terminal if a request matches a health check endpoint.
Header Propagation	Propagates HTTP headers from the incoming request to the outgoing HTTP Client requests.
All
HTTP Logging	Logs HTTP Requests and Responses.	All	At the beginning of the middleware pipeline.
HTTP Method Override	Allows an incoming POST request to override the method.	All	Before middleware that consume the updated method.
HTTPS Redirection	Redirect all HTTP requests to HTTPS.	All	Before middleware that consume the URL.
HTTP Strict Transport Security (HSTS)	Security enhancement middleware that adds a special response header.	All	Before responses are sent and after middleware that modify requests. Examples: Forwarded Headers, URL Rewriting.
MVC	Processes requests with MVC/Razor Pages.	RP/MVC	Terminal if a request matches a route.
OWIN	Interop with OWIN-based apps, servers, and middleware.	RP/MVC	Terminal if the OWIN Middleware fully processes the request.
Output Caching	Provides support for caching responses based on configuration.	RP/MVC	Before middleware that require caching. UseRouting and UseCors must come before UseOutputCache.
Response Caching	Provides support for caching responses. This requires client participation to work. Use output caching for complete server control.	RP/MVC	Before middleware that require caching. UseCors must come before UseResponseCaching. Response caching isn't typically beneficial for UI apps, such as Razor Pages, because browsers generally set request headers that prevent caching. Output caching benefits UI apps.
Request Decompression	Provides support for decompressing requests.	All	Before middleware that read the request body.
Response Compression	Provides support for compressing responses.	All	Before middleware that require compression.
Request Localization	Provides localization support.	All	Before localization sensitive middleware. Must appear after Routing Middleware when using RouteDataRequestCultureProvider.
Request Timeouts	Provides support for configuring request timeouts, global and per endpoint.	All	UseRequestTimeouts must come after UseExceptionHandler, UseDeveloperExceptionPage, and UseRouting.
Endpoint Routing.	Defines and constrains request routes.	All	Terminal for matching routes.
SPA	Handles all requests from this point in the middleware chain by returning the default page for the Single Page Application (SPA).	All	Appears late in the pipeline, so other middleware for serving static files, such as MVC actions, take precedence.
Session	Provides support for managing user sessions.	RP/MVC	Before middleware that require Session.
Static File	Provides support for serving static files and directory browsing.	All	Terminal if a request matches a file.
URL Rewrite	Provides support for rewriting URLs and redirecting requests.	All	Before middleware that consume the URL.
W3C Logging	Generates server access logs in the W3C Extended Log File Format.	All	At the beginning of the middleware pipeline.
Blazor WebAssembly Debugging	Debugging Blazor Web Apps that adopt client-side rendering (CSR) inside Chromium developer tools.	BWA	At the beginning of the middleware pipeline.
WebSockets	Enables the WebSockets protocol.	All	Before middleware that are required to accept WebSocket requests.

Additional resources

• Lifetime and registration options (includes middleware sample)
• Write custom ASP.NET Core middleware
• Test ASP.NET Core middleware
• Configure gRPC-Web in ASP.NET Core
• Migrate HTTP modules to ASP.NET Core middleware
• App startup in ASP.NET Core
• Request Features in ASP.NET Core
• Factory-based middleware activation in ASP.NET Core
• Middleware activation with a third-party container in ASP.NET Core