daohualiuxiang
/
AspNetCore.Docs
mirror of https://github.com/dotnet/AspNetCore.Docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
AspNetCore.Docs/aspnetcore/fundamentals/middleware.md

14 KiB
Raw Blame History

title author description keywords ms.author manager ms.date ms.topic ms.assetid ms.technology ms.prod uid
ASP.NET Core Middleware | Microsoft Docs rick-anderson Explains middleware and the request pipeline. ASP.NET Core, Middleware, pipeline, delegate riande wpickett 02/14/2017 article db9a86ab-46c2-40e0-baed-86e38c16af1f aspnet aspnet-core fundamentals/middleware

ASP.NET Core Middleware Fundamentals

By Rick Anderson and Steve Smith

View or download sample code

What is middleware

Middleware are software components that are assembled into an application pipeline to handle requests and responses. Each component chooses whether to pass the request on to the next component in the pipeline, and can perform certain actions before and after the next component is invoked 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 on the IApplicationBuilder instance that is passed into the Configure method in the Startup class. An individual request delegate can be specified in-line as an anonymous method (called in-line middleware), or it can be defined in a reusable class. These reusable classes and in-line anonymous methods are middleware, or middleware components. Each middleware component in the request pipeline is responsible for invoking the next component in the pipeline, or short-circuiting the chain if appropriate.

Migrating HTTP Modules to Middleware explains the difference between request pipelines in ASP.NET Core and the previous versions and provides more middleware samples.

Creating a middleware pipeline with IApplicationBuilder

The ASP.NET Core request pipeline consists of a sequence of request delegates, called one after the next, as this diagram shows (the thread of execution follows the black arrows):

Request processing pattern showing a request arriving, processing through three middlewares, and the response leaving the application. Each middleware runs its logic and hands off the request to the next middleware at the next() statement. After the third middleware processes the request, it's handed back through the prior two middlewares for additional processing after the next() statements each in turn before leaving the application as a response to the client.

Each delegate has the opportunity to perform operations before and after the next delegate. A delegate can decide to not pass a request to the next delegate -- this is referred to as short-circuiting the request pipeline. Short-circuiting is often desirable because it allows unnecessary work to be avoided. For example, the static file middleware can return a request for a static file and short circuit the rest of the pipeline. Exception handling delegates need to be called early on in the pipeline, so they are able to catch exceptions that occur in later stages of the pipeline.

The simplest possible ASP.NET Core app sets up a single request delegate that handles all requests. In this case, there isn't really a request "pipeline", rather a single anonymous function that is called in response to every HTTP request.

[!code-csharpMain]

The first app.Run delegate terminates the pipeline.

You chain multiple request delegates together with app.Use. The next parameter represents the next delegate in the pipeline. You can terminate (short-circuit) the pipeline by not calling the next parameter. You can typically perform actions both before and after the next delegate, as this example demonstrates:

[!code-csharpMain]

[!WARNING] Be careful modifying the HttpResponse after invoking next, as the response may have already been sent to the client. HttpResponse.HasStarted can be used to check if the headers have been sent yet.

[!WARNING] Do not call next.Invoke after calling a write method. A middleware should produce a response or call next.Invoke, not both.

Ordering

The order middleware components are added in the Configure method is the order in which they are invoked on requests, and the reverse order for the response. This ordering is critical for security, performance, and functionality.

The Configure method (shown below) adds the following middleware components:

  1. Exception/error handling
  2. Static file server
  3. Authentication
  4. MVC
public void Configure(IApplicationBuilder app)
{
    app.UseExceptionHandler("/Home/Error"); // Call first to catch exceptions
                                            // thrown in the following middleware.

    app.UseStaticFiles();                   // Return static files and end pipeline.

    app.UseIdentity();                     // Authenticate before you access
                                           // secure resources.

    app.UseMvcWithDefaultRoute();          // Add MVC to the request pipeline.
}

In the code above, UseExceptionHandler is the first middleware added to the pipeline -- therefore it will catch any exceptions that occur in later calls.

The static file middleware is called early in the pipeline so it can handle requests and short circuit without going through the remaining components. The static file middleware provides no authorization checks. Any files served by it, including those under wwwroot are publicly available. See Working with static files for an approach to secure static files.

If the request is not handled by the static file middleware, it's passed on to the Identity middleware (app.UseIdentity), which performs authentication. Identity does not short circuit unauthenticated requests. Identity authenticates requests, but authorization (and rejection) does not happen until after MVC selects a specific controller and action.

The following example demonstrates a middleware ordering where requests for static files are handled by the static file middleware before the response compression middleware. Static files are not compressed with this ordering of the middleware. The MVC responses from UseMvcWithDefaultRoute can be compressed.

public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles();         // Static files not compressed
                                  // by middleware.
    app.UseResponseCompression();
    app.UseMvcWithDefaultRoute();
}

Run, Map, and Use

You configure the HTTP pipeline using Run, Map, and Use. The Run method short circuits the pipeline (that is, it will not call a next request delegate). Run is a convention, and some middleware components may expose Run[Middleware] methods that run at the end of the pipeline.

Map* extensions are used as a convention for branching the 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.

[!code-csharpMain]

The following table shows the requests and responses from http://localhost:1234 using the code above:

Request Response
localhost:1234 Hello from non-Map delegate.
localhost:1234/map1 Map Test 1
localhost:1234/map2 Map Test 2
localhost:1234/map3 Hello from non-Map delegate.

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

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 branch:

[!code-csharpMain]

The following table shows the requests and responses from http://localhost:1234 using the code above:

Request Response
localhost:1234 Hello from non-Map delegate.
localhost:1234/?branch=master Branch used = master

Map supports nesting, for example:

app.Map("/level1", level1App => {
       level1App.Map("/level2a", level2AApp => {
           // "/level1/level2a"
           //...
       });
       level1App.Map("/level2b", level2BApp => {
           // "/level1/level2b"
           //...
       });
   });

Map can also match multiple segments at once, for example:

app.Map("/level1/level2", HandleMultiSeg);

Built-in middleware

ASP.NET Core ships with the following middleware components:

Middleware Description
Authentication Provides authentication support.
CORS Configures Cross-Origin Resource Sharing.
Response Caching Provides support for caching responses.
Response Compression Provides support for compressing responses.
Routing Defines and constrains request routes.
Session Provides support for managing user sessions.
Static Files Provides support for serving static files and directory browsing.
URL Rewriting Middleware Provides support for rewriting URLs and redirecting requests.

Writing middleware

Middleware is generally encapsulated in a class and exposed with an extension method. Consider the following middleware, which sets the culture for the current request from the query string:

[!code-csharpMain]

Note: The sample code above is used to demonstrate creating a middleware component. See Globalization and localization for ASP.NET Core's built-in localization support.

You can test the middleware by passing in the culture, for example http://localhost:7997/?culture=no.

The following code moves the middleware delegate to a class:

[!code-csharpMain]

The following extension method exposes the middleware through IApplicationBuilder:

[!code-csharpMain]

The following code calls the middleware from Configure:

[!code-csharpMain]

Middleware should follow the Explicit Dependencies Principle by exposing its dependencies in its constructor. Middleware is constructed once per application lifetime. See Per-request dependencies below if you need to share services with middleware within a request.

Middleware can resolve their dependencies from dependency injection through constructor parameters. UseMiddleware<T> can also accept additional parameters directly.

Per-request dependencies

Because middleware are constructed at app startup, not per-request, scoped lifetime services used by middleware constructors will not be shared with other dependency-injected types during each request. If you need to share a scoped service between your middleware and other types, you should add these services to the Invoke method's signature. The Invoke method can accept additional parameters that will be populated by dependency injection. For example:

public class MyMiddleware
{
    private readonly RequestDelegate _next;

    public MyMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task Invoke(HttpContext httpContext, IMyScopedService svc)
    {
        svc.MyProperty = 1000;
        await _next(httpContext);
    }
}

Resources