ASP.NET Core oprogramowanie pośrednicząceASP.NET Core Middleware

Autorzy Rick Anderson i Steve SmithBy Rick Anderson and Steve Smith

Oprogramowanie pośredniczące jest oprogramowaniem, które jest połączone z potokiem aplikacji w celu obsługi żądań i odpowiedzi.Middleware is software that's assembled into an app pipeline to handle requests and responses. Każdy składnik:Each component:

  • Wybiera, czy żądanie ma zostać przekazane do następnego składnika w potoku.Chooses whether to pass the request to the next component in the pipeline.
  • Może wykonać prace przed i po następnym składniku potoku.Can perform work before and after the next component in the pipeline.

Delegaty żądań są używane do kompilowania potoku żądania.Request delegates are used to build the request pipeline. Delegaty żądań obsługują każde żądanie HTTP.The request delegates handle each HTTP request.

Delegatów żądań konfiguruje się za pomocą metod rozszerzenia Run, Map i Use.Request delegates are configured using Run, Map, and Use extension methods. Osobnego delegata żądania można określić jako metodę anonimową (nazywaną w wierszu) lub można ją zdefiniować w klasie wielokrotnego użytku.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. Te klasy wielokrotnego użytku i metody anonimowe w wierszu to oprogramowanie pośredniczące, nazywane również składnikami oprogramowania pośredniczącego.These reusable classes and in-line anonymous methods are middleware, also called middleware components. Każdy składnik pośredniczący w potoku żądania jest odpowiedzialny za wywoływanie następnego składnika w potoku lub krótkiego obwodu potoku.Each middleware component in the request pipeline is responsible for invoking the next component in the pipeline or short-circuiting the pipeline. W przypadku krótkiego obwodu oprogramowanie pośredniczące nosi nazwę oprogramowania pośredniczącego terminalu , ponieważ zapobiega przetwarzaniu żądania przez dalsze oprogramowanie pośredniczące.When a middleware short-circuits, it's called a terminal middleware because it prevents further middleware from processing the request.

Migrowanie programów obsługi i modułów HTTP do ASP.NET Core oprogramowania pośredniczącego wyjaśnia różnicę między potokami żądań w ASP.NET Core i ASP.NET 4. x i oferuje dodatkowe przykłady oprogramowania pośredniczącego.Migrowanie programów obsługi i modułów HTTP do ASP.NET Core oprogramowania pośredniczącego explains the difference between request pipelines in ASP.NET Core and ASP.NET 4.x and provides additional middleware samples.

Tworzenie potoku oprogramowania pośredniczącego za pomocą IApplicationBuilderCreate a middleware pipeline with IApplicationBuilder

Potok żądania ASP.NET Core składa się z sekwencji delegatów żądań o nazwie jeden po drugim.The ASP.NET Core request pipeline consists of a sequence of request delegates, called one after the other. Na poniższym diagramie przedstawiono koncepcję.The following diagram demonstrates the concept. Wątek wykonywania jest zgodny z czarnym strzałką.The thread of execution follows the black arrows.

Wzorzec przetwarzania żądań pokazujący żądanie docierające do, przetwarzania przez trzy middlewares i odpowiedzi opuszczających aplikację.

Każdy delegat może wykonać operacje przed i po następnym delegacie.Each delegate can perform operations before and after the next delegate. Delegaty obsługi wyjątków powinny być wywoływane wczesnie w potoku, dlatego mogą przechwytywać wyjątki, które występują w późniejszych etapach potoku.Exception-handling delegates should be called early in the pipeline, so they can catch exceptions that occur in later stages of the pipeline.

Najprostszym możliwym ASP.NET Core aplikacji jest skonfigurowanie pojedynczego delegata żądania, który obsługuje wszystkie żądania.The simplest possible ASP.NET Core app sets up a single request delegate that handles all requests. Ten przypadek nie obejmuje rzeczywistego potoku żądania.This case doesn't include an actual request pipeline. Zamiast tego funkcja pojedynczej anonimowej jest wywoływana w odpowiedzi na każde żądanie HTTP.Instead, a single anonymous function is called in response to every HTTP request.

public class Startup
{
    public void Configure(IApplicationBuilder app)
    {
        app.Run(async context =>
        {
            await context.Response.WriteAsync("Hello, World!");
        });
    }
}

Pierwszy delegat Run kończy potok.The first Run delegate terminates the pipeline.

Łączenie wielu delegatów żądań z Use.Chain multiple request delegates together with Use. @No__t-0 Parametr reprezentuje następny delegat w potoku.The next parameter represents the next delegate in the pipeline. Potok można skrócić, nie wywołując następnego parametru.You can short-circuit the pipeline by not calling the next parameter. Zazwyczaj można wykonywać akcje zarówno przed, jak i po następnym delegatze, jak pokazano w poniższym przykładzie:You can typically perform actions both before and after the next delegate, as the following example demonstrates:

public class Startup
{
    public void Configure(IApplicationBuilder app)
    {
        app.Use(async (context, next) =>
        {
            // Do work that doesn't write to the Response.
            await next.Invoke();
            // Do logging or other work that doesn't write to the Response.
        });

        app.Run(async context =>
        {
            await context.Response.WriteAsync("Hello from 2nd delegate.");
        });
    }
}

Gdy delegat nie przekazuje żądania do następnego delegata, jest on nazywany krótkim obwodem potoku żądania.When a delegate doesn't pass a request to the next delegate, it's called short-circuiting the request pipeline. Krótki obwód jest często pożądany, ponieważ pozwala uniknąć niepotrzebnej pracy.Short-circuiting is often desirable because it avoids unnecessary work. Na przykład statyczne oprogramowanie pośredniczące może działać jako oprogramowanie pośredniczące terminalu przez przetwarzanie żądania dla pliku statycznego i krótkiego obwodu pozostałej części potoku.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. Oprogramowanie pośredniczące dodane do potoku zanim oprogramowanie pośredniczące, które zakończy dalsze przetwarzanie, nadal przetwarza kod po instrukcji next.Invoke.Middleware added to the pipeline before the middleware that terminates further processing still processes code after their next.Invoke statements. Należy jednak zapoznać się z poniższym ostrzeżeniem dotyczącym próby zapisu do odpowiedzi, która została już wysłana.However, see the following warning about attempting to write to a response that has already been sent.

Ostrzeżenie

Nie wywołuj next.Invoke po wysłaniu odpowiedzi do klienta.Don't call next.Invoke after the response has been sent to the client. Zmiany w HttpResponse po rozpoczęciu zgłaszania wyjątku przez odpowiedź.Changes to HttpResponse after the response has started throw an exception. Na przykład zmiany, takie jak nagłówki ustawień i kod stanu zgłaszają wyjątek.For example, changes such as setting headers and a status code throw an exception. Zapis w treści odpowiedzi po wywołaniu next:Writing to the response body after calling next:

  • Może spowodować naruszenie protokołu.May cause a protocol violation. Na przykład pisanie więcej niż podane Content-Length.For example, writing more than the stated Content-Length.
  • Może uszkodzić format treści.May corrupt the body format. Na przykład, pisząc stopkę HTML do pliku CSS.For example, writing an HTML footer to a CSS file.

HasStarted jest przydatną wskazówką wskazującą, czy nagłówki zostały wysłane lub w których zapisano treść.HasStarted is a useful hint to indicate if headers have been sent or the body has been written to.

ZamówOrder

Kolejność, w jakiej składniki pośredniczące są dodawane w metodzie Startup.Configure definiuje kolejność, w jakiej składniki pośredniczące są wywoływane na żądaniach i odwrotnej kolejności odpowiedzi.The order that middleware components are added in the Startup.Configure method defines the order in which the middleware components are invoked on requests and the reverse order for the response. Kolejność ma kluczowe znaczenie dla bezpieczeństwa, wydajności i funkcjonalności.The order is critical for security, performance, and functionality.

Poniższa metoda Startup.Configure dodaje składniki pośredniczące dla typowych scenariuszy aplikacji:The following Startup.Configure method adds middleware components for common app scenarios:

  1. Obsługa wyjątków/błędówException/error handling
    • Gdy aplikacja jest uruchamiana w środowisku deweloperskim:When the app runs in the Development environment:
      • Oprogramowanie pośredniczące stron wyjątków dla deweloperów (UseDeveloperExceptionPage) zgłasza błędy środowiska uruchomieniowego aplikacji.Developer Exception Page Middleware (UseDeveloperExceptionPage) reports app runtime errors.
      • Strona błędu bazy danych raporty pośredniczące — błędy środowiska uruchomieniowego bazy danych.Database Error Page Middleware reports database runtime errors.
    • Gdy aplikacja jest uruchamiana w środowisku produkcyjnym:When the app runs in the Production environment:
      • Program obsługi wyjątków — oprogramowanie pośredniczące (UseExceptionHandler) przechwytuje wyjątki zgłoszone w następujących middlewares.Exception Handler Middleware (UseExceptionHandler) catches exceptions thrown in the following middlewares.
      • Oprogramowanie pośredniczące protokołu HTTP Strict Transport Security (HSTS) (UseHsts) dodaje nagłówek Strict-Transport-Security.HTTP Strict Transport Security Protocol (HSTS) Middleware (UseHsts) adds the Strict-Transport-Security header.
  2. Oprogramowanie pośredniczące przekierowania HTTPS (UseHttpsRedirection) przekierowuje żądania HTTP do protokołu HTTPS.HTTPS Redirection Middleware (UseHttpsRedirection) redirects HTTP requests to HTTPS.
  3. Oprogramowanie pośredniczące plików statycznych (UseStaticFiles) zwraca pliki statyczne i dalsze przetwarzanie żądań na krótkie obwody.Static File Middleware (UseStaticFiles) returns static files and short-circuits further request processing.
  4. Oprogramowanie pośredniczące zasad plików cookie (UseCookiePolicy) polega na tym, że aplikacja jest zgodna z przepisami Ogólne rozporządzenie o ochronie danych UE (Rodo).Cookie Policy Middleware (UseCookiePolicy) conforms the app to the EU General Data Protection Regulation (GDPR) regulations.
  5. Kierowanie oprogramowania pośredniczącego (UseRouting) do przesyłania żądań.Routing Middleware (UseRouting) to route requests.
  6. Oprogramowanie pośredniczące uwierzytelniania (UseAuthentication) próbuje uwierzytelnić użytkownika przed zezwoleniem na dostęp do zabezpieczonych zasobów.Authentication Middleware (UseAuthentication) attempts to authenticate the user before they're allowed access to secure resources.
  7. Oprogramowanie pośredniczące autoryzacji (UseAuthorization) autoryzuje użytkownika do uzyskiwania dostępu do zabezpieczonych zasobów.Authorization Middleware (UseAuthorization) authorizes a user to access secure resources.
  8. Oprogramowanie pośredniczące sesji (UseSession) ustanawia i utrzymuje stan sesji.Session Middleware (UseSession) establishes and maintains session state. Jeśli aplikacja używa stanu sesji, wywołaj oprogramowanie pośredniczące sesji po wyjściu z zasad plików cookie i przed oprogramowania MVC.If the app uses session state, call Session Middleware after Cookie Policy Middleware and before MVC Middleware.
  9. Oprogramowanie pośredniczące routingu punktu końcowego (UseEndpoints z MapRazorPages), aby dodać Razor Pages punkty końcowe do potoku żądania.Endpoint Routing Middleware (UseEndpoints with MapRazorPages) to add Razor Pages endpoints to the request pipeline.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
        app.UseDatabaseErrorPage();
    }
    else
    {
        app.UseExceptionHandler("/Error");
        app.UseHsts();
    }

    app.UseHttpsRedirection();
    app.UseStaticFiles();
    app.UseCookiePolicy();
    app.UseRouting();
    app.UseAuthentication();
    app.UseAuthorization();
    app.UseSession();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorPages();
    });
}

W powyższym przykładowym kodzie każda Metoda rozszerzenia oprogramowania pośredniczącego jest narażona na IApplicationBuilder za pomocą przestrzeni nazw Microsoft.AspNetCore.Builder.In the preceding example code, each middleware extension method is exposed on IApplicationBuilder through the Microsoft.AspNetCore.Builder namespace.

UseExceptionHandler to pierwszy składnik pośredniczący dodany do potoku.UseExceptionHandler is the first middleware component added to the pipeline. W związku z tym, oprogramowanie pośredniczące programu obsługi wyjątków przechwytuje wszystkie wyjątki występujące w późniejszych wywołaniach.Therefore, the Exception Handler Middleware catches any exceptions that occur in later calls.

Oprogramowanie pośredniczące plików statycznych jest wczesnie wywoływane w potoku, dzięki czemu może obsługiwać żądania i krótkie obwód bez przechodzenia przez pozostałe składniki.Static File Middleware is called early in the pipeline so that it can handle requests and short-circuit without going through the remaining components. Oprogramowanie pośredniczące plików statycznych nie zapewnia żadnych kontroli autoryzacji.The Static File Middleware provides no authorization checks. Wszystkie pliki obsługiwane przez oprogramowanie pośredniczące plików statycznych, w tym w katalogu wwwroot, są publicznie dostępne.Any files served by Static File Middleware, including those under wwwroot, are publicly available. Aby zapoznać się z podejściem do zabezpieczania plików statycznych, zobacz Pliki statyczne w ASP.NET Core.For an approach to secure static files, see Pliki statyczne w ASP.NET Core.

Jeśli żądanie nie jest obsługiwane przez oprogramowanie pośredniczące pliku statycznego, jest ono przesyłane do oprogramowania pośredniczącego uwierzytelniania (UseAuthentication), które wykonuje uwierzytelnianie.If the request isn't handled by the Static File Middleware, it's passed on to the Authentication Middleware (UseAuthentication), which performs authentication. Uwierzytelnianie nie ma krótkoterminowych żądań nieuwierzytelnionych.Authentication doesn't short-circuit unauthenticated requests. Chociaż uwierzytelnianie pośredniczące uwierzytelnia żądania, autoryzacja (i odrzucanie) występuje tylko po zaznaczeniu określonej strony Razor lub kontrolera MVC i akcji.Although Authentication Middleware authenticates requests, authorization (and rejection) occurs only after MVC selects a specific Razor Page or MVC controller and action.

Poniższy przykład ilustruje kolejność oprogramowania pośredniczącego, w którym żądania plików statycznych są obsługiwane przez oprogramowanie pośredniczące plików statycznych przed użyciem oprogramowania pośredniczącego kompresji.The following example demonstrates a middleware order where requests for static files are handled by Static File Middleware before Response Compression Middleware. Pliki statyczne nie są kompresowane z tą kolejnością oprogramowania.Static files aren't compressed with this middleware order. Razor Pages odpowiedzi można skompresować.The Razor Pages responses can be compressed.

public void Configure(IApplicationBuilder app)
{
    // Static files aren't compressed by Static File Middleware.
    app.UseStaticFiles();

    app.UseResponseCompression();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorPages();
    });
}
  1. Obsługa wyjątków/błędówException/error handling
    • Gdy aplikacja jest uruchamiana w środowisku deweloperskim:When the app runs in the Development environment:
      • Oprogramowanie pośredniczące stron wyjątków dla deweloperów (UseDeveloperExceptionPage) zgłasza błędy środowiska uruchomieniowego aplikacji.Developer Exception Page Middleware (UseDeveloperExceptionPage) reports app runtime errors.
      • Strona błędu bazy danych oprogramowanie pośredniczące (Microsoft.AspNetCore.Builder.DatabaseErrorPageExtensions.UseDatabaseErrorPage) raportuje błędy środowiska uruchomieniowego bazy danych.Database Error Page Middleware (Microsoft.AspNetCore.Builder.DatabaseErrorPageExtensions.UseDatabaseErrorPage) reports database runtime errors.
    • Gdy aplikacja jest uruchamiana w środowisku produkcyjnym:When the app runs in the Production environment:
      • Program obsługi wyjątków — oprogramowanie pośredniczące (UseExceptionHandler) przechwytuje wyjątki zgłoszone w następujących middlewares.Exception Handler Middleware (UseExceptionHandler) catches exceptions thrown in the following middlewares.
      • Oprogramowanie pośredniczące protokołu HTTP Strict Transport Security (HSTS) (UseHsts) dodaje nagłówek Strict-Transport-Security.HTTP Strict Transport Security Protocol (HSTS) Middleware (UseHsts) adds the Strict-Transport-Security header.
  2. Oprogramowanie pośredniczące przekierowania HTTPS (UseHttpsRedirection) przekierowuje żądania HTTP do protokołu HTTPS.HTTPS Redirection Middleware (UseHttpsRedirection) redirects HTTP requests to HTTPS.
  3. Oprogramowanie pośredniczące plików statycznych (UseStaticFiles) zwraca pliki statyczne i dalsze przetwarzanie żądań na krótkie obwody.Static File Middleware (UseStaticFiles) returns static files and short-circuits further request processing.
  4. Oprogramowanie pośredniczące zasad plików cookie (UseCookiePolicy) polega na tym, że aplikacja jest zgodna z przepisami Ogólne rozporządzenie o ochronie danych UE (Rodo).Cookie Policy Middleware (UseCookiePolicy) conforms the app to the EU General Data Protection Regulation (GDPR) regulations.
  5. Oprogramowanie pośredniczące uwierzytelniania (UseAuthentication) próbuje uwierzytelnić użytkownika przed zezwoleniem na dostęp do zabezpieczonych zasobów.Authentication Middleware (UseAuthentication) attempts to authenticate the user before they're allowed access to secure resources.
  6. Oprogramowanie pośredniczące sesji (UseSession) ustanawia i utrzymuje stan sesji.Session Middleware (UseSession) establishes and maintains session state. Jeśli aplikacja używa stanu sesji, wywołaj oprogramowanie pośredniczące sesji po wyjściu z zasad plików cookie i przed oprogramowania MVC.If the app uses session state, call Session Middleware after Cookie Policy Middleware and before MVC Middleware.
  7. MVC (UseMvc), aby dodać MVC do potoku żądania.MVC (UseMvc) to add MVC to the request pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
        app.UseDatabaseErrorPage();
    }
    else
    {
        app.UseExceptionHandler("/Error");
        app.UseHsts();
    }

    app.UseHttpsRedirection();
    app.UseStaticFiles();
    app.UseCookiePolicy();
    app.UseAuthentication();
    app.UseSession();
    app.UseMvc();
}

W powyższym przykładowym kodzie każda Metoda rozszerzenia oprogramowania pośredniczącego jest narażona na IApplicationBuilder za pomocą przestrzeni nazw Microsoft.AspNetCore.Builder.In the preceding example code, each middleware extension method is exposed on IApplicationBuilder through the Microsoft.AspNetCore.Builder namespace.

UseExceptionHandler to pierwszy składnik pośredniczący dodany do potoku.UseExceptionHandler is the first middleware component added to the pipeline. W związku z tym, oprogramowanie pośredniczące programu obsługi wyjątków przechwytuje wszystkie wyjątki występujące w późniejszych wywołaniach.Therefore, the Exception Handler Middleware catches any exceptions that occur in later calls.

Oprogramowanie pośredniczące plików statycznych jest wczesnie wywoływane w potoku, dzięki czemu może obsługiwać żądania i krótkie obwód bez przechodzenia przez pozostałe składniki.Static File Middleware is called early in the pipeline so that it can handle requests and short-circuit without going through the remaining components. Oprogramowanie pośredniczące plików statycznych nie zapewnia żadnych kontroli autoryzacji.The Static File Middleware provides no authorization checks. Wszystkie pliki obsługiwane przez oprogramowanie pośredniczące plików statycznych, w tym w katalogu wwwroot, są publicznie dostępne.Any files served by Static File Middleware, including those under wwwroot, are publicly available. Aby zapoznać się z podejściem do zabezpieczania plików statycznych, zobacz Pliki statyczne w ASP.NET Core.For an approach to secure static files, see Pliki statyczne w ASP.NET Core.

Jeśli żądanie nie jest obsługiwane przez oprogramowanie pośredniczące pliku statycznego, jest ono przesyłane do oprogramowania pośredniczącego uwierzytelniania (UseAuthentication), które wykonuje uwierzytelnianie.If the request isn't handled by the Static File Middleware, it's passed on to the Authentication Middleware (UseAuthentication), which performs authentication. Uwierzytelnianie nie ma krótkoterminowych żądań nieuwierzytelnionych.Authentication doesn't short-circuit unauthenticated requests. Chociaż uwierzytelnianie pośredniczące uwierzytelnia żądania, autoryzacja (i odrzucanie) występuje tylko po zaznaczeniu określonej strony Razor lub kontrolera MVC i akcji.Although Authentication Middleware authenticates requests, authorization (and rejection) occurs only after MVC selects a specific Razor Page or MVC controller and action.

Poniższy przykład ilustruje kolejność oprogramowania pośredniczącego, w którym żądania plików statycznych są obsługiwane przez oprogramowanie pośredniczące plików statycznych przed użyciem oprogramowania pośredniczącego kompresji.The following example demonstrates a middleware order where requests for static files are handled by Static File Middleware before Response Compression Middleware. Pliki statyczne nie są kompresowane z tą kolejnością oprogramowania.Static files aren't compressed with this middleware order. Odpowiedzi MVC z UseMvcWithDefaultRoute można skompresować.The MVC responses from UseMvcWithDefaultRoute can be compressed.

public void Configure(IApplicationBuilder app)
{
    // Static files aren't compressed by Static File Middleware.
    app.UseStaticFiles();

    app.UseResponseCompression();

    app.UseMvcWithDefaultRoute();
}

Używanie, uruchamianie i mapowanieUse, Run, and Map

Skonfiguruj potok HTTP przy użyciu Use, Run i Map.Configure the HTTP pipeline using Use, Run, and Map. Metoda Use może skrócić obwód rurociągu (oznacza to, że jeśli nie wywoła delegata żądania next).The Use method can short-circuit the pipeline (that is, if it doesn't call a next request delegate). Run jest konwencją, a niektóre składniki pośredniczące mogą uwidaczniać metody Run[Middleware], które są uruchamiane na końcu potoku.Run is a convention, and some middleware components may expose Run[Middleware] methods that run at the end of the pipeline.

rozszerzenia Map są używane jako konwencja rozgałęziania potoku.Map extensions are used as a convention for branching the pipeline. Map rozgałęzianie potoku żądań na podstawie dopasowań podanej ścieżki żądania.Map branches the request pipeline based on matches of the given request path. Jeśli ścieżka żądania rozpoczyna się od podaną ścieżką, rozgałęzienie jest wykonywane.If the request path starts with the given path, the branch is executed.

public class Startup
{
    private static void HandleMapTest1(IApplicationBuilder app)
    {
        app.Run(async context =>
        {
            await context.Response.WriteAsync("Map Test 1");
        });
    }

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

    public void Configure(IApplicationBuilder app)
    {
        app.Map("/map1", HandleMapTest1);

        app.Map("/map2", HandleMapTest2);

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

W poniższej tabeli przedstawiono żądania i odpowiedzi z http://localhost:1234 przy użyciu poprzedniego kodu.The following table shows the requests and responses from http://localhost:1234 using the previous code.

ProśbaRequest OdpowiedźResponse
localhost: 1234localhost:1234 Witaj od delegata innego niż mapowanie.Hello from non-Map delegate.
localhost: 1234/Map1localhost:1234/map1 Test mapy 1Map Test 1
localhost: 1234/MAP2 —localhost:1234/map2 Test mapy 2Map Test 2
localhost: 1234/map3 —localhost:1234/map3 Witaj od delegata innego niż mapowanie.Hello from non-Map delegate.

Gdy zostanie użyta Map, dopasowane segmenty ścieżki są usuwane z HttpRequest.Path i dołączane do HttpRequest.PathBase dla każdego żądania.When Map is used, the matched path segments are removed from HttpRequest.Path and appended to HttpRequest.PathBase for each request.

MapWhen oddziałuje potok żądania na podstawie wyniku danego predykatu.MapWhen branches the request pipeline based on the result of the given predicate. Dowolny predykat typu Func<HttpContext, bool> może służyć do mapowania żądań do nowej gałęzi potoku.Any predicate of type Func<HttpContext, bool> can be used to map requests to a new branch of the pipeline. W poniższym przykładzie predykat służy do wykrywania obecności zmiennej ciągu zapytania branch:In the following example, a predicate is used to detect the presence of a query string variable branch:

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

    public void Configure(IApplicationBuilder app)
    {
        app.MapWhen(context => context.Request.Query.ContainsKey("branch"),
                               HandleBranch);

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

W poniższej tabeli przedstawiono żądania i odpowiedzi z http://localhost:1234 przy użyciu poprzedniego kodu.The following table shows the requests and responses from http://localhost:1234 using the previous code.

ProśbaRequest OdpowiedźResponse
localhost: 1234localhost:1234 Witaj od delegata innego niż mapowanie.Hello from non-Map delegate.
localhost: 1234/? Branch = Masterlocalhost:1234/?branch=master Używane gałęzie = MasterBranch used = master

Map obsługuje zagnieżdżanie, na przykład:Map supports nesting, for example:

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

Map może również dopasować wiele segmentów jednocześnie:Map can also match multiple segments at once:

public class Startup
{
    private static void HandleMultiSeg(IApplicationBuilder app)
    {
        app.Run(async context =>
        {
            await context.Response.WriteAsync("Map multiple segments.");
        });
    }

    public void Configure(IApplicationBuilder app)
    {
        app.Map("/map1/seg1", HandleMultiSeg);

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

Wbudowane oprogramowanie pośrednicząceBuilt-in middleware

ASP.NET Core dostarcza z następującymi składnikami oprogramowania pośredniczącego.ASP.NET Core ships with the following middleware components. Kolumna Order zawiera uwagi dotyczące umieszczania oprogramowania pośredniczącego w potoku przetwarzania żądań i w ramach jakich warunków oprogramowanie pośredniczące może przerwać przetwarzanie żądań.The Order column provides notes on middleware placement in the request processing pipeline and under what conditions the middleware may terminate request processing. W przypadku krótkiego obwody przez oprogramowanie pośredniczące proces przetwarzania żądań i zapobiega przetwarzaniu żądania przez dalsze podrzędne oprogramowanie pośredniczące.When a middleware short-circuits the request processing pipeline and prevents further downstream middleware from processing a request, it's called a terminal middleware. Aby uzyskać więcej informacji na temat skracania obwodów, zobacz sekcję Tworzenie potoku oprogramowania pośredniczącego za pomocą IApplicationBuilder .For more information on short-circuiting, see the Create a middleware pipeline with IApplicationBuilder section.

Oprogramowania pośredniczącegoMiddleware OpisDescription ZamówOrder
UwierzytelnianieAuthentication Zapewnia obsługę uwierzytelniania.Provides authentication support. Przed HttpContext.User jest wymagana.Before HttpContext.User is needed. Terminal dla wywołań zwrotnych uwierzytelniania OAuth.Terminal for OAuth callbacks.
Zasady dotyczące plików cookieCookie Policy Śledzi zgodę użytkowników na przechowywanie informacji osobistych i wymusza minimalne standardy dotyczące pól plików cookie, takich jak secure i SameSite.Tracks consent from users for storing personal information and enforces minimum standards for cookie fields, such as secure and SameSite. Przed wystawianiem plików cookie przez oprogramowanie pośredniczące.Before middleware that issues cookies. Przykłady: uwierzytelnianie, sesja, MVC (TempData).Examples: Authentication, Session, MVC (TempData).
CORSCORS Konfiguruje udostępnianie zasobów między źródłami.Configures Cross-Origin Resource Sharing. Przed składnikami korzystającymi z mechanizmu CORS.Before components that use CORS.
DiagnostykaDiagnostics Kilka oddzielnych middlewares, które udostępniają stronę wyjątku dewelopera, obsługę wyjątków, strony kodu stanu i domyślną stronę sieci Web dla nowych aplikacji.Several separate middlewares that provide a developer exception page, exception handling, status code pages, and the default web page for new apps. Przed składnikami, które generują błędy.Before components that generate errors. Terminal dla wyjątków lub obsługa domyślnej strony sieci Web dla nowych aplikacji.Terminal for exceptions or serving the default web page for new apps.
Nagłówki przesłane dalejForwarded Headers Przekazuje nagłówki proxy do bieżącego żądania.Forwards proxied headers onto the current request. Przed składnikami, które zużywają zaktualizowane pola.Before components that consume the updated fields. Przykłady: schemat, host, adres IP klienta, metoda.Examples: scheme, host, client IP, method.
Sprawdzenie kondycjiHealth Check Sprawdza kondycję aplikacji ASP.NET Core i jej zależności, na przykład sprawdzanie dostępności bazy danych.Checks the health of an ASP.NET Core app and its dependencies, such as checking database availability. Terminal, jeśli żądanie pasuje do punktu końcowego sprawdzania kondycji.Terminal if a request matches a health check endpoint.
Zastąpienie metody HTTPHTTP Method Override Zezwala na przychodzące żądanie POST przesłaniające metodę.Allows an incoming POST request to override the method. Przed składnikami, które zużywają zaktualizowaną metodę.Before components that consume the updated method.
Przekierowanie HTTPSHTTPS Redirection Przekierowuj wszystkie żądania HTTP do protokołu HTTPS.Redirect all HTTP requests to HTTPS. Przed składnikami, które używają adresu URL.Before components that consume the URL.
Zabezpieczenia protokołu HTTP Strict Transport (HSTS)HTTP Strict Transport Security (HSTS) Ulepszanie zabezpieczeń oprogramowanie pośredniczące, które dodaje specjalny nagłówek odpowiedzi.Security enhancement middleware that adds a special response header. Przed wysłaniem odpowiedzi i po składnikach, które modyfikują żądania.Before responses are sent and after components that modify requests. Przykłady: nagłówki przesłane dalej, ponowne zapisywanie adresów URL.Examples: Forwarded Headers, URL Rewriting.
StandardMVC Przetwarza żądania przy użyciu MVC/Razor Pages.Processes requests with MVC/Razor Pages. Terminal, jeśli żądanie pasuje do trasy.Terminal if a request matches a route.
OWINOWIN Współdziałanie z aplikacjami opartymi na OWIN, serwerami i oprogramowanie pośredniczące.Interop with OWIN-based apps, servers, and middleware. Terminal, jeśli oprogramowanie OWIN w pełni przetwarza żądanie.Terminal if the OWIN Middleware fully processes the request.
Buforowanie odpowiedziResponse Caching Zapewnia obsługę buforowania odpowiedzi.Provides support for caching responses. Przed składnikami, które wymagają buforowania.Before components that require caching.
Kompresja odpowiedziResponse Compression Zapewnia obsługę kompresowania odpowiedzi.Provides support for compressing responses. Przed składnikami wymagającymi kompresji.Before components that require compression.
Lokalizacja żądaniaRequest Localization Zapewnia obsługę lokalizacji.Provides localization support. Przed uwzględnieniem poufnych składników lokalizacji.Before localization sensitive components.
Routing punktów końcowychEndpoint Routing Definiuje trasy żądań i ogranicza je.Defines and constrains request routes. Terminal dla pasujących tras.Terminal for matching routes.
ObradSession Zapewnia obsługę zarządzania sesjami użytkowników.Provides support for managing user sessions. Przed składnikami, które wymagają sesji.Before components that require Session.
Pliki statyczneStatic Files Zapewnia obsługę plików statycznych i przeglądania katalogów.Provides support for serving static files and directory browsing. Terminal, jeśli żądanie pasuje do pliku.Terminal if a request matches a file.
Ponowne zapisywanie adresów URLURL Rewrite Zapewnia obsługę ponownego zapisywania adresów URL i Przekierowywanie żądań.Provides support for rewriting URLs and redirecting requests. Przed składnikami, które używają adresu URL.Before components that consume the URL.
WebSocketsWebSockets Włącza protokół WebSockets.Enables the WebSockets protocol. Przed składnikami, które są wymagane do akceptowania żądań WebSocket.Before components that are required to accept WebSocket requests.

Zasoby dodatkoweAdditional resources