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.

Delegaty żądań są konfigurowane przy użyciu Run Map Use metod rozszerzających, i.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ącegoWyjaśnia różnicę między potokami żądań w ASP.NET Core i ASP.NET 4. x i udostępnia 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!");
        });
    }
}

Łączenie wielu delegatów żądań z Use .Chain multiple request delegates together with Use. nextParametr 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 przed oprogramowanie pośredniczące, które zakończy dalsze przetwarzanie, ciągle przetwarza kod po ich next.Invoke zestawie.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. HttpResponsePo rozpoczęciu zgłaszania wyjątku zmiany wprowadzone po odpowiedzi.Changes to HttpResponse after the response has started throw an exception. Na przykład ustawienie nagłówki i kod stanu zgłasza wyjątek.For example, setting headers and a status code throw an exception. Zapisywanie 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 zapisywanie 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.

HasStartedjest 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.

RunDelegaty nie odbierają next parametru.Run delegates don't receive a next parameter. Pierwszy Run delegat jest zawsze terminalem i kończy potok.The first Run delegate is always terminal and terminates the pipeline. Runjest konwencją.Run is a convention. Niektóre składniki pośredniczące mogą uwidaczniać Run[Middleware] metody, które są uruchamiane na końcu potoku:Some middleware components may expose Run[Middleware] methods that run at the end of the pipeline:

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.");
        });
    }
}

Jeśli chcesz zobaczyć Komentarze do kodu przetłumaczone na języki inne niż angielski, poinformuj nas o tym problemie z dyskusjąw witrynie GitHub.If you would like to see code comments translated to languages other than English, let us know in this GitHub discussion issue.

W poprzednim przykładzie Run Delegat zapisuje dane "Hello from 2nd delegate." do odpowiedzi, a następnie kończy potok.In the preceding example, the Run delegate writes "Hello from 2nd delegate." to the response and then terminates the pipeline. Jeśli Use Run po delegatze zostanie dodany inny obiekt lub delegat Run , nie jest on wywoływany.If another Use or Run delegate is added after the Run delegate, it's not called.

Zamówienie oprogramowania pośredniczącegoMiddleware order

Na poniższym diagramie przedstawiono potok przetwarzania kompletnego żądania dla ASP.NET Core aplikacji MVC i Razor Pages.The following diagram shows the complete request processing pipeline for ASP.NET Core MVC and Razor Pages apps. Możesz zobaczyć, jak w typowej aplikacji są uporządkowane istniejące middlewares i gdzie są dodawane niestandardowe middlewares.You can see how, in a typical app, existing middlewares are ordered and where custom middlewares are added. Masz pełną kontrolę nad tym, jak zmienić kolejność istniejących middlewares lub wstrzyknąć nowe niestandardowe middlewares w miarę potrzeb w scenariuszach.You have full control over how to reorder existing middlewares or inject new custom middlewares as necessary for your scenarios.

ASP.NET Core potok oprogramowania pośredniczącego

Oprogramowanie pośredniczące punktu końcowego na powyższym diagramie wykonuje potok filtru dla odpowiedniego typu aplikacji — MVC lub Razor strony.The Endpoint middleware in the preceding diagram executes the filter pipeline for the corresponding app type—MVC or Razor Pages.

Potok filtru ASP.NET Core

Kolejność, w jakiej składniki pośredniczące są dodawane w Startup.Configure metodzie, definiuje kolejność, w jakiej składniki oprogramowania pośredniczącego są wywoływane w żą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 Startup.Configure Metoda dodaje składniki pośredniczące związane z zabezpieczeniami w zalecanej kolejności:The following Startup.Configure method adds security-related middleware components in the recommended order:

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.UseRequestLocalization();
    // app.UseCors();

    app.UseAuthentication();
    app.UseAuthorization();
    // app.UseSession();
    // app.UseResponseCaching();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorPages();
        endpoints.MapControllerRoute(
            name: "default",
            pattern: "{controller=Home}/{action=Index}/{id?}");
    });
}

Powyższy kod ma następujące działanie:In the preceding code:

  • Oprogramowanie pośredniczące, które nie jest dodawane podczas tworzenia nowej aplikacji sieci Web z kontami poszczególnych użytkowników , jest oznaczone jako komentarz.Middleware that is not added when creating a new web app with individual users accounts is commented out.
  • Nie każde oprogramowanie pośredniczące musi przejść do tej dokładnej kolejności, ale wiele do.Not every middleware needs to go in this exact order, but many do. Przykład:For example:
    • UseCors, UseAuthentication i UseAuthorization muszą przejść w podanej kolejności.UseCors, UseAuthentication, and UseAuthorization must go in the order shown.
    • UseCorsobecnie musi przejść UseResponseCaching do tego błędu.UseCors currently must go before UseResponseCaching due to this bug.

Poniższa Startup.Configure Metoda 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 strony 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 ( UseExceptionHandler ) przechwytuje wyjątki zgłoszone w następujących middlewares.Exception Handler Middleware (UseExceptionHandler) catches exceptions thrown in the following middlewares.
      • Protokół pośredniczący protokołu HTTP Strict Transport Security (HSTS) ( UseHsts ) dodaje Strict-Transport-Security nagłówek.HTTP Strict Transport Security Protocol (HSTS) Middleware (UseHsts) adds the Strict-Transport-Security header.
  2. Oprogramowanie pośredniczące przekierowywania 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 ) powoduje, że aplikacja jest zgodna z przepisami ue ogólne rozporządzenie o ochronie danych (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 im 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. Program pośredniczący do routingu punktu końcowego ( UseEndpoints z MapRazorPages ) umożliwia dodawanie Razor punktów końcowych stron 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 poprzednim przykładowym kodzie każda Metoda rozszerzenia oprogramowania pośredniczącego jest udostępniana w IApplicationBuilder Microsoft.AspNetCore.Builder przestrzeni nazw.In the preceding example code, each middleware extension method is exposed on IApplicationBuilder through the Microsoft.AspNetCore.Builder namespace.

UseExceptionHandlerjest pierwszym składnikiem pośredniczącym dodanym 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 przez MVC określonego Razor kontrolera 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. RazorOdpowiedzi na strony 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();
    });
}

W przypadku aplikacji jednostronicowych (aplikacji jednostronicowych) oprogramowanie pośredniczące SPA UseSpaStaticFiles zazwyczaj jest ostatnim węzłem potoku oprogramowania pośredniczącego.For Single Page Applications (SPAs), the SPA middleware UseSpaStaticFiles usually comes last in the middleware pipeline. Oprogramowanie pośredniczące SPA jest ostatnie:The SPA middleware comes last:

  • Aby zezwolić wszystkim innym middlewares na odpowiadanie na pasujące żądania.To allow all other middlewares to respond to matching requests first.
  • Aby umożliwić uruchamianie aplikacji jednostronicowych z routingiem po stronie klienta dla wszystkich tras, które nie są rozpoznawane przez aplikację serwera.To allow SPAs with client-side routing to run for all routes that are unrecognized by the server app.

Aby uzyskać więcej informacji na temat aplikacji jednostronicowych, zobacz przewodniki dotyczące szablonów projektów reagowanie i kątowych .For more details on SPAs, see the guides for the React and Angular project templates.

Przekierowane nagłówki — zamówienie oprogramowaniaForwarded Headers Middleware order

Przekierowane nagłówki oprogramowanie pośredniczące powinno być uruchamiane przed innym programem pośredniczącym.Forwarded Headers Middleware should run before other middleware. Takie porządkowanie zapewnia, że oprogramowanie pośredniczące polegające na informacjach o przekazanych nagłówkach może zużywać wartości nagłówka do przetworzenia.This ordering ensures that the middleware relying on forwarded headers information can consume the header values for processing. Aby uruchomić przekazane nagłówki oprogramowania pośredniczącego po diagnostyki i obsłudze błędów oprogramowania pośredniczącego, zobacz kolejność wydawania w postaci nagłówków dalej.To run Forwarded Headers Middleware after diagnostics and error handling middleware, see Forwarded Headers Middleware order.

Rozgałęzianie potoku oprogramowania pośredniczącegoBranch the middleware pipeline

Maprozszerzenia są używane jako konwencja rozgałęziania potoku.Map extensions are used as a convention for branching the pipeline. Maprozgałęzienia potoku żądania 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 używania poprzedniego kodu.The following table shows the requests and responses from http://localhost:1234 using the previous code.

RequestRequest 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 Map jest używany, dopasowane segmenty ścieżki są usuwane z HttpRequest.Path i dodawane do HttpRequest.PathBase każdego żądania.When Map is used, the matched path segments are removed from HttpRequest.Path and appended to HttpRequest.PathBase for each request.

Mapobsł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
    });
});

Mapmożna 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.");
        });
    }
}

MapWhenrozgałęzienia potoku żą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 używania poprzedniego kodu:The following table shows the requests and responses from http://localhost:1234 using the previous code:

RequestRequest 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

UseWhenoddziałuje również potok żądania na podstawie wyniku danego predykatu.UseWhen also branches the request pipeline based on the result of the given predicate. W przeciwieństwie MapWhen do programu, gałąź ta jest ponownie przyłączona do głównego potoku, jeśli nie jest ona krótka lub nie zawiera terminalu pośredniczącego:Unlike with MapWhen, this branch is rejoined to the main pipeline if it doesn't short-circuit or contain a terminal middleware:

public class Startup
{
    private readonly ILogger<Startup> _logger;

    public Startup(ILogger<Startup> logger)
    {
        _logger = logger;
    }

    private void HandleBranchAndRejoin(IApplicationBuilder app)
    {
        app.Use(async (context, next) =>
        {
            var branchVer = context.Request.Query["branch"];
            _logger.LogInformation("Branch used = {branchVer}", branchVer);

            // Do work that doesn't write to the Response.
            await next();
            // Do other work that doesn't write to the Response.
        });
    }

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

        app.Run(async context =>
        {
            await context.Response.WriteAsync("Hello from main pipeline.");
        });
    }
}

W poprzednim przykładzie odpowiedź "Hello z głównego potoku".In the preceding example, a response of "Hello from main pipeline." jest zapisywana dla wszystkich żądań.is written for all requests. Jeśli żądanie zawiera zmienną ciągu zapytania branch , jej wartość jest rejestrowana przed ponownym przyłączeniem głównego potoku.If the request includes a query string variable branch, its value is logged before the main pipeline is rejoined.

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.

Oprogramowanie pośrednicząceMiddleware OpisDescription ZamówienieOrder
AuthenticationAuthentication Zapewnia obsługę uwierzytelniania.Provides authentication support. Przed zainstalowaniem HttpContext.User .Before HttpContext.User is needed. Terminal dla wywołań zwrotnych uwierzytelniania OAuth.Terminal for OAuth callbacks.
AutoryzacjaAuthorization Zapewnia obsługę autoryzacji.Provides authorization support. Natychmiast po oprogramowaniu pośredniczącym uwierzytelniania.Immediately after the Authentication Middleware.
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. UseCorsobecnie musi przejść UseResponseCaching do tego błędu.UseCors currently must go before UseResponseCaching due to this bug.
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.
Propagowanie nagłówkaHeader Propagation Propaguje nagłówki HTTP z przychodzącego żądania do wychodzących żądań klienta HTTP.Propagates HTTP headers from the incoming request to the outgoing HTTP Client requests.
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.
MVCMVC Przetwarza żądania ze 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. UseCORSmusi występować przed UseResponseCaching .UseCORS must come before UseResponseCaching.
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.
HASŁASPA Obsługuje wszystkie żądania z tego punktu w łańcuchu oprogramowania pośredniczącego, zwracając domyślną stronę aplikacji jednostronicowej (SPA)Handles all requests from this point in the middleware chain by returning the default page for the Single Page Application (SPA) Na koniec łańcucha, dzięki czemu inne oprogramowanie pośredniczące do obsługi plików statycznych, działania MVC itd., ma pierwszeństwo.Late in the chain, so that other middleware for serving static files, MVC actions, etc., takes precedence.
SesjaSession 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.
Protokoły WebSocketWebSockets 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

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.

Delegaty żądań są konfigurowane przy użyciu Run Map Use metod rozszerzających, i.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ącegoWyjaśnia różnicę między potokami żądań w ASP.NET Core i ASP.NET 4. x i udostępnia 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 Run Delegat kończy potok.The first Run delegate terminates the pipeline.

Łączenie wielu delegatów żądań z Use .Chain multiple request delegates together with Use. nextParametr 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 przed oprogramowanie pośredniczące, które zakończy dalsze przetwarzanie, ciągle przetwarza kod po ich next.Invoke zestawie.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. HttpResponsePo rozpoczęciu zgłaszania wyjątku zmiany wprowadzone po odpowiedzi.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. Zapisywanie 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 zapisywanie 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.

HasStartedjest 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ówienie oprogramowania pośredniczącegoMiddleware order

Kolejność, w jakiej składniki pośredniczące są dodawane w Startup.Configure metodzie, definiuje kolejność, w jakiej składniki oprogramowania pośredniczącego są wywoływane w żą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.

W poniższej Startup.Configure metodzie w zalecanej kolejności dodano składniki pośredniczące powiązane z zabezpieczeniami:The following Startup.Configure method adds security related middleware components in the recommended order:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
        app.UseDatabaseErrorPage();
    }
    else
    {
        app.UseExceptionHandler("/Home/Error");
        app.UseHsts();
    }

    app.UseHttpsRedirection();
    app.UseStaticFiles();
    app.UseCookiePolicy();

    // app.UseRequestLocalization();
    // app.UseCors();

    app.UseAuthentication();
    // app.UseSession();

    app.UseMvc(routes =>
    {
        routes.MapRoute(
            name: "default",
            template: "{controller=Home}/{action=Index}/{id?}");
    });
}

Powyższy kod ma następujące działanie:In the preceding code:

  • Oprogramowanie pośredniczące, które nie jest dodawane podczas tworzenia nowej aplikacji sieci Web z kontami poszczególnych użytkowników , jest oznaczone jako komentarz.Middleware that is not added when creating a new web app with individual users accounts is commented out.
  • Nie każde oprogramowanie pośredniczące musi przejść do tej dokładnej kolejności, ale wiele do.Not every middleware needs to go in this exact order, but many do. Na przykład, UseCors i UseAuthentication musi przejść w podanej kolejności.For example, UseCors and UseAuthentication must go in the order shown.

Poniższa Startup.Configure Metoda 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 strony 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 ( UseExceptionHandler ) przechwytuje wyjątki zgłoszone w następujących middlewares.Exception Handler Middleware (UseExceptionHandler) catches exceptions thrown in the following middlewares.
      • Protokół pośredniczący protokołu HTTP Strict Transport Security (HSTS) ( UseHsts ) dodaje Strict-Transport-Security nagłówek.HTTP Strict Transport Security Protocol (HSTS) Middleware (UseHsts) adds the Strict-Transport-Security header.
  2. Oprogramowanie pośredniczące przekierowywania 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 ) powoduje, że aplikacja jest zgodna z przepisami ue ogólne rozporządzenie o ochronie danych (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 im 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 poprzednim przykładowym kodzie każda Metoda rozszerzenia oprogramowania pośredniczącego jest udostępniana w IApplicationBuilder Microsoft.AspNetCore.Builder przestrzeni nazw.In the preceding example code, each middleware extension method is exposed on IApplicationBuilder through the Microsoft.AspNetCore.Builder namespace.

UseExceptionHandlerjest pierwszym składnikiem pośredniczącym dodanym 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 przez MVC określonego Razor kontrolera 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 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. UseMetoda może skrócić obwód rurociągu (oznacza to, że jeśli nie wywoła next delegata żądania).The Use method can short-circuit the pipeline (that is, if it doesn't call a next request delegate). Runjest konwencją, a niektóre składniki pośredniczące mogą uwidaczniać Run[Middleware] metody, 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.

Maprozszerzenia są używane jako konwencja rozgałęziania potoku.Map extensions are used as a convention for branching the pipeline. Maprozgałęzienia potoku żądania 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 używania poprzedniego kodu.The following table shows the requests and responses from http://localhost:1234 using the previous code.

RequestRequest 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 Map jest używany, dopasowane segmenty ścieżki są usuwane z HttpRequest.Path i dodawane do HttpRequest.PathBase każdego żądania.When Map is used, the matched path segments are removed from HttpRequest.Path and appended to HttpRequest.PathBase for each request.

MapWhenrozgałęzienia potoku żą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 używania poprzedniego kodu.The following table shows the requests and responses from http://localhost:1234 using the previous code.

RequestRequest 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

Mapobsł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
    });
});

Mapmożna 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.

Oprogramowanie pośrednicząceMiddleware OpisDescription ZamówienieOrder
AuthenticationAuthentication Zapewnia obsługę uwierzytelniania.Provides authentication support. Przed zainstalowaniem HttpContext.User .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.
MVCMVC Przetwarza żądania ze 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.
SesjaSession 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.
Protokoły WebSocketWebSockets 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.

Dodatkowe zasobyAdditional resources