ASP.NET Core-MiddlewareASP.NET Core Middleware

Von Rick Anderson und Steve SmithBy Rick Anderson and Steve Smith

Middleware ist Software, die zu einer Anwendungspipeline zusammengesetzt wird, um Anforderungen und Antworten zu verarbeiten.Middleware is software that's assembled into an app pipeline to handle requests and responses. Jede Komponente kann Folgendes ausführen:Each component:

  • Entscheiden, ob die Anforderung an die nächste Komponente in der Pipeline übergeben werden soll.Chooses whether to pass the request to the next component in the pipeline.
  • Ausführen von Arbeiten, bevor oder nachdem die nächste Komponente in der Pipeline aufgerufen wird.Can perform work before and after the next component in the pipeline.

Anforderungsdelegaten werden verwendet, um die Anforderungspipeline zu erstellen.Request delegates are used to build the request pipeline. Die Anforderungsdelegaten behandeln jede HTTP-Anforderung.The request delegates handle each HTTP request.

Anforderungsdelegaten werden mit den Erweiterungsmethoden Run, Map und Use konfiguriert.Request delegates are configured using Run, Map, and Use extension methods. Ein einzelner Anforderungsdelegat kann inline als anonyme Methode angegeben werden (sogenannte Inline-Middleware), oder er kann in einer wiederverwendbaren Klasse definiert werden.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. Diese wiederverwendbaren Klassen und anonymen Inline-Methoden sind Middleware bzw. Middlewarekomponenten.These reusable classes and in-line anonymous methods are middleware, also called middleware components. Jede Middlewarekomponente in der Anforderungspipeline ist für das Aufrufen der jeweils nächsten Komponente in der Pipeline oder, wenn nötig, für das Kurzschließen der Pipeline zuständig.Each middleware component in the request pipeline is responsible for invoking the next component in the pipeline or short-circuiting the pipeline. Wenn eine Middleware einen Kurzschluss verursacht, wird diese als Terminalmiddleware bezeichnet, da sie verhindert, dass weitere Middleware die Anforderung verarbeiten kann.When a middleware short-circuits, it's called a terminal middleware because it prevents further middleware from processing the request.

Unter Migrieren von HTTP-Handlern und Modulen zu ASP.net Core Middleware wird der Unterschied zwischen Anforderungspipelines in ASP.NET Core und ASP.NET 4.x erklärt. Außerdem werden dort zusätzliche Beispiele für Middleware bereitgestellt.Migrieren von HTTP-Handlern und Modulen zu ASP.net Core Middleware explains the difference between request pipelines in ASP.NET Core and ASP.NET 4.x and provides additional middleware samples.

Erstellen einer Middlewarepipeline mit IApplicationBuilderCreate a middleware pipeline with IApplicationBuilder

Die ASP.NET Core-Anforderungspipeline besteht aus einer Sequenz von Anforderungsdelegaten, die nacheinander aufgerufen werden.The ASP.NET Core request pipeline consists of a sequence of request delegates, called one after the other. Das Konzept wird im folgenden Diagramm veranschaulicht.The following diagram demonstrates the concept. Der Ausführungsthread folgt den schwarzen Pfeilen.The thread of execution follows the black arrows.

Anforderungsverarbeitungsmuster mit eingehender Anforderung, deren Verarbeitung von drei Middlewares und die ausgehende Antwort der Anwendung.

Jeder Delegat kann Vorgänge vor und nach dem nächsten Delegaten ausführen.Each delegate can perform operations before and after the next delegate. Die Ausnahmebehandlungsdelegaten müssen am Anfang der Pipeline aufgerufen werden, sodass sie Ausnahmen abfangen können, die zu einem späteren Zeitpunkt in der Pipeline ausgelöst werden.Exception-handling delegates should be called early in the pipeline, so they can catch exceptions that occur in later stages of the pipeline.

Die einfachste mögliche ASP.NET Core-App enthält einen einzigen Anforderungsdelegaten, der alle Anforderungen verarbeitet.The simplest possible ASP.NET Core app sets up a single request delegate that handles all requests. In diesem Fall ist keine tatsächliche Anforderungspipeline vorhanden.This case doesn't include an actual request pipeline. Stattdessen wird eine einzelne anonyme Funktion als Antwort auf jede HTTP-Anforderung aufgerufen.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!");
        });
    }
}

Mit Use können Sie mehrere Anforderungedelegate miteinander verknüpfen.Chain multiple request delegates together with Use. Der Parameter next steht für den nächsten Delegaten in der Pipeline.The next parameter represents the next delegate in the pipeline. Sie können die Pipeline kurzschließen, indem Sie den Parameter next nicht aufrufen.You can short-circuit the pipeline by not calling the next parameter. Normalerweise können Sie Aktionen sowohl vor als auch nach dem nächsten Delegaten durchführen. Dies wird in folgendem Beispiel veranschaulicht: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.");
        });
    }
}

Wenn ein keine Anforderung an den nächsten Delegaten übergibt, wird dies als Kurzschluss der Anforderungspipeline bezeichnet.When a delegate doesn't pass a request to the next delegate, it's called short-circuiting the request pipeline. Das Kurzschließen ist oft sinnvoll, da es unnötige Arbeit verhindert.Short-circuiting is often desirable because it avoids unnecessary work. Die Middleware für statische Dateien kann beispielsweise als Terminalmiddleware fungieren, indem sie eine Anforderung für eine statische Datei zurückgibt und den Rest der Pipeline kurzschließt.For example, Static File Middleware can act as a terminal middleware by processing a request for a static file and short-circuiting the rest of the pipeline. Middleware, die noch vor der Middleware, die die weitere Verarbeitung beendet, zur Pipeline hinzugefügt wird, verarbeitet Code noch nach den next.Invoke-Anweisungen weiter.Middleware added to the pipeline before the middleware that terminates further processing still processes code after their next.Invoke statements. Sehen Sie sich allerdings die folgende Warnung zum Versuch an, in eine Antwort zu schreiben, die bereits gesendet wurde.However, see the following warning about attempting to write to a response that has already been sent.

Warnung

Rufen Sie next.Invoke nicht auf, nachdem die Antwort an den Client gesendet wurde.Don't call next.Invoke after the response has been sent to the client. An HttpResponse vorgenommene Änderungen lösen nach dem Start der Antwort eine Ausnahme aus.Changes to HttpResponse after the response has started throw an exception. Das Festlegen von Headern und einem Statuscode lösen beispielsweise eine Ausnahme aus.For example, setting headers and a status code throw an exception. Wenn Sie nach dem Aufruf von next in den Antworttext schreiben, kann dies:Writing to the response body after calling next:

  • einen Protokollverstoß verursachen,May cause a protocol violation. wenn Sie z.B. mehr als das genannte Content-Length-Objekt schreiben.For example, writing more than the stated Content-Length.
  • Fehler im Textformat auslösen,May corrupt the body format. wenn Sie z.B. eine HTML-Fußzeile in eine CSS-Datei schreiben.For example, writing an HTML footer to a CSS file.

HasStarted ist ein nützlicher Hinweis, der angibt, ob Header gesendet wurden oder ob in den Text geschrieben wurde.HasStarted is a useful hint to indicate if headers have been sent or the body has been written to.

Run-Delegaten erhalten keinen next-Parameter.Run delegates don't receive a next parameter. Der erste Run-Delegat beendet immer die Pipeline.The first Run delegate is always terminal and terminates the pipeline. Run ist eine Konvention.Run is a convention. Einige Middlewarekomponenten machen möglicherweise Run[Middleware]-Methoden verfügbar, die am Ende einer Pipeline ausgeführt werden: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.");
        });
    }
}

Wenn Sie möchten, dass Codekommentare in anderen Sprachen als Englisch angezeigt werden, informieren Sie uns in diesem GitHub-Issue.If you would like to see code comments translated to languages other than English, let us know in this GitHub discussion issue.

Im vorherigen Beispiel schreibt der Run-Delegat "Hello from 2nd delegate." zur Antwort und beendet dann die Pipeline.In the preceding example, the Run delegate writes "Hello from 2nd delegate." to the response and then terminates the pipeline. Wenn ein anderer Use- oder Run-Delegat nach dem Run-Delegaten hinzugefügt wird, wird dieser nicht aufgerufen.If another Use or Run delegate is added after the Run delegate, it's not called.

MiddlewarereihenfolgeMiddleware order

In der folgenden Abbildung wird die gesamte Anforderungsverarbeitungspipeline für MVC- und Razor Pages-Apps in ASP.NET Core dargestellt.The following diagram shows the complete request processing pipeline for ASP.NET Core MVC and Razor Pages apps. Es ist zu sehen, wie vorhandene Middleware in einer typischen App sortiert ist und an welcher Stelle benutzerdefinierte Middleware hinzugefügt wird.You can see how, in a typical app, existing middlewares are ordered and where custom middlewares are added. Sie haben vollständige Kontrolle darüber, wie vorhandene Middleware neu angeordnet oder neue benutzerdefinierte Middleware nach Bedarf eingefügt wird.You have full control over how to reorder existing middlewares or inject new custom middlewares as necessary for your scenarios.

ASP.NET Core-Middlewarepipeline

Der Endpunktmiddleware in der vorangehenden Abbildung führt die Filterpipeline für den entsprechenden App-Typ aus (MVC oder Razor Pages).The Endpoint middleware in the preceding diagram executes the filter pipeline for the corresponding app type—MVC or Razor Pages.

ASP.NET Core-Filterpipeline

Die Reihenfolge, in der Middlewarekomponenten in der Startup.Configure-Methode hinzugefügt werden, legt die Reihenfolge fest, in der die Middlewarekomponenten bei Anforderungen aufgerufen werden. Bei Antworten gilt die umgekehrte Reihenfolge.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. Die Reihenfolge ist in Bezug auf Sicherheit, Leistung und Funktionalität entscheidend.The order is critical for security, performance, and functionality.

Die folgende Startup.Configure-Methode fügt sicherheitsbezogene Middlewarekomponenten in der empfohlenen Reihenfolge hinzu: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?}");
    });
}

Für den Code oben gilt:In the preceding code:

  • Middleware, die beim Erstellen einer neuen Web-App mit einzelnen Benutzerkonten nicht hinzugefügt wird, wird auskommentiert.Middleware that is not added when creating a new web app with individual users accounts is commented out.
  • Nicht jede Middleware muss in genau dieser Reihenfolge vorliegen, aber für viele Middlewarekomponenten ist dies erforderlich.Not every middleware needs to go in this exact order, but many do. Zum Beispiel:For example:
    • UseCors, UseAuthentication und UseAuthorization müssen in der gezeigten Reihenfolge vorliegen.UseCors, UseAuthentication, and UseAuthorization must go in the order shown.
    • UseCors muss sich derzeit aufgrund dieses Fehlers vor UseResponseCaching befinden.UseCors currently must go before UseResponseCaching due to this bug.

Die folgenden Startup.Configure-Methode fügt Middlewarekomponenten für allgemeine App-Szenarien hinzu:The following Startup.Configure method adds middleware components for common app scenarios:

  1. Ausnahme-/FehlerbehandlungException/error handling
    • Bei Ausführung der App in der Entwicklungsumgebung:When the app runs in the Development environment:
      • Middleware der Seite mit Ausnahmen für Entwickler (UseDeveloperExceptionPage) meldet App-Laufzeitfehler.Developer Exception Page Middleware (UseDeveloperExceptionPage) reports app runtime errors.
      • Middleware der Seite mit Datenbankfehlern meldet Datenbanklaufzeitfehler.Database Error Page Middleware reports database runtime errors.
    • Bei Ausführung der App in der Produktionsumgebung:When the app runs in the Production environment:
      • Middleware für Ausnahmehandler (UseExceptionHandler) fängt Ausnahmen ab, die in den folgenden Middlewarekomponenten ausgelöst werden.Exception Handler Middleware (UseExceptionHandler) catches exceptions thrown in the following middlewares.
      • HTTP Strict Transport Security Protocol-Middleware (HSTS) (UseHsts) fügt den Strict-Transport-Security-Header hinzu.HTTP Strict Transport Security Protocol (HSTS) Middleware (UseHsts) adds the Strict-Transport-Security header.
  2. Middleware zur HTTPS-Umleitung (UseHttpsRedirection) leitet HTTP-Anforderungen an HTTPS um.HTTPS Redirection Middleware (UseHttpsRedirection) redirects HTTP requests to HTTPS.
  3. Middleware für statische Dateien (UseStaticFiles) gibt statische Dateien zurück und umgeht die weitere Anforderungsverarbeitung.Static File Middleware (UseStaticFiles) returns static files and short-circuits further request processing.
  4. Middleware für Cookierichtlinien (UseCookiePolicy) sorgt dafür, dass die App die Anforderungen der europäischen Datenschutzgrundverordnung (DSGVO) erfüllt.Cookie Policy Middleware (UseCookiePolicy) conforms the app to the EU General Data Protection Regulation (GDPR) regulations.
  5. Routingmiddleware (UseRouting) zum Weiterleiten von Anforderungen.Routing Middleware (UseRouting) to route requests.
  6. Middleware für die Authentifizierung (UseAuthentication) versucht, den Benutzer zu authentifizieren, bevor der Zugriff auf sichere Ressourcen zugelassen wird.Authentication Middleware (UseAuthentication) attempts to authenticate the user before they're allowed access to secure resources.
  7. Autorisierungsmiddleware (UseAuthorization) wird zum Autorisieren des Zugriffs auf sichere Ressourcen eines Benutzers verwendet.Authorization Middleware (UseAuthorization) authorizes a user to access secure resources.
  8. Middleware für Sitzungen (UseSession) richtet einen Sitzungsstatus ein und erhält diesen aufrecht.Session Middleware (UseSession) establishes and maintains session state. Wenn die App den Sitzungsstatus verwendet, rufen Sie die Middleware für Sitzungen nach der Middleware für Cookierichtlinien und vor der MVC-Middleware auf.If the app uses session state, call Session Middleware after Cookie Policy Middleware and before MVC Middleware.
  9. Endpunktroutingmiddleware (UseEndpoints mit MapRazorPages) zum Hinzufügen von Razor Pages-Endpunkten zur Anforderungspipeline.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();
    });
}

Im vorhergehenden Beispielcode wird jede Middleware-Erweiterungsmethode in IApplicationBuilder über den Microsoft.AspNetCore.Builder-Namespace verfügbar gemacht.In the preceding example code, each middleware extension method is exposed on IApplicationBuilder through the Microsoft.AspNetCore.Builder namespace.

UseExceptionHandler ist die erste Middlewarekomponente, die der Pipeline hinzugefügt wird.UseExceptionHandler is the first middleware component added to the pipeline. Aus diesem Grund fängt die Middleware für den Ausnahmehandler alle Ausnahmen ab, die in späteren Aufrufen auftreten.Therefore, the Exception Handler Middleware catches any exceptions that occur in later calls.

Die Middleware für statische Dateien wird am Anfang der Pipeline aufgerufen, damit sie Anforderungen und Kurzschlüsse verarbeiten kann, ohne dass die verbleibenden Komponenten durchlaufen werden müssen.Static File Middleware is called early in the pipeline so that it can handle requests and short-circuit without going through the remaining components. Die Middleware für statische Dateien stellt keine Autorisierungsüberprüfungen bereit.The Static File Middleware provides no authorization checks. Alle Dateien, die von Middleware für statische Dateien unterstützt werden, einschließlich der Dateien unter wwwroot, sind öffentlich verfügbar.Any files served by Static File Middleware, including those under wwwroot, are publicly available. Informationen zum Sichern statischer Dateien finden Sie unter Statische Dateien in ASP.NET Core.For an approach to secure static files, see Statische Dateien in ASP.NET Core.

Wenn die Anforderung nicht von der Middleware für statische Dateien verarbeitet wird, wird sie an die Authentifizierungsmiddleware (UseAuthentication) übergeben, welche die Authentifizierung durchführt.If the request isn't handled by the Static File Middleware, it's passed on to the Authentication Middleware (UseAuthentication), which performs authentication. Die Authentifizierung schließt nicht authentifizierte Anforderungen nicht kurz.Authentication doesn't short-circuit unauthenticated requests. Auch wenn die Authentifizierungsmiddleware Anforderungen authentifiziert, erfolgt die Autorisierung (und Ablehnung) erst dann, wenn MVC eine spezifische Razor Page oder einen MVC-Controller und eine Aktion ausgewählt hat.Although Authentication Middleware authenticates requests, authorization (and rejection) occurs only after MVC selects a specific Razor Page or MVC controller and action.

Im folgenden Beispiel wird eine Middlewarereihenfolge veranschaulicht, bei der Anforderungen statischer Dateien von der Middleware für statische Dateien vor der Middleware für die Antwortkomprimierung verarbeitet werden.The following example demonstrates a middleware order where requests for static files are handled by Static File Middleware before Response Compression Middleware. Die statischen Dateien werden bei dieser Middlewarereihenfolge nicht komprimiert.Static files aren't compressed with this middleware order. Die Razor Pages-Antworten können komprimiert werden.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();
    });
}

Bei Single-Page-Webanwendungen (Single-Page Applications, SPAs) ist die entsprechende SPA-Middleware UseSpaStaticFiles in der Regel der letzte Teil der Middlewarepipeline.For Single Page Applications (SPAs), the SPA middleware UseSpaStaticFiles usually comes last in the middleware pipeline. Die SPA-Middleware kommt zuletzt, damit:The SPA middleware comes last:

  • Jede andere Middleware zuerst auf entsprechende Anforderungen reagieren können.To allow all other middlewares to respond to matching requests first.
  • SPAs mit clientseitigem Routing für alle Routen ausgeführt werden können, die von der Server-App nicht erkannt werden.To allow SPAs with client-side routing to run for all routes that are unrecognized by the server app.

Weitere Informationen zu SPAs finden Sie in den Anleitungen zu den React- und Angular-Projektvorlagen.For more details on SPAs, see the guides for the React and Angular project templates.

Middleware für weitergeleitete Header: AuftragForwarded Headers Middleware order

Die Middleware für weitergeleitete Header muss noch vor einer anderen Middleware ausgeführt werden.Forwarded Headers Middleware should run before other middleware. Mit dieser Reihenfolge wird sichergestellt, dass die auf Informationen von weitergeleiteten Headern basierende Middleware die zu verarbeitenden Headerwerte nutzen kann.This ordering ensures that the middleware relying on forwarded headers information can consume the header values for processing. Unter Middleware für weitergeleitete Header: Auftrag finden Sie Informationen zum Ausführen der Middleware für weitergeleitete Header nach der diagnostischen Middleware und der Middleware für die Fehlerbehandlung.To run Forwarded Headers Middleware after diagnostics and error handling middleware, see Forwarded Headers Middleware order.

Branchen der MiddlewarepipelineBranch the middleware pipeline

Map-Erweiterungen werden als Konvention zum Branchen der Pipeline verwendet.Map extensions are used as a convention for branching the pipeline. Map brancht die Anforderungspipeline auf Grundlage von Übereinstimmungen des angegebenen Anforderungspfads.Map branches the request pipeline based on matches of the given request path. Wenn der Anforderungspfad mit dem angegebenen Pfad beginnt, wird der Branch ausgeführt.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>");
        });
    }
}

In der folgenden Tabelle sind die Anforderungen und Antworten von http://localhost:1234 mit dem oben stehenden Code aufgelistet.The following table shows the requests and responses from http://localhost:1234 using the previous code.

AnforderungRequest AntwortResponse
localhost:1234localhost:1234 Hello from non-Map delegate.Hello from non-Map delegate.
localhost:1234/map1localhost:1234/map1 Map Test 1Map Test 1
localhost:1234/map2localhost:1234/map2 Map Test 2Map Test 2
localhost:1234/map3localhost:1234/map3 Hello from non-Map delegate.Hello from non-Map delegate.

Bei Verwendung von Map werden die übereinstimmenden Pfadsegmente aus HttpRequest.Path entfernt und für jede Anforderung an HttpRequest.PathBase angehängt.When Map is used, the matched path segments are removed from HttpRequest.Path and appended to HttpRequest.PathBase for each request.

Map unterstützt das Schachteln, wie z.B. in folgendem Code:Map supports nesting, for example:

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

Map kann auch mehrere Segmente auf einmal zuordnen: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.");
        });
    }
}

MapWhen brancht die Anforderungspipeline auf Grundlage des Ergebnisses des angegebenen Prädikats.MapWhen branches the request pipeline based on the result of the given predicate. Jedes Prädikat vom Typ Func<HttpContext, bool> kann verwendet werden, um Anforderungen einem neuen Branch der Pipeline zuzuordnen.Any predicate of type Func<HttpContext, bool> can be used to map requests to a new branch of the pipeline. Im folgenden Beispiel wird ein Prädikat verwendet, um das Vorhandensein der Abfragezeichenfolgenvariablen branch zu ermitteln: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>");
        });
    }
}

In der folgenden Tabelle sind die Anforderungen und Antworten von http://localhost:1234 mit dem oben stehenden Code aufgelistet:The following table shows the requests and responses from http://localhost:1234 using the previous code:

AnforderungRequest AntwortResponse
localhost:1234localhost:1234 Hello from non-Map delegate.Hello from non-Map delegate.
localhost:1234/?branch=masterlocalhost:1234/?branch=master Branch used = masterBranch used = master

UseWhen brancht auch die Anforderungspipeline auf Grundlage des Ergebnisses des angegebenen Prädikats.UseWhen also branches the request pipeline based on the result of the given predicate. Anders als bei MapWhen wird dieser Branch wieder mit der Hauptpipeline verbunden, wenn er nicht kurzgeschlossen wird oder eine Terminalmiddleware enthält: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.");
        });
    }
}

Im vorherigen Beispiel wird „Hello from main pipeline“ (Hallo aus der Hauptpipeline)In the preceding example, a response of "Hello from main pipeline." für alle Anforderungen geschrieben.is written for all requests. Wenn die Anforderung eine Abfragezeichenfolgevariable branch enthält, wird der Wert der Pipeline protokolliert, bevor eine neue Verbindung hergestellt wird.If the request includes a query string variable branch, its value is logged before the main pipeline is rejoined.

Integrierte MiddlewareBuilt-in middleware

Die folgenden Middlewarekomponenten sind im Lieferumfang von ASP.NET Core enthalten.ASP.NET Core ships with the following middleware components. Die Spalte Reihenfolge enthält Hinweise zur Platzierung der Middleware in der Pipeline, die die Anforderung verarbeitet, und zu den Bedingungen, unter denen die Middleware die Anforderungsverarbeitung möglicherweise beendet.The Order column provides notes on middleware placement in the request processing pipeline and under what conditions the middleware may terminate request processing. Wenn eine Middleware einen Kurzschluss in der Anforderungsverarbeitungspipeline verursacht und verhindert, dass Downstreammiddleware eine Anforderung verarbeitet, wird diese als Terminalmiddleware bezeichnet.When a middleware short-circuits the request processing pipeline and prevents further downstream middleware from processing a request, it's called a terminal middleware. Weitere Informationen zu Kurzschlüssen finden Sie im Abschnitt Erstellen einer Middlewarepipeline mit IApplicationBuilder.For more information on short-circuiting, see the Create a middleware pipeline with IApplicationBuilder section.

MiddlewareMiddleware BeschreibungDescription AuftragOrder
AuthentifizierungAuthentication Bietet Unterstützung für Authentifizierungen.Provides authentication support. Bevor HttpContext.User erforderlich ist.Before HttpContext.User is needed. Terminal für OAuth-Rückrufe.Terminal for OAuth callbacks.
AutorisierungAuthorization Bietet Unterstützung für AuthentifizierungenProvides authorization support. Direkt nach der AuthentifizierungsmiddlewareImmediately after the Authentication Middleware.
CookierichtlinieCookie Policy Verfolgt die Zustimmung von Benutzern zum Speichern persönlicher Informationen und erzwingt die Mindeststandards für cookiefelder, z. B. secure und SameSite.Tracks consent from users for storing personal information and enforces minimum standards for cookie fields, such as secure and SameSite. Befindet sich vor der Middleware, die cookies ausstellt.Before middleware that issues cookies. Beispiele: Authentifizierung, Sitzung, MVC (TempData).Examples: Authentication, Session, MVC (TempData).
CORSCORS Konfiguriert die Ressourcenfreigabe zwischen verschiedenen Ursprüngen (Cross-Origin Resource Sharing, CORS).Configures Cross-Origin Resource Sharing. Vor Komponenten, die CORS verwenden.Before components that use CORS. UseCors muss sich derzeit aufgrund dieses Fehlers vor UseResponseCaching befinden.UseCors currently must go before UseResponseCaching due to this bug.
DiagnoseDiagnostics Mehrere separate Middlewares, die Entwicklern eine Ausnahmeseite, Ausnahmebehandlung, Statuscodeseiten und die Standardwebseite für neue Apps bereitstellen.Several separate middlewares that provide a developer exception page, exception handling, status code pages, and the default web page for new apps. Vor Komponenten, die Fehler erzeugen.Before components that generate errors. Terminal für Ausnahmen oder zum Bereitstellen der Standardwebseite für neue Apps.Terminal for exceptions or serving the default web page for new apps.
Weitergeleitete HeaderForwarded Headers Leitet Proxyheader an die aktuelle Anforderung weiter.Forwards proxied headers onto the current request. Vor Komponenten, die die aktualisierten Felder nutzen.Before components that consume the updated fields. Beispiele: Schema, Host, Client-IP, Methode.Examples: scheme, host, client IP, method.
IntegritätsprüfungHealth Check Überprüft die Integrität der ASP.NET Core-App und ihrer Abhängigkeiten, z. B. Überprüfung der Datenbankverfügbarkeit.Checks the health of an ASP.NET Core app and its dependencies, such as checking database availability. Abschließend, wenn eine Anforderung mit einem Integritätsprüfungs-Endpunkt übereinstimmt.Terminal if a request matches a health check endpoint.
HeaderweitergabeHeader Propagation Überträgt HTTP-Header aus der eingehenden Anforderung zu ausgehenden HTTP-ClientanforderungenPropagates HTTP headers from the incoming request to the outgoing HTTP Client requests.
Außerkraftsetzung der HTTP-MethodeHTTP Method Override Ermöglicht es eingehenden POST-Anforderungen, die Methode außer Kraft zu setzen.Allows an incoming POST request to override the method. Vor Komponenten, die die aktualisierte Methode nutzen.Before components that consume the updated method.
HTTPS-UmleitungHTTPS Redirection Leitet alle HTTP-Anforderungen an HTTPS um.Redirect all HTTP requests to HTTPS. Vor Komponenten, die die URL nutzen.Before components that consume the URL.
HTTP Strict Transport Security (HSTS)HTTP Strict Transport Security (HSTS) Middleware für erweiterte Sicherheit, die einen besonderen Antwortheader hinzufügt.Security enhancement middleware that adds a special response header. Bevor Antworten gesendet werden und nach Komponenten, die Anforderungen ändern.Before responses are sent and after components that modify requests. Beispiele: weitergeleitete Header, URL-Umschreibung.Examples: Forwarded Headers, URL Rewriting.
MVCMVC Verarbeitet Anforderungen mit MVC/Razor Pages.Processes requests with MVC/Razor Pages. Abschließend, wenn eine Anforderung mit einer Route übereinstimmt.Terminal if a request matches a route.
OWINOWIN Interoperabilität mit auf OWIN basierten Apps, Servern und Middleware.Interop with OWIN-based apps, servers, and middleware. Abschließend, wenn die OWIN-Middleware die Anforderung vollständig verarbeitet.Terminal if the OWIN Middleware fully processes the request.
Zwischenspeichern von AntwortenResponse Caching Bietet Unterstützung für das Zwischenspeichern von Antworten.Provides support for caching responses. Vor Komponenten, für die das Zwischenspeichern erforderlich ist.Before components that require caching. UseCORS muss sich vor UseResponseCaching befinden.UseCORS must come before UseResponseCaching.
AntwortkomprimierungResponse Compression Bietet Unterstützung für das Komprimieren von Antworten.Provides support for compressing responses. Vor Komponenten, für die das Komprimieren erforderlich ist.Before components that require compression.
Lokalisierung von AnforderungenRequest Localization Bietet Unterstützung für die Lokalisierung.Provides localization support. Vor der Lokalisierung vertraulicher Komponenten.Before localization sensitive components.
EndpunktroutingEndpoint Routing Definiert Anforderungsrouten und schränkt diese ein.Defines and constrains request routes. Terminal für entsprechende Routen.Terminal for matching routes.
SPASPA Verarbeitet alle Anforderungen ab diesem Punkt in der Middlewarekette, indem die Standardseite für die Single-Page-Anwendung zurückgegeben wird.Handles all requests from this point in the middleware chain by returning the default page for the Single Page Application (SPA) Kommt spät in der Kette, sodass andere Middleware, z. B. die zum Bereitstellen von statischen Dateien oder MVC-Aktionen, Vorrang hat.Late in the chain, so that other middleware for serving static files, MVC actions, etc., takes precedence.
SitzungSession Bietet Unterstützung für das Verwalten von Benutzersitzungen.Provides support for managing user sessions. Vor Komponenten, für die Sitzungen erforderlich sind.Before components that require Session.
Statische DateienStatic Files Bietet Unterstützung für das Verarbeiten statischer Dateien und das Durchsuchen des Verzeichnisses.Provides support for serving static files and directory browsing. Abschließend, wenn eine Anforderung mit einer Datei übereinstimmt.Terminal if a request matches a file.
Umschreiben einer URLURL Rewrite Bietet Unterstützung für das Umschreiben von URLs und das Umleiten von Anforderungen.Provides support for rewriting URLs and redirecting requests. Vor Komponenten, die die URL nutzen.Before components that consume the URL.
WebSocketsWebSockets Aktiviert das WebSockets-Protokoll.Enables the WebSockets protocol. Vor Komponenten, die WebSocket-Anforderungen annehmen müssen.Before components that are required to accept WebSocket requests.

Zusätzliche RessourcenAdditional resources

Von Rick Anderson und Steve SmithBy Rick Anderson and Steve Smith

Middleware ist Software, die zu einer Anwendungspipeline zusammengesetzt wird, um Anforderungen und Antworten zu verarbeiten.Middleware is software that's assembled into an app pipeline to handle requests and responses. Jede Komponente kann Folgendes ausführen:Each component:

  • Entscheiden, ob die Anforderung an die nächste Komponente in der Pipeline übergeben werden soll.Chooses whether to pass the request to the next component in the pipeline.
  • Ausführen von Arbeiten, bevor oder nachdem die nächste Komponente in der Pipeline aufgerufen wird.Can perform work before and after the next component in the pipeline.

Anforderungsdelegaten werden verwendet, um die Anforderungspipeline zu erstellen.Request delegates are used to build the request pipeline. Die Anforderungsdelegaten behandeln jede HTTP-Anforderung.The request delegates handle each HTTP request.

Anforderungsdelegaten werden mit den Erweiterungsmethoden Run, Map und Use konfiguriert.Request delegates are configured using Run, Map, and Use extension methods. Ein einzelner Anforderungsdelegat kann inline als anonyme Methode angegeben werden (sogenannte Inline-Middleware), oder er kann in einer wiederverwendbaren Klasse definiert werden.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. Diese wiederverwendbaren Klassen und anonymen Inline-Methoden sind Middleware bzw. Middlewarekomponenten.These reusable classes and in-line anonymous methods are middleware, also called middleware components. Jede Middlewarekomponente in der Anforderungspipeline ist für das Aufrufen der jeweils nächsten Komponente in der Pipeline oder, wenn nötig, für das Kurzschließen der Pipeline zuständig.Each middleware component in the request pipeline is responsible for invoking the next component in the pipeline or short-circuiting the pipeline. Wenn eine Middleware einen Kurzschluss verursacht, wird diese als Terminalmiddleware bezeichnet, da sie verhindert, dass weitere Middleware die Anforderung verarbeiten kann.When a middleware short-circuits, it's called a terminal middleware because it prevents further middleware from processing the request.

Unter Migrieren von HTTP-Handlern und Modulen zu ASP.net Core Middleware wird der Unterschied zwischen Anforderungspipelines in ASP.NET Core und ASP.NET 4.x erklärt. Außerdem werden dort zusätzliche Beispiele für Middleware bereitgestellt.Migrieren von HTTP-Handlern und Modulen zu ASP.net Core Middleware explains the difference between request pipelines in ASP.NET Core and ASP.NET 4.x and provides additional middleware samples.

Erstellen einer Middlewarepipeline mit IApplicationBuilderCreate a middleware pipeline with IApplicationBuilder

Die ASP.NET Core-Anforderungspipeline besteht aus einer Sequenz von Anforderungsdelegaten, die nacheinander aufgerufen werden.The ASP.NET Core request pipeline consists of a sequence of request delegates, called one after the other. Das Konzept wird im folgenden Diagramm veranschaulicht.The following diagram demonstrates the concept. Der Ausführungsthread folgt den schwarzen Pfeilen.The thread of execution follows the black arrows.

Anforderungsverarbeitungsmuster mit eingehender Anforderung, deren Verarbeitung von drei Middlewares und die ausgehende Antwort der Anwendung.

Jeder Delegat kann Vorgänge vor und nach dem nächsten Delegaten ausführen.Each delegate can perform operations before and after the next delegate. Die Ausnahmebehandlungsdelegaten müssen am Anfang der Pipeline aufgerufen werden, sodass sie Ausnahmen abfangen können, die zu einem späteren Zeitpunkt in der Pipeline ausgelöst werden.Exception-handling delegates should be called early in the pipeline, so they can catch exceptions that occur in later stages of the pipeline.

Die einfachste mögliche ASP.NET Core-App enthält einen einzigen Anforderungsdelegaten, der alle Anforderungen verarbeitet.The simplest possible ASP.NET Core app sets up a single request delegate that handles all requests. In diesem Fall ist keine tatsächliche Anforderungspipeline vorhanden.This case doesn't include an actual request pipeline. Stattdessen wird eine einzelne anonyme Funktion als Antwort auf jede HTTP-Anforderung aufgerufen.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!");
        });
    }
}

Der erste Run-Delegat beendet die Pipeline.The first Run delegate terminates the pipeline.

Mit Use können Sie mehrere Anforderungedelegate miteinander verknüpfen.Chain multiple request delegates together with Use. Der Parameter next steht für den nächsten Delegaten in der Pipeline.The next parameter represents the next delegate in the pipeline. Sie können die Pipeline kurzschließen, indem Sie den Parameter next nicht aufrufen.You can short-circuit the pipeline by not calling the next parameter. Normalerweise können Sie Aktionen sowohl vor als auch nach dem nächsten Delegaten durchführen. Dies wird in folgendem Beispiel veranschaulicht: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.");
        });
    }
}

Wenn ein keine Anforderung an den nächsten Delegaten übergibt, wird dies als Kurzschluss der Anforderungspipeline bezeichnet.When a delegate doesn't pass a request to the next delegate, it's called short-circuiting the request pipeline. Das Kurzschließen ist oft sinnvoll, da es unnötige Arbeit verhindert.Short-circuiting is often desirable because it avoids unnecessary work. Die Middleware für statische Dateien kann beispielsweise als Terminalmiddleware fungieren, indem sie eine Anforderung für eine statische Datei zurückgibt und den Rest der Pipeline kurzschließt.For example, Static File Middleware can act as a terminal middleware by processing a request for a static file and short-circuiting the rest of the pipeline. Middleware, die noch vor der Middleware, die die weitere Verarbeitung beendet, zur Pipeline hinzugefügt wird, verarbeitet Code noch nach den next.Invoke-Anweisungen weiter.Middleware added to the pipeline before the middleware that terminates further processing still processes code after their next.Invoke statements. Sehen Sie sich allerdings die folgende Warnung zum Versuch an, in eine Antwort zu schreiben, die bereits gesendet wurde.However, see the following warning about attempting to write to a response that has already been sent.

Warnung

Rufen Sie next.Invoke nicht auf, nachdem die Antwort an den Client gesendet wurde.Don't call next.Invoke after the response has been sent to the client. An HttpResponse vorgenommene Änderungen lösen nach dem Start der Antwort eine Ausnahme aus.Changes to HttpResponse after the response has started throw an exception. Änderungen wie das Festlegen von Headern und einem Statuscode lösen beispielsweise eine Ausnahme aus.For example, changes such as setting headers and a status code throw an exception. Wenn Sie nach dem Aufruf von next in den Antworttext schreiben, kann dies:Writing to the response body after calling next:

  • einen Protokollverstoß verursachen,May cause a protocol violation. wenn Sie z.B. mehr als das genannte Content-Length-Objekt schreiben.For example, writing more than the stated Content-Length.
  • Fehler im Textformat auslösen,May corrupt the body format. wenn Sie z.B. eine HTML-Fußzeile in eine CSS-Datei schreiben.For example, writing an HTML footer to a CSS file.

HasStarted ist ein nützlicher Hinweis, der angibt, ob Header gesendet wurden oder ob in den Text geschrieben wurde.HasStarted is a useful hint to indicate if headers have been sent or the body has been written to.

MiddlewarereihenfolgeMiddleware order

Die Reihenfolge, in der Middlewarekomponenten in der Startup.Configure-Methode hinzugefügt werden, legt die Reihenfolge fest, in der die Middlewarekomponenten bei Anforderungen aufgerufen werden. Bei Antworten gilt die umgekehrte Reihenfolge.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. Die Reihenfolge ist in Bezug auf Sicherheit, Leistung und Funktionalität entscheidend.The order is critical for security, performance, and functionality.

Die folgende Startup.Configure-Methode fügt sicherheitsbezogene Middlewarekomponenten in der empfohlenen Reihenfolge hinzu: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?}");
    });
}

Für den Code oben gilt:In the preceding code:

  • Middleware, die beim Erstellen einer neuen Web-App mit einzelnen Benutzerkonten nicht hinzugefügt wird, wird auskommentiert.Middleware that is not added when creating a new web app with individual users accounts is commented out.
  • Nicht jede Middleware muss in genau dieser Reihenfolge vorliegen, aber für viele Middlewarekomponenten ist dies erforderlich.Not every middleware needs to go in this exact order, but many do. Beispielsweise müssen UseCors und UseAuthentication in der gezeigten Reihenfolge vorliegen.For example, UseCors and UseAuthentication must go in the order shown.

Die folgenden Startup.Configure-Methode fügt Middlewarekomponenten für allgemeine App-Szenarien hinzu:The following Startup.Configure method adds middleware components for common app scenarios:

  1. Ausnahme-/FehlerbehandlungException/error handling
    • Bei Ausführung der App in der Entwicklungsumgebung:When the app runs in the Development environment:
      • Middleware der Seite mit Ausnahmen für Entwickler (UseDeveloperExceptionPage) meldet App-Laufzeitfehler.Developer Exception Page Middleware (UseDeveloperExceptionPage) reports app runtime errors.
      • Middleware der Seite mit Datenbankfehlern (Microsoft.AspNetCore.Builder.DatabaseErrorPageExtensions.UseDatabaseErrorPage) meldet Datenbanklaufzeitfehler.Database Error Page Middleware (Microsoft.AspNetCore.Builder.DatabaseErrorPageExtensions.UseDatabaseErrorPage) reports database runtime errors.
    • Bei Ausführung der App in der Produktionsumgebung:When the app runs in the Production environment:
      • Middleware für Ausnahmehandler (UseExceptionHandler) fängt Ausnahmen ab, die in den folgenden Middlewarekomponenten ausgelöst werden.Exception Handler Middleware (UseExceptionHandler) catches exceptions thrown in the following middlewares.
      • HTTP Strict Transport Security Protocol-Middleware (HSTS) (UseHsts) fügt den Strict-Transport-Security-Header hinzu.HTTP Strict Transport Security Protocol (HSTS) Middleware (UseHsts) adds the Strict-Transport-Security header.
  2. Middleware zur HTTPS-Umleitung (UseHttpsRedirection) leitet HTTP-Anforderungen an HTTPS um.HTTPS Redirection Middleware (UseHttpsRedirection) redirects HTTP requests to HTTPS.
  3. Middleware für statische Dateien (UseStaticFiles) gibt statische Dateien zurück und umgeht die weitere Anforderungsverarbeitung.Static File Middleware (UseStaticFiles) returns static files and short-circuits further request processing.
  4. Middleware für Cookierichtlinien (UseCookiePolicy) sorgt dafür, dass die App die Anforderungen der europäischen Datenschutzgrundverordnung (DSGVO) erfüllt.Cookie Policy Middleware (UseCookiePolicy) conforms the app to the EU General Data Protection Regulation (GDPR) regulations.
  5. Middleware für die Authentifizierung (UseAuthentication) versucht, den Benutzer zu authentifizieren, bevor der Zugriff auf sichere Ressourcen zugelassen wird.Authentication Middleware (UseAuthentication) attempts to authenticate the user before they're allowed access to secure resources.
  6. Middleware für Sitzungen (UseSession) richtet einen Sitzungsstatus ein und erhält diesen aufrecht.Session Middleware (UseSession) establishes and maintains session state. Wenn die App den Sitzungsstatus verwendet, rufen Sie die Middleware für Sitzungen nach der Middleware für Cookierichtlinien und vor der MVC-Middleware auf.If the app uses session state, call Session Middleware after Cookie Policy Middleware and before MVC Middleware.
  7. MVC-Middleware (UseMvc) zum Hinzufügen von MVC zur Anforderungspipeline.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();
}

Im vorhergehenden Beispielcode wird jede Middleware-Erweiterungsmethode in IApplicationBuilder über den Microsoft.AspNetCore.Builder-Namespace verfügbar gemacht.In the preceding example code, each middleware extension method is exposed on IApplicationBuilder through the Microsoft.AspNetCore.Builder namespace.

UseExceptionHandler ist die erste Middlewarekomponente, die der Pipeline hinzugefügt wird.UseExceptionHandler is the first middleware component added to the pipeline. Aus diesem Grund fängt die Middleware für den Ausnahmehandler alle Ausnahmen ab, die in späteren Aufrufen auftreten.Therefore, the Exception Handler Middleware catches any exceptions that occur in later calls.

Die Middleware für statische Dateien wird am Anfang der Pipeline aufgerufen, damit sie Anforderungen und Kurzschlüsse verarbeiten kann, ohne dass die verbleibenden Komponenten durchlaufen werden müssen.Static File Middleware is called early in the pipeline so that it can handle requests and short-circuit without going through the remaining components. Die Middleware für statische Dateien stellt keine Autorisierungsüberprüfungen bereit.The Static File Middleware provides no authorization checks. Alle Dateien, die von Middleware für statische Dateien unterstützt werden, einschließlich der Dateien unter wwwroot, sind öffentlich verfügbar.Any files served by Static File Middleware, including those under wwwroot, are publicly available. Informationen zum Sichern statischer Dateien finden Sie unter Statische Dateien in ASP.NET Core.For an approach to secure static files, see Statische Dateien in ASP.NET Core.

Wenn die Anforderung nicht von der Middleware für statische Dateien verarbeitet wird, wird sie an die Authentifizierungsmiddleware (UseAuthentication) übergeben, welche die Authentifizierung durchführt.If the request isn't handled by the Static File Middleware, it's passed on to the Authentication Middleware (UseAuthentication), which performs authentication. Die Authentifizierung schließt nicht authentifizierte Anforderungen nicht kurz.Authentication doesn't short-circuit unauthenticated requests. Auch wenn die Authentifizierungsmiddleware Anforderungen authentifiziert, erfolgt die Autorisierung (und Ablehnung) erst dann, wenn MVC eine spezifische Razor Page oder einen MVC-Controller und eine Aktion ausgewählt hat.Although Authentication Middleware authenticates requests, authorization (and rejection) occurs only after MVC selects a specific Razor Page or MVC controller and action.

Im folgenden Beispiel wird eine Middlewarereihenfolge veranschaulicht, bei der Anforderungen statischer Dateien von der Middleware für statische Dateien vor der Middleware für die Antwortkomprimierung verarbeitet werden.The following example demonstrates a middleware order where requests for static files are handled by Static File Middleware before Response Compression Middleware. Die statischen Dateien werden bei dieser Middlewarereihenfolge nicht komprimiert.Static files aren't compressed with this middleware order. Die MVC-Antworten von UseMvcWithDefaultRoute können komprimiert werden.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();
}

Use, Run und MapUse, Run, and Map

Konfigurieren Sie die HTTP-Pipeline mit Use, Run und Map.Configure the HTTP pipeline using Use, Run, and Map. Die Use-Methode kann die Pipeline kurzschließen (wenn sie keinen next-Anforderungsdelegaten aufruft).The Use method can short-circuit the pipeline (that is, if it doesn't call a next request delegate). Run ist eine Konvention. Einige Middlewarekomponenten machen möglicherweise Run[Middleware]-Methoden verfügbar, die am Ende einer Pipeline ausgeführt werden.Run is a convention, and some middleware components may expose Run[Middleware] methods that run at the end of the pipeline.

Map-Erweiterungen werden als Konvention zum Branchen der Pipeline verwendet.Map extensions are used as a convention for branching the pipeline. Map brancht die Anforderungspipeline auf Grundlage von Übereinstimmungen des angegebenen Anforderungspfads.Map branches the request pipeline based on matches of the given request path. Wenn der Anforderungspfad mit dem angegebenen Pfad beginnt, wird der Branch ausgeführt.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>");
        });
    }
}

In der folgenden Tabelle sind die Anforderungen und Antworten von http://localhost:1234 mit dem oben stehenden Code aufgelistet.The following table shows the requests and responses from http://localhost:1234 using the previous code.

AnforderungRequest AntwortResponse
localhost:1234localhost:1234 Hello from non-Map delegate.Hello from non-Map delegate.
localhost:1234/map1localhost:1234/map1 Map Test 1Map Test 1
localhost:1234/map2localhost:1234/map2 Map Test 2Map Test 2
localhost:1234/map3localhost:1234/map3 Hello from non-Map delegate.Hello from non-Map delegate.

Bei Verwendung von Map werden die übereinstimmenden Pfadsegmente aus HttpRequest.Path entfernt und für jede Anforderung an HttpRequest.PathBase angehängt.When Map is used, the matched path segments are removed from HttpRequest.Path and appended to HttpRequest.PathBase for each request.

MapWhen brancht die Anforderungspipeline auf Grundlage des Ergebnisses des angegebenen Prädikats.MapWhen branches the request pipeline based on the result of the given predicate. Jedes Prädikat vom Typ Func<HttpContext, bool> kann verwendet werden, um Anforderungen einem neuen Branch der Pipeline zuzuordnen.Any predicate of type Func<HttpContext, bool> can be used to map requests to a new branch of the pipeline. Im folgenden Beispiel wird ein Prädikat verwendet, um das Vorhandensein der Abfragezeichenfolgenvariablen branch zu ermitteln: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>");
        });
    }
}

In der folgenden Tabelle sind die Anforderungen und Antworten von http://localhost:1234 mit dem oben stehenden Code aufgelistet.The following table shows the requests and responses from http://localhost:1234 using the previous code.

AnforderungRequest AntwortResponse
localhost:1234localhost:1234 Hello from non-Map delegate.Hello from non-Map delegate.
localhost:1234/?branch=masterlocalhost:1234/?branch=master Branch used = masterBranch used = master

Map unterstützt das Schachteln, wie z.B. in folgendem Code:Map supports nesting, for example:

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

Map kann auch mehrere Segmente auf einmal zuordnen: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.");
        });
    }
}

Integrierte MiddlewareBuilt-in middleware

Die folgenden Middlewarekomponenten sind im Lieferumfang von ASP.NET Core enthalten.ASP.NET Core ships with the following middleware components. Die Spalte Reihenfolge enthält Hinweise zur Platzierung der Middleware in der Pipeline, die die Anforderung verarbeitet, und zu den Bedingungen, unter denen die Middleware die Anforderungsverarbeitung möglicherweise beendet.The Order column provides notes on middleware placement in the request processing pipeline and under what conditions the middleware may terminate request processing. Wenn eine Middleware einen Kurzschluss in der Anforderungsverarbeitungspipeline verursacht und verhindert, dass Downstreammiddleware eine Anforderung verarbeitet, wird diese als Terminalmiddleware bezeichnet.When a middleware short-circuits the request processing pipeline and prevents further downstream middleware from processing a request, it's called a terminal middleware. Weitere Informationen zu Kurzschlüssen finden Sie im Abschnitt Erstellen einer Middlewarepipeline mit IApplicationBuilder.For more information on short-circuiting, see the Create a middleware pipeline with IApplicationBuilder section.

MiddlewareMiddleware BeschreibungDescription AuftragOrder
AuthentifizierungAuthentication Bietet Unterstützung für Authentifizierungen.Provides authentication support. Bevor HttpContext.User erforderlich ist.Before HttpContext.User is needed. Terminal für OAuth-Rückrufe.Terminal for OAuth callbacks.
CookierichtlinieCookie Policy Verfolgt die Zustimmung von Benutzern zum Speichern persönlicher Informationen und erzwingt die Mindeststandards für cookiefelder, z. B. secure und SameSite.Tracks consent from users for storing personal information and enforces minimum standards for cookie fields, such as secure and SameSite. Befindet sich vor der Middleware, die cookies ausstellt.Before middleware that issues cookies. Beispiele: Authentifizierung, Sitzung, MVC (TempData).Examples: Authentication, Session, MVC (TempData).
CORSCORS Konfiguriert die Ressourcenfreigabe zwischen verschiedenen Ursprüngen (Cross-Origin Resource Sharing, CORS).Configures Cross-Origin Resource Sharing. Vor Komponenten, die CORS verwenden.Before components that use CORS.
DiagnoseDiagnostics Mehrere separate Middlewares, die Entwicklern eine Ausnahmeseite, Ausnahmebehandlung, Statuscodeseiten und die Standardwebseite für neue Apps bereitstellen.Several separate middlewares that provide a developer exception page, exception handling, status code pages, and the default web page for new apps. Vor Komponenten, die Fehler erzeugen.Before components that generate errors. Terminal für Ausnahmen oder zum Bereitstellen der Standardwebseite für neue Apps.Terminal for exceptions or serving the default web page for new apps.
Weitergeleitete HeaderForwarded Headers Leitet Proxyheader an die aktuelle Anforderung weiter.Forwards proxied headers onto the current request. Vor Komponenten, die die aktualisierten Felder nutzen.Before components that consume the updated fields. Beispiele: Schema, Host, Client-IP, Methode.Examples: scheme, host, client IP, method.
IntegritätsprüfungHealth Check Überprüft die Integrität der ASP.NET Core-App und ihrer Abhängigkeiten, z. B. Überprüfung der Datenbankverfügbarkeit.Checks the health of an ASP.NET Core app and its dependencies, such as checking database availability. Abschließend, wenn eine Anforderung mit einem Integritätsprüfungs-Endpunkt übereinstimmt.Terminal if a request matches a health check endpoint.
Außerkraftsetzung der HTTP-MethodeHTTP Method Override Ermöglicht es eingehenden POST-Anforderungen, die Methode außer Kraft zu setzen.Allows an incoming POST request to override the method. Vor Komponenten, die die aktualisierte Methode nutzen.Before components that consume the updated method.
HTTPS-UmleitungHTTPS Redirection Leitet alle HTTP-Anforderungen an HTTPS um.Redirect all HTTP requests to HTTPS. Vor Komponenten, die die URL nutzen.Before components that consume the URL.
HTTP Strict Transport Security (HSTS)HTTP Strict Transport Security (HSTS) Middleware für erweiterte Sicherheit, die einen besonderen Antwortheader hinzufügt.Security enhancement middleware that adds a special response header. Bevor Antworten gesendet werden und nach Komponenten, die Anforderungen ändern.Before responses are sent and after components that modify requests. Beispiele: weitergeleitete Header, URL-Umschreibung.Examples: Forwarded Headers, URL Rewriting.
MVCMVC Verarbeitet Anforderungen mit MVC/Razor Pages.Processes requests with MVC/Razor Pages. Abschließend, wenn eine Anforderung mit einer Route übereinstimmt.Terminal if a request matches a route.
OWINOWIN Interoperabilität mit auf OWIN basierten Apps, Servern und Middleware.Interop with OWIN-based apps, servers, and middleware. Abschließend, wenn die OWIN-Middleware die Anforderung vollständig verarbeitet.Terminal if the OWIN Middleware fully processes the request.
Zwischenspeichern von AntwortenResponse Caching Bietet Unterstützung für das Zwischenspeichern von Antworten.Provides support for caching responses. Vor Komponenten, für die das Zwischenspeichern erforderlich ist.Before components that require caching.
AntwortkomprimierungResponse Compression Bietet Unterstützung für das Komprimieren von Antworten.Provides support for compressing responses. Vor Komponenten, für die das Komprimieren erforderlich ist.Before components that require compression.
Lokalisierung von AnforderungenRequest Localization Bietet Unterstützung für die Lokalisierung.Provides localization support. Vor der Lokalisierung vertraulicher Komponenten.Before localization sensitive components.
EndpunktroutingEndpoint Routing Definiert Anforderungsrouten und schränkt diese ein.Defines and constrains request routes. Terminal für entsprechende Routen.Terminal for matching routes.
SitzungSession Bietet Unterstützung für das Verwalten von Benutzersitzungen.Provides support for managing user sessions. Vor Komponenten, für die Sitzungen erforderlich sind.Before components that require Session.
Statische DateienStatic Files Bietet Unterstützung für das Verarbeiten statischer Dateien und das Durchsuchen des Verzeichnisses.Provides support for serving static files and directory browsing. Abschließend, wenn eine Anforderung mit einer Datei übereinstimmt.Terminal if a request matches a file.
Umschreiben einer URLURL Rewrite Bietet Unterstützung für das Umschreiben von URLs und das Umleiten von Anforderungen.Provides support for rewriting URLs and redirecting requests. Vor Komponenten, die die URL nutzen.Before components that consume the URL.
WebSocketsWebSockets Aktiviert das WebSockets-Protokoll.Enables the WebSockets protocol. Vor Komponenten, die WebSocket-Anforderungen annehmen müssen.Before components that are required to accept WebSocket requests.

Zusätzliche RessourcenAdditional resources