Fehlerbehandlung in ASP.NET CoreHandle errors in ASP.NET Core

Von Kirk Larkin, Tom Dykstra und Steve SmithBy Kirk Larkin, Tom Dykstra, and Steve Smith

Dieser Artikel beschreibt grundsätzliche Vorgehensweisen zur Behandlung von Fehlern in ASP.NET Core-Web-Apps.This article covers common approaches to handling errors in ASP.NET Core web apps. Weitere Informationen für Web-Apps finden Sie unter Fehlerbehandlung in ASP.NET Core-Web-APIs.See Fehlerbehandlung in ASP.NET Core-Web-APIs for web APIs.

Anzeigen oder Herunterladen von BeispielcodeView or download sample code. (Informationen zum Herunterladen.) Die Registerkarte „Netzwerk“ in den F12-Entwicklertools im Browser ist beim Testen der Beispiel-App nützlich.(How to download.) The network tab on the F12 browser developer tools is useful when testing the sample app.

Seite mit Ausnahmen für EntwicklerDeveloper Exception Page

Die Seite mit Ausnahmen für Entwickler enthält ausführliche Informationen zu unbehandelten Anforderungsausnahmen.The Developer Exception Page displays detailed information about unhandled request exceptions. Die ASP.NET Core-Vorlagen generieren den folgenden Code:The ASP.NET Core templates generate the following code:

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

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

    app.UseRouting();

    app.UseAuthorization();

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

Der vorangehende hervorgehobene Code aktiviert die Seite mit Ausnahmen für Entwickler, wenn die App in der Entwicklungsumgebung ausgeführt wird.The preceding highlighted code enables the developer exception page when the app is running in the Development environment.

Die Vorlagen platzieren UseDeveloperExceptionPage am Anfang der Middlewarepipeline, sodass die in der nachfolgenden Middleware ausgelösten unbehandelten Ausnahmen abgefangen werden.The templates place UseDeveloperExceptionPage early in the middleware pipeline so that it can catch unhandled exceptions thrown in middleware that follows.

Der vorangehende Code aktiviert die Seite mit Ausnahmen für Entwickler nur dann, wenn die App in der Entwicklungsumgebung ausgeführt wird.The preceding code enables the Developer Exception Page only when the app runs in the Development environment. Bei Ausführung der App in der Produktionsumgebung sollten keine detaillierten Informationen zu den Ausnahmen öffentlich angezeigt werden.Detailed exception information should not be displayed publicly when the app runs in the Production environment. Weitere Informationen zum Konfigurieren der Umgebungen finden Sie unter Verwenden von mehreren Umgebungen in ASP.NET Core.For more information on configuring environments, see Verwenden von mehreren Umgebungen in ASP.NET Core.

Die Seite mit Ausnahmen für Entwickler enthält die folgenden Informationen zu der Ausnahme und der Anforderung:The Developer Exception Page includes the following information about the exception and the request:

  • StapelüberwachungStack trace
  • Abfragezeichenfolgeparameter, sofern vorhandenQuery string parameters if any
  • Cookies, sofern vorhandenCookies if any
  • HeaderHeaders

Seite „Ausnahmehandler“Exception handler page

Um eine benutzerdefinierte Fehlerbehandlungsseite für die Produktionsumgebung zu konfigurieren, rufen Sie UseExceptionHandler auf.To configure a custom error handling page for the Production environment, call UseExceptionHandler. Die Aufgaben der Middleware zur Ausnahmebehandlung:This exception handling middleware:

  • Dient zum Abfangen und Protokollieren unbehandelter Ausnahmen.Catches and logs unhandled exceptions.
  • Führt erneut die Anforderung in einer anderen Pipeline im angegebenen Pfad aus.Re-executes the request in an alternate pipeline using the path indicated. Die Anforderung wird nicht erneut ausgeführt, wenn die Antwort gestartet wurde.The request isn't re-executed if the response has started. Der von der Vorlage generierte Code führt die Anforderung erneut mit dem /Error-Pfad aus.The template generated code re-executes the request using the /Error path.

Im folgenden Beispiel fügt UseExceptionHandler die Middleware zur Ausnahmebehandlung in Nichtentwicklungsumgebungen hinzu:In the following example, UseExceptionHandler adds the exception handling middleware in non-Development environments:

if (env.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}
else
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

Die Razor Pages-App-Vorlage stellt im Ordner Pages eine Fehlerseite ( .cshtml) und PageModel-Klasse (ErrorModel) bereit.The Razor Pages app template provides an Error page (.cshtml) and PageModel class (ErrorModel) in the Pages folder. Die Projektvorlage einer MVC-App enthält die Aktionsmethode Error und die Ansicht „Error“ im Home-Controller.For an MVC app, the project template includes an Error action method and an Error view for the Home controller.

Die Middleware für die Ausnahmebehandlung führt die Anforderung unter Verwendung der ursprünglichen HTTP-Methode erneut aus.The exception handling middleware re-executes the request using the original HTTP method. Wenn ein Endpunkt für die Fehlerbehandlung auf bestimmte HTTP-Methoden beschränkt ist, wird er nur für diese Methoden ausgeführt.If an error handler endpoint is restricted to a specific set of HTTP methods, it runs only for those HTTP methods. Beispielsweise wird eine MVC-Controller-Aktion, die das Attribut [HttpGet] verwendet, nur für GET-Anforderungen ausgeführt.For example, an MVC controller action that uses the [HttpGet] attribute runs only for GET requests. Um sicherzustellen, dass alle Anforderungen die benutzerdefinierte Seite für die Fehlerbehandlung erreichen, beschränken Sie die Endpunkte nicht auf bestimmte HTTP-Methoden.To ensure that all requests reach the custom error handling page, don't restrict them to a specific set of HTTP methods.

So behandeln Sie Ausnahmen unterschiedlich, basierend auf der ursprünglichen HTTP-Methode:To handle exceptions differently based on the original HTTP method:

  • Für Razor Pages erstellen Sie mehrere Handlermethoden.For Razor Pages, create multiple handler methods. Verwenden Sie beispielsweise OnGet zum Behandeln von GET-Ausnahmen und OnPost zum Behandeln von POST-Ausnahmen.For example, use OnGet to handle GET exceptions and use OnPost to handle POST exceptions.
  • Für MVC wenden Sie HTTP-Verbattribute auf mehrere Aktionen an.For MVC, apply HTTP verb attributes to multiple actions. Verwenden Sie beispielsweise [HttpGet] zum Behandeln von GET-Ausnahmen und [HttpPost] zum Behandeln von POST-Ausnahmen.For example, use [HttpGet] to handle GET exceptions and use [HttpPost] to handle POST exceptions.

Um nicht authentifizierten Benutzern die Anzeige der benutzerdefinierten Seite für die Fehlerbehandlung zu ermöglichen, stellen Sie sicher, dass der anonyme Zugriff unterstützt wird.To allow unauthenticated users to view the custom error handling page, ensure that it supports anonymous access.

Zugreifen auf die AusnahmeAccess the exception

Verwenden Sie IExceptionHandlerPathFeature, um auf die Ausnahme oder den Pfad der ursprünglichen Anforderung in einem Fehlerhandler zuzugreifen.Use IExceptionHandlerPathFeature to access the exception and the original request path in an error handler. Der folgende Code fügt dem Standard Pages/Error.cshtml.cs die von den ASP.NET Core-Vorlagen generierte ExceptionMessage hinzu:The following code adds ExceptionMessage to the default Pages/Error.cshtml.cs generated by the ASP.NET Core templates:

[ResponseCache(Duration=0, Location=ResponseCacheLocation.None, NoStore=true)]
[IgnoreAntiforgeryToken]
public class ErrorModel : PageModel
{
    public string RequestId { get; set; }
    public bool ShowRequestId => !string.IsNullOrEmpty(RequestId);
    public string ExceptionMessage { get; set; }
    private readonly ILogger<ErrorModel> _logger;

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

    public void OnGet()
    {
        RequestId = Activity.Current?.Id ?? HttpContext.TraceIdentifier;

        var exceptionHandlerPathFeature =
        HttpContext.Features.Get<IExceptionHandlerPathFeature>();
        if (exceptionHandlerPathFeature?.Error is FileNotFoundException)
        {
            ExceptionMessage = "File error thrown";
            _logger.LogError(ExceptionMessage);
        }
        if (exceptionHandlerPathFeature?.Path == "/index")
        {
            ExceptionMessage += " from home page";
        }
    }
}

Warnung

Stellen Sie Clients keine vertraulichen Fehlerinformationen bereit.Do not serve sensitive error information to clients. Die Bereitstellung von Fehlern ist ein Sicherheitsrisiko.Serving errors is a security risk.

So testen Sie die Ausnahme in der Beispiel-AppTo test the exception in the sample app:

  • Legen Sie die Umgebung auf Produktion fest.Set the environment to production.
  • Entfernen Sie die Kommentare aus webBuilder.UseStartup<Startup>(); in Program.cs.Remove the comments from webBuilder.UseStartup<Startup>(); in Program.cs.
  • Wählen Sie Trigger an exception (Ausnahme auslösen) auf der Startseite aus.Select Trigger an exception on the home page.

Lambda-Ausdruck für AusnahmehandlerException handler lambda

Eine Alternative zu einer benutzerdefinierten Ausnahmebehandlungsseite ist das Angeben eines Lambda-Ausdrucks für UseExceptionHandler.An alternative to a custom exception handler page is to provide a lambda to UseExceptionHandler. Die Verwendung eines Lambda-Ausdrucks ermöglicht den Zugriff auf den Fehler, bevor die Antwort zurückgegeben wird.Using a lambda allows access to the error before returning the response.

Der folgende Code verwendet einen Lambdaausdruck für die Ausnahmebehandlung:The following code uses a lambda for exception handling:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler(errorApp =>
        {
            errorApp.Run(async context =>
            {
                context.Response.StatusCode = (int) HttpStatusCode.InternalServerError;;
                context.Response.ContentType = "text/html";

                await context.Response.WriteAsync("<html lang=\"en\"><body>\r\n");
                await context.Response.WriteAsync("ERROR!<br><br>\r\n");

                var exceptionHandlerPathFeature =
                    context.Features.Get<IExceptionHandlerPathFeature>();

                if (exceptionHandlerPathFeature?.Error is FileNotFoundException)
                {
                    await context.Response.WriteAsync(
                                              "File error thrown!<br><br>\r\n");
                }

                await context.Response.WriteAsync(
                                              "<a href=\"/\">Home</a><br>\r\n");
                await context.Response.WriteAsync("</body></html>\r\n");
                await context.Response.WriteAsync(new string(' ', 512)); 
            });
        });
        app.UseHsts();
    }

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

    app.UseRouting();

    app.UseAuthorization();

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

Warnung

Stellen Sie keine vertraulichen Fehlerinformationen aus IExceptionHandlerFeature oder IExceptionHandlerPathFeature für Clients bereit.Do not serve sensitive error information from IExceptionHandlerFeature or IExceptionHandlerPathFeature to clients. Die Bereitstellung von Fehlern ist ein Sicherheitsrisiko.Serving errors is a security risk.

So testen Sie den Lambdaausdruck für die Ausnahmebehandlung in der Beispiel-AppTo test the exception handling lambda in the sample app:

  • Legen Sie die Umgebung auf Produktion fest.Set the environment to production.
  • Entfernen Sie die Kommentare aus webBuilder.UseStartup<StartupLambda>(); in Program.cs.Remove the comments from webBuilder.UseStartup<StartupLambda>(); in Program.cs.
  • Wählen Sie Trigger an exception (Ausnahme auslösen) auf der Startseite aus.Select Trigger an exception on the home page.

UseStatusCodePagesUseStatusCodePages

Die ASP.NET Core-App stellt für HTTP-Fehlerstatuscodes wie 404 – Nicht gefunden standardmäßig keine Statuscodeseite zur Verfügung.By default, an ASP.NET Core app doesn't provide a status code page for HTTP error status codes, such as 404 - Not Found. Wenn die App einen HTTP-Fehlerstatuscode 400–599 feststellt, der keinen Text enthält, werden der Statuscode und ein leerer Antworttext zurückgegeben.When the app encounters an HTTP 400-599 error status code that doesn't have a body, it returns the status code and an empty response body. Verwenden Sie zum Bereitstellen von Statuscodeseiten Middleware für Statuscodeseiten.To provide status code pages, use the status code pages middleware. Um für gängige Statuscodes einfache Handler im Textformat zu aktivieren, rufen Sie in der Startup.Configure-Methode UseStatusCodePages auf:To enable default text-only handlers for common error status codes, call UseStatusCodePages in the Startup.Configure method:

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

    app.UseStatusCodePages();

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

    app.UseRouting();

    app.UseAuthorization();

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

Rufen Sie UseStatusCodePages vor der Middleware für die Anforderungsverarbeitung auf.Call UseStatusCodePages before request handling middleware. Rufen Sie beispielsweise UseStatusCodePages vor der Middleware für statische Dateien und der Middleware für Endpunkte auf.For example, call UseStatusCodePages before the Static File Middleware and the Endpoints Middleware.

Wenn UseStatusCodePages nicht verwendet wird, wird beim Navigieren zu einer URL ohne Endpunkt eine browserabhängige Fehlermeldung zurückgegeben, die angibt, dass der Endpunkt nicht gefunden werden kann.When UseStatusCodePages isn't used, navigating to a URL without an endpoint returns a browser dependent error message indicating the endpoint can't be found. Navigieren Sie zum Beispiel zu Home/Privacy2.For example, navigating to Home/Privacy2. Wenn UseStatusCodePages aufgerufen wird, gibt der Browser Folgendes zurück:When UseStatusCodePages is called, the browser returns:

Status Code: 404; Not Found

UseStatusCodePages wird normalerweise nicht in der Produktionsumgebung verwendet, da diese Methode eine Meldung zurückgibt, die für Benutzer nicht nützlich ist.UseStatusCodePages isn't typically used in production because it returns a message that isn't useful to users.

So testen Sie UseStatusCodePages in der Beispiel-AppTo test UseStatusCodePages in the sample app:

  • Legen Sie die Umgebung auf Produktion fest.Set the environment to production.
  • Entfernen Sie die Kommentare aus webBuilder.UseStartup<StartupUseStatusCodePages>(); in Program.cs.Remove the comments from webBuilder.UseStartup<StartupUseStatusCodePages>(); in Program.cs.
  • Klicken Sie auf die Links auf der Startseite.Select the links on the home page on the home page.

Hinweis

Die Middleware für Statuscodeseiten erfasst keine Ausnahmen.The status code pages middleware does not catch exceptions. Um eine benutzerdefinierte Fehlerbehandlungsseite bereitzustellen, verwenden Sie die Ausnahmehandlerseite.To provide a custom error handling page, use the exception handler page.

UseStatusCodePages mit FormatzeichenfolgeUseStatusCodePages with format string

Um den Inhaltstyp und Text der Antwort anzupassen, verwenden Sie die Überladung von UseStatusCodePages, die einen Inhaltstyp und eine Formatierungszeichenfolge erfordert:To customize the response content type and text, use the overload of UseStatusCodePages that takes a content type and format string:

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

    app.UseStatusCodePages(
        "text/plain", "Status code page, status code: {0}");

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

    app.UseRouting();

    app.UseAuthorization();

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

Im vorangehenden Code ist {0} ein Platzhalter für den Fehlercode.In the preceding code, {0} is a placeholder for the error code.

UseStatusCodePages mit Formatzeichenfolge wird normalerweise nicht in der Produktionsumgebung verwendet, da diese Methode eine Meldung zurückgibt, die für Benutzer nicht nützlich ist.UseStatusCodePages with a format string isn't typically used in production because it returns a message that isn't useful to users.

Um UseStatusCodePages in der Beispiel-App zu testen, entfernen Sie die Kommentare aus webBuilder.UseStartup<StartupFormat>(); in Program.cs.To test UseStatusCodePages in the sample app, remove the comments from webBuilder.UseStartup<StartupFormat>(); in Program.cs.

UseStatusCodePages mit Lambda-AusdruckUseStatusCodePages with lambda

Um benutzerdefinierten Code für die Fehlerbehandlung und das Schreiben von Antworten anzugeben, verwenden Sie die Überladung von UseStatusCodePages, die einen Lambda-Ausdruck verwendet:To specify custom error-handling and response-writing code, use the overload of UseStatusCodePages that takes a lambda expression:

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

    app.UseStatusCodePages(async context =>
    {
        context.HttpContext.Response.ContentType = "text/plain";

        await context.HttpContext.Response.WriteAsync(
            "Status code page, status code: " +
            context.HttpContext.Response.StatusCode);
    });

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

    app.UseRouting();

    app.UseAuthorization();

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

UseStatusCodePages mit Lambdaausdruck wird normalerweise nicht in der Produktionsumgebung verwendet, da diese Methode eine Meldung zurückgibt, die für Benutzer nicht nützlich ist.UseStatusCodePages with a lambda isn't typically used in production because it returns a message that isn't useful to users.

Um UseStatusCodePages in der Beispiel-App zu testen, entfernen Sie die Kommentare aus webBuilder.UseStartup<StartupStatusLambda>(); in Program.cs.To test UseStatusCodePages in the sample app, remove the comments from webBuilder.UseStartup<StartupStatusLambda>(); in Program.cs.

UseStatusCodePagesWithRedirectsUseStatusCodePagesWithRedirects

Die Erweiterungsmethode UseStatusCodePagesWithRedirects:The UseStatusCodePagesWithRedirects extension method:

  • Sendet den Statuscode 302 Found (Gefunden) an den Client.Sends a 302 - Found status code to the client.
  • Leitet den Client an den in der URL-Vorlage angegebenen Fehlerbehandlungsendpunkt weiter.Redirects the client to the error handling endpoint provided in the URL template. Der Fehlerbehandlungsendpunkt zeigt in der Regel Fehlerinformationen an und gibt den HTTP-Code 200 zurück.The error handling endpoint typically displays error information and returns HTTP 200.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Error");
        app.UseHsts();
    }

    app.UseStatusCodePagesWithRedirects("/MyStatusCode?code={0}");

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

    app.UseRouting();

    app.UseAuthorization();

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

Die URL-Vorlage kann, wie im vorangehenden Code gezeigt, einen {0}-Platzhalter für den Statuscode enthalten.The URL template can include a {0} placeholder for the status code, as shown in the preceding code. Wenn die URL-Vorlage mit einer Tilde (~) beginnt, wird ~ durch die Angabe für PathBase der App ersetzt.If the URL template starts with ~ (tilde), the ~ is replaced by the app's PathBase. Wenn Sie in der App einen Endpunkt angeben, müssen Sie eine MVC-Ansicht oder Razor-Seite für den Endpunkt erstellen.When specifying an endpoint in the app, create an MVC view or Razor page for the endpoint. Ein Razor Pages-Beispiel finden Sie unter Pages/MyStatusCode.cshtml in der Beispiel-App.For a Razor Pages example, see Pages/MyStatusCode.cshtml in the sample app.

Diese Methode wird häufig verwendet, wenn die App Folgendes tun soll:This method is commonly used when the app:

  • Den Client an einen anderen Endpunkt umleiten, in der Regel in Fällen, in denen eine andere App den Fehler verarbeitet.Should redirect the client to a different endpoint, usually in cases where a different app processes the error. Für Web-Apps gibt die Adressleiste des Browsers des Clients den umgeleiteten Endpunkt wieder.For web apps, the client's browser address bar reflects the redirected endpoint.
  • Den ursprünglichen Statuscode mit der anfänglichen Umleitungsantwort nicht beibehalten und zurückgeben.Shouldn't preserve and return the original status code with the initial redirect response.

Um UseStatusCodePages in der Beispiel-App zu testen, entfernen Sie die Kommentare aus webBuilder.UseStartup<StartupSCredirect>(); in Program.cs.To test UseStatusCodePages in the sample app, remove the comments from webBuilder.UseStartup<StartupSCredirect>(); in Program.cs.

UseStatusCodePagesWithReExecuteUseStatusCodePagesWithReExecute

Die Erweiterungsmethode UseStatusCodePagesWithReExecute:The UseStatusCodePagesWithReExecute extension method:

  • Gibt den ursprünglichen Statuscode an den Client zurück.Returns the original status code to the client.
  • Generiert den Antworttext durch die erneute Ausführung der Anforderungspipeline mithilfe eines alternativen Pfads.Generates the response body by re-executing the request pipeline using an alternate path.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Error");
        app.UseHsts();
    }

    app.UseStatusCodePagesWithReExecute("/MyStatusCode2", "?code={0}");

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

    app.UseRouting();

    app.UseAuthorization();

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

Wenn in der App ein Endpunkt angegeben ist, müssen Sie eine MVC-Ansicht oder Razor-Seite für den Endpunkt erstellen.If an endpoint within the app is specified, create an MVC view or Razor page for the endpoint. Stellen Sie sicher, dass UseStatusCodePagesWithReExecute vor UseRouting platziert wird, damit die Anforderung an die Statusseite umgeleitet werden kann.Ensure UseStatusCodePagesWithReExecute is placed before UseRouting so the request can be rerouted to the status page. Ein Razor Pages-Beispiel finden Sie unter Pages/MyStatusCode2.cshtml in der Beispiel-App.For a Razor Pages example, see Pages/MyStatusCode2.cshtml in the sample app.

Diese Methode wird häufig verwendet, wenn die App Folgendes tun soll:This method is commonly used when the app should:

  • Die Anforderung ohne Umleitung an einen anderen Endpunkt verarbeiten.Process the request without redirecting to a different endpoint. Für Web-Apps gibt die Adressleiste des Browsers des Clients den ursprünglich angeforderten Endpunkt wieder.For web apps, the client's browser address bar reflects the originally requested endpoint.
  • Den ursprünglichen Statuscode mit der Antwort beibehalten und zurückgeben.Preserve and return the original status code with the response.

Die Vorlagen für URL und Abfragezeichenfolgen können für den Statuscode einen Platzhalter ({0}) enthalten.The URL and query string templates may include a placeholder {0} for the status code. Die URL-Vorlage muss mit einem Schrägstrich (/) beginnen.The URL template must start with /.

Der Endpunkt, der den Fehler verarbeitet, kann die ursprüngliche URL abrufen, die den Fehler generiert hat (siehe folgendes Beispiel):The endpoint that processes the error can get the original URL that generated the error, as shown in the following example:

[ResponseCache(Duration = 0, Location = ResponseCacheLocation.None, NoStore = true)]
public class MyStatusCode2Model : PageModel
{
    public string RequestId { get; set; }
    public bool ShowRequestId => !string.IsNullOrEmpty(RequestId);

    public string ErrorStatusCode { get; set; }

    public string OriginalURL { get; set; }
    public bool ShowOriginalURL => !string.IsNullOrEmpty(OriginalURL);

    public void OnGet(string code)
    {
        RequestId = Activity.Current?.Id ?? HttpContext.TraceIdentifier;
        ErrorStatusCode = code;

        var statusCodeReExecuteFeature = HttpContext.Features.Get<
                                               IStatusCodeReExecuteFeature>();
        if (statusCodeReExecuteFeature != null)
        {
            OriginalURL =
                statusCodeReExecuteFeature.OriginalPathBase
                + statusCodeReExecuteFeature.OriginalPath
                + statusCodeReExecuteFeature.OriginalQueryString;
        }
    }
}

Ein Razor Pages-Beispiel finden Sie unter Pages/MyStatusCode2.cshtml in der Beispiel-App.For a Razor Pages example, see Pages/MyStatusCode2.cshtml in the sample app.

Um UseStatusCodePages in der Beispiel-App zu testen, entfernen Sie die Kommentare aus webBuilder.UseStartup<StartupSCreX>(); in Program.cs.To test UseStatusCodePages in the sample app, remove the comments from webBuilder.UseStartup<StartupSCreX>(); in Program.cs.

Deaktivieren von StatuscodeseitenDisable status code pages

Verwenden Sie das Attribut [SkipStatusCodePages], um Statuscodeseiten für einen MVC-Controller oder eine MVC-Aktionsmethode zu deaktivieren.To disable status code pages for an MVC controller or action method, use the [SkipStatusCodePages] attribute.

Verwenden Sie IStatusCodePagesFeature, um Statuscodeseiten für bestimmte Anforderungen in der Handlermethode von Razor Pages oder in einem MVC-Controller zu deaktivieren:To disable status code pages for specific requests in a Razor Pages handler method or in an MVC controller, use IStatusCodePagesFeature:

public void OnGet()
{
    // using Microsoft.AspNetCore.Diagnostics;
    var statusCodePagesFeature = HttpContext.Features.Get<IStatusCodePagesFeature>();

    if (statusCodePagesFeature != null)
    {
        statusCodePagesFeature.Enabled = false;
    }
}

AusnahmebehandlungscodeException-handling code

Code auf Seiten zur Ausnahmebehandlung kann ebenfalls Ausnahmen auslösen.Code in exception handling pages can also throw exceptions. Produktionsfehlerseiten sollten gründlich getestet werden. Achten Sie darauf, dabei keine eigenen Ausnahmen auszulösen.Production error pages should be tested thoroughly and take extra care to avoid throwing exceptions of their own.

AntwortheaderResponse headers

Nachdem die Header für eine Antwort gesendet wurden:Once the headers for a response are sent:

  • Die App kann den Statuscode der Antwort nicht ändern.The app can't change the response's status code.
  • Weder Ausnahmeseiten noch Handler können ausgeführt werden.Any exception pages or handlers can't run. Die Antwort muss abgeschlossen oder die Verbindung unterbrochen werden.The response must be completed or the connection aborted.

Sichere AusnahmebehandlungServer exception handling

Neben der Ausnahmebehandlungslogik in einer App kann die HTTP-Serverimplementierung einige Ausnahmebehandlungen durchführen.In addition to the exception handling logic in an app, the HTTP server implementation can handle some exceptions. Wenn der Server eine Ausnahme erfasst, bevor die Antwortheader gesendet werden, sendet der Server die Antwort 500 - Internal Server Error ohne Antworttext.If the server catches an exception before response headers are sent, the server sends a 500 - Internal Server Error response without a response body. Wenn der Server eine Ausnahme auffängt, nachdem die Antwortheader gesendet wurden, schließt der Server die Verbindung.If the server catches an exception after response headers are sent, the server closes the connection. Anforderungen, die nicht von der App verarbeitet werden, werden vom Server verarbeitet.Requests that aren't handled by the app are handled by the server. Jede Ausnahme, die bei der Anforderungsverarbeitung durch den Server auftritt, wird durch die Ausnahmebehandlung des Servers verarbeitet.Any exception that occurs when the server is handling the request is handled by the server's exception handling. Die benutzerdefinierten Fehlerseiten der App, Middleware zur Fehlerbehandlung und Filter haben keine Auswirkungen auf dieses Verhalten.The app's custom error pages, exception handling middleware, and filters don't affect this behavior.

Fehlerbehandlung während des StartsStartup exception handling

Nur auf Hostebene können Ausnahmen behandelt werden, die während des Starts einer App auftreten.Only the hosting layer can handle exceptions that take place during app startup. Der Host kann für das Erfassen von Startfehlern und Erfassen detaillierter Fehler konfiguriert werden.The host can be configured to capture startup errors and capture detailed errors.

Die Hostingebene kann nur dann für einen beim Start erfassten Fehler eine Fehlerseite anzeigen, wenn der Fehler nach der Bindung an die Hostadresse bzw. den Port auftritt.The hosting layer can show an error page for a captured startup error only if the error occurs after host address/port binding. Wenn die Bindung misslingt:If binding fails:

  • Die Hostebene protokolliert eine kritische Ausnahme.The hosting layer logs a critical exception.
  • Der DotNet-Prozess stürzt ab.The dotnet process crashes.
  • Wenn der HTTP-Server Kestrel heißt, wird keine Fehlerseite angezeigt.No error page is displayed when the HTTP server is Kestrel.

Wenn sie auf IIS (oder Azure App Service) oder IIS Express ausgeführt wird, wird ein Prozessfehler 502.5 vom ASP.NET Core-Modul zurückgegeben, wenn der Prozess nicht starten kann.When running on IIS (or Azure App Service) or IIS Express, a 502.5 - Process Failure is returned by the ASP.NET Core Module if the process can't start. Weitere Informationen finden Sie unter Problembehandlung bei ASP.NET Core in Azure App Service und IIS.For more information, see Problembehandlung bei ASP.NET Core in Azure App Service und IIS.

Datenbank-FehlerseiteDatabase error page

Der Ausnahmefilter der Datenbankentwicklerseite AddDatabaseDeveloperPageExceptionFilter erfasst datenbankbezogene Ausnahmen, die mithilfe von Entity Framework Core-Migrationen aufgelöst werden können.The Database developer page exception filter AddDatabaseDeveloperPageExceptionFilter captures database-related exceptions that can be resolved by using Entity Framework Core migrations. Wenn diese Ausnahmen auftreten, wird eine HTML-Antwort mit Details zu möglichen Aktionen zum Beheben des Problems generiert.When these exceptions occur, an HTML response is generated with details of possible actions to resolve the issue. Diese Seite ist nur in der Entwicklungsumgebung aktiviert.This page is enabled only in the Development environment. Der folgende Code wurde von den ASP.NET Core Razor Pages-Vorlagen generiert, als einzelne Benutzerkonten angegeben wurden:The following code was generated by the ASP.NET Core Razor Pages templates when individual user accounts were specified:

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<ApplicationDbContext>(options =>
        options.UseSqlServer(
            Configuration.GetConnectionString("DefaultConnection")));
    services.AddDatabaseDeveloperPageExceptionFilter();
    services.AddDefaultIdentity<IdentityUser>(options => options.SignIn.RequireConfirmedAccount = true)
        .AddEntityFrameworkStores<ApplicationDbContext>();
    services.AddRazorPages();
}

AusnahmefilterException filters

In MVC-Apps können Ausnahmefilter global oder auf einen Controller oder eine Aktion bezogen konfiguriert werden.In MVC apps, exception filters can be configured globally or on a per-controller or per-action basis. In Razor Pages-Apps können sie global oder auf ein Seitenmodell bezogen konfiguriert werden.In Razor Pages apps, they can be configured globally or per page model. Diese Filter verarbeiten jede nicht behandelte Ausnahme, die während der Ausführung eine Controlleraktion oder eines anderen Filters auftritt.These filters handle any unhandled exceptions that occur during the execution of a controller action or another filter. Weitere Informationen finden Sie unter Filter in ASP.NET Core.For more information, see Filter in ASP.NET Core.

Ausnahmefilter eignen sich zum Auffangen von Ausnahmen, die in MVC-Aktionen ausgelöst werden. Sie sind jedoch nicht so flexibel wie die integrierte Middleware für die Ausnahmebehandlung, UseExceptionHandler.Exception filters are useful for trapping exceptions that occur within MVC actions, but they're not as flexible as the built-in exception handling middleware, UseExceptionHandler. Es wird empfohlen, UseExceptionHandler zu verwenden, wenn Sie für die Fehlerbehandlung auf Grundlage einer ausgewählten MVC-Aktion eine andere Strategie auswählen müssen.We recommend using UseExceptionHandler, unless you need to perform error handling differently based on which MVC action is chosen.

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

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

    app.UseRouting();

    app.UseAuthorization();

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

ModellstatusfehlerModel state errors

Informationen zum Behandeln von Modellstatusfehlern finden Sie unter Modellbindung und Modellvalidierung.For information about how to handle model state errors, see Model binding and Model validation.

Zusätzliche RessourcenAdditional resources

Von Tom Dykstra und Steve SmithBy Tom Dykstra, and Steve Smith

Dieser Artikel beschreibt grundsätzliche Vorgehensweisen zur Behandlung von Fehlern in ASP.NET Core-Web-Apps.This article covers common approaches to handling errors in ASP.NET Core web apps. Weitere Informationen für Web-Apps finden Sie unter Fehlerbehandlung in ASP.NET Core-Web-APIs.See Fehlerbehandlung in ASP.NET Core-Web-APIs for web APIs.

Anzeigen oder Herunterladen von BeispielcodeView or download sample code. (Informationen zum Herunterladen.)(How to download.)

Seite mit Ausnahmen für EntwicklerDeveloper Exception Page

Die Seite mit Ausnahmen für Entwickler enthält ausführliche Informationen zu Anforderungsausnahmen.The Developer Exception Page displays detailed information about request exceptions. Die ASP.NET Core-Vorlagen generieren den folgenden Code:The ASP.NET Core templates generate the following code:

if (env.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}
else
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

Der vorangehende Code aktiviert die Seite mit Ausnahmen für Entwickler, wenn die App in der Entwicklungsumgebung ausgeführt wird.The preceding code enables the developer exception page when the app is running in the Development environment.

Die Vorlagen platzieren UseDeveloperExceptionPage vor jeder Middleware, sodass Ausnahmen in der nachfolgenden Middleware abgefangen werden.The templates place UseDeveloperExceptionPage before any middleware so exceptions are caught in the middleware that follows.

Der vorangehende Code aktiviert die Seite mit Ausnahmen für Entwickler nur dann, wenn die App in der Entwicklungsumgebung ausgeführt wird.The preceding code enables the Developer Exception Page only when the app is running in the Development environment. Bei Ausführung der App in der Produktionsumgebung sollten keine detaillierten Informationen zu den Ausnahmen öffentlich angezeigt werden.Detailed exception information should not be displayed publicly when the app runs in production. Weitere Informationen zum Konfigurieren der Umgebungen finden Sie unter Verwenden von mehreren Umgebungen in ASP.NET Core.For more information on configuring environments, see Verwenden von mehreren Umgebungen in ASP.NET Core.

Die Seite mit Ausnahmen für Entwickler enthält die folgenden Informationen zu der Ausnahme und der Anforderung:The Developer Exception Page includes the following information about the exception and the request:

  • StapelüberwachungStack trace
  • Abfragezeichenfolgeparameter, sofern vorhandenQuery string parameters if any
  • Cookies, sofern vorhandenCookies if any
  • HeaderHeaders

Seite „Ausnahmehandler“Exception handler page

Um eine benutzerdefinierte Fehlerbehandlung für die Produktionsumgebung zu konfigurieren, verwenden Sie Middleware zur Ausnahmebehandlung.To configure a custom error handling page for the Production environment, use the Exception Handling Middleware. Die Middleware:The middleware:

  • Dient zum Abfangen und Protokollieren von Ausnahmen.Catches and logs exceptions.
  • Führt die Anforderung für die angegebene Seite oder den Controller in einer anderen Pipeline erneut aus.Re-executes the request in an alternate pipeline for the page or controller indicated. Die Anforderung wird nicht erneut ausgeführt, wenn die Antwort gestartet wurde.The request isn't re-executed if the response has started. Der von der Vorlage generierte Code führt die Anforderung erneut mit /Error aus.The template generated code re-executes the request to /Error.

Im folgenden Beispiel fügt UseExceptionHandler die Middleware zur Ausnahmebehandlung in Nichtentwicklungsumgebungen hinzu:In the following example, UseExceptionHandler adds the Exception Handling Middleware in non-Development environments:

if (env.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}
else
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

Die Razor Pages-App-Vorlage stellt im Ordner Pages eine Fehlerseite ( .cshtml) und PageModel-Klasse (ErrorModel) bereit.The Razor Pages app template provides an Error page (.cshtml) and PageModel class (ErrorModel) in the Pages folder. Die Projektvorlage einer MVC-App enthält eine Fehleraktionsmethode und die Ansicht „Fehler“ im Home-Controller.For an MVC app, the project template includes an Error action method and an Error view in the Home controller.

Markieren Sie die Aktionsmethode für die Fehlerbehandlung nicht mit HTTP-Methodenattributen wie HttpGet.Don't mark the error handler action method with HTTP method attributes, such as HttpGet. Durch explizite Verben könnte bei einigen Anforderungen verhindert werden, dass diese Methode zum Einsatz kommt.Explicit verbs prevent some requests from reaching the method. Lassen Sie den anonymen Zugriff auf die Methode zu, wenn nicht authentifizierten Benutzern die Fehleransicht angezeigt werden soll.Allow anonymous access to the method if unauthenticated users should see the error view.

Zugreifen auf die AusnahmeAccess the exception

Verwenden Sie IExceptionHandlerPathFeature, um auf die Ausnahme oder den Pfad der ursprünglichen Anforderung in einem Controller für die Fehlerbehandlung oder auf einer Seite zuzugreifen:Use IExceptionHandlerPathFeature to access the exception and the original request path in an error handler controller or page:

[ResponseCache(Duration = 0, Location = ResponseCacheLocation.None, NoStore = true)]
public class ErrorModel : PageModel
{
    public string RequestId { get; set; }
    public bool ShowRequestId => !string.IsNullOrEmpty(RequestId);
    public string ExceptionMessage { get; set; }

    public void OnGet()
    {
        RequestId = Activity.Current?.Id ?? HttpContext.TraceIdentifier;

        var exceptionHandlerPathFeature =
            HttpContext.Features.Get<IExceptionHandlerPathFeature>();
        if (exceptionHandlerPathFeature?.Error is FileNotFoundException)
        {
            ExceptionMessage = "File error thrown";
        }
        if (exceptionHandlerPathFeature?.Path == "/index")
        {
            ExceptionMessage += " from home page";
        }
    }
}

Warnung

Stellen Sie Clients keine vertraulichen Fehlerinformationen bereit.Do not serve sensitive error information to clients. Die Bereitstellung von Fehlern ist ein Sicherheitsrisiko.Serving errors is a security risk.

Legen Sie die Umgebung auf Produktionen fest, und erzwingen Sie eine Ausnahme, um die vorherige Seite zur Ausnahmebehandlung zu aktivieren.To trigger the preceding exception handling page, set the environment to productions and force an exception.

Lambda-Ausdruck für AusnahmehandlerException handler lambda

Eine Alternative zu einer benutzerdefinierten Ausnahmebehandlungsseite ist das Angeben eines Lambda-Ausdrucks für UseExceptionHandler.An alternative to a custom exception handler page is to provide a lambda to UseExceptionHandler. Die Verwendung eines Lambda-Ausdrucks ermöglicht den Zugriff auf den Fehler, bevor die Antwort zurückgegeben wird.Using a lambda allows access to the error before returning the response.

Hier ist ein Beispiel der Verwendung eines Lambda-Ausdrucks für die Ausnahmebehandlung:Here's an example of using a lambda for exception handling:

if (env.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}
else
{
   app.UseExceptionHandler(errorApp =>
   {
        errorApp.Run(async context =>
        {
            context.Response.StatusCode = (int) HttpStatusCode.InternalServerError;
            context.Response.ContentType = "text/html";

            await context.Response.WriteAsync("<html lang=\"en\"><body>\r\n");
            await context.Response.WriteAsync("ERROR!<br><br>\r\n");

            var exceptionHandlerPathFeature = 
                context.Features.Get<IExceptionHandlerPathFeature>();

            if (exceptionHandlerPathFeature?.Error is FileNotFoundException)
            {
                await context.Response.WriteAsync("File error thrown!<br><br>\r\n");
            }

            await context.Response.WriteAsync("<a href=\"/\">Home</a><br>\r\n");
            await context.Response.WriteAsync("</body></html>\r\n");
            await context.Response.WriteAsync(new string(' ', 512)); // IE padding
        });
    });
    app.UseHsts();
}

Im vorangehenden Code wird await context.Response.WriteAsync(new string(' ', 512)); hinzugefügt, sodass der Internet Explorer-Browser die Fehlermeldung anstelle einer IE-Fehlermeldung anzeigt.In the preceding code, await context.Response.WriteAsync(new string(' ', 512)); is added so the Internet Explorer browser displays the error message rather than an IE error message. Weitere Informationen finden Sie in diesem GitHub-Issue.For more information, see this GitHub issue.

Warnung

Stellen Sie keine vertraulichen Fehlerinformationen aus IExceptionHandlerFeature oder IExceptionHandlerPathFeature für Clients bereit.Do not serve sensitive error information from IExceptionHandlerFeature or IExceptionHandlerPathFeature to clients. Die Bereitstellung von Fehlern ist ein Sicherheitsrisiko.Serving errors is a security risk.

Um in der Beispiel-App das Ergebnis des Lambda-Ausdrucks für die Ausnahmebehandlung anzuzeigen, verwenden Sie die Präprozessordirektiven ProdEnvironment und ErrorHandlerLambda, und wählen Sie auf der Startseite Ausnahme auslösen aus.To see the result of the exception handling lambda in the sample app, use the ProdEnvironment and ErrorHandlerLambda preprocessor directives, and select Trigger an exception on the home page.

UseStatusCodePagesUseStatusCodePages

Ihre ASP.NET Core-App stellt für HTTP-Statuscodes wie 404 – Nicht gefunden standardmäßig keine Statuscodeseite zur Verfügung.By default, an ASP.NET Core app doesn't provide a status code page for HTTP status codes, such as 404 - Not Found. Die App gibt einen Statuscode und einen leeren Antworttext zurück.The app returns a status code and an empty response body. Verwenden Sie zum Bereitstellen von Statuscodeseiten Middleware für Statuscodeseiten.To provide status code pages, use Status Code Pages middleware.

Die Middleware wird vom Paket Microsoft.AspNetCore.Diagnostics zur Verfügung gestellt.The middleware is made available by the Microsoft.AspNetCore.Diagnostics package.

Um für gängige Statuscodes einfache Handler im Textformat zu aktivieren, rufen Sie in der Startup.Configure-Methode UseStatusCodePages auf:To enable default text-only handlers for common error status codes, call UseStatusCodePages in the Startup.Configure method:

app.UseStatusCodePages();

Rufen Sie UseStatusCodePages vor Middleware zur Anforderungsverarbeitung auf (z.B. Middleware für statische Dateien und MVC-Middleware).Call UseStatusCodePages before request handling middleware (for example, Static File Middleware and MVC Middleware).

Wenn UseStatusCodePages nicht verwendet wird, wird beim Navigieren zu einer URL ohne Endpunkt eine browserabhängige Fehlermeldung zurückgegeben, die angibt, dass der Endpunkt nicht gefunden werden kann.When UseStatusCodePages isn't used, navigating to a URL without an endpoint returns a browser dependent error message indicating the endpoint can't be found. Navigieren Sie zum Beispiel zu Home/Privacy2.For example, navigating to Home/Privacy2. Wenn UseStatusCodePages aufgerufen wird, gibt der Browser Folgendes zurück:When UseStatusCodePages is called, the browser returns:

Status Code: 404; Not Found

UseStatusCodePages mit FormatzeichenfolgeUseStatusCodePages with format string

Um den Inhaltstyp und Text der Antwort anzupassen, verwenden Sie die Überladung von UseStatusCodePages, die einen Inhaltstyp und eine Formatierungszeichenfolge erfordert:To customize the response content type and text, use the overload of UseStatusCodePages that takes a content type and format string:

app.UseStatusCodePages(
    "text/plain", "Status code page, status code: {0}");            

UseStatusCodePages mit Lambda-AusdruckUseStatusCodePages with lambda

Um benutzerdefinierten Code für die Fehlerbehandlung und das Schreiben von Antworten anzugeben, verwenden Sie die Überladung von UseStatusCodePages, die einen Lambda-Ausdruck verwendet:To specify custom error-handling and response-writing code, use the overload of UseStatusCodePages that takes a lambda expression:


app.UseStatusCodePages(async context =>
{
    context.HttpContext.Response.ContentType = "text/plain";

    await context.HttpContext.Response.WriteAsync(
        "Status code page, status code: " + 
        context.HttpContext.Response.StatusCode);
});

UseStatusCodePagesWithRedirectsUseStatusCodePagesWithRedirects

Die Erweiterungsmethode UseStatusCodePagesWithRedirects:The UseStatusCodePagesWithRedirects extension method:

  • Sendet den Statuscode 302 Found (Gefunden) an den Client.Sends a 302 - Found status code to the client.
  • Der Client wird an den in der URL-Vorlage angegebenen Standort umgeleitet.Redirects the client to the location provided in the URL template.
app.UseStatusCodePagesWithRedirects("/StatusCode?code={0}");

Die URL-Vorlage kann, wie im Beispiel gezeigt, einen {0}-Platzhalter für den Statuscode enthalten.The URL template can include a {0} placeholder for the status code, as shown in the example. Wenn die URL-Vorlage mit einer Tilde (~) beginnt, wird ~ durch die Angabe für PathBase der App ersetzt.If the URL template starts with ~ (tilde), the ~ is replaced by the app's PathBase. Wenn Sie in der App auf einen Endpunkt verweisen, müssen Sie eine MVC-Ansicht oder Razor-Seite für den Endpunkt erstellen.If you point to an endpoint within the app, create an MVC view or Razor page for the endpoint. Ein Razor Pages-Beispiel finden Sie unter Pages/StatusCode.cshtml in der Beispiel-App.For a Razor Pages example, see Pages/StatusCode.cshtml in the sample app.

Diese Methode wird häufig verwendet, wenn die App Folgendes tun soll:This method is commonly used when the app:

  • Den Client an einen anderen Endpunkt umleiten, in der Regel in Fällen, in denen eine andere App den Fehler verarbeitet.Should redirect the client to a different endpoint, usually in cases where a different app processes the error. Für Web-Apps gibt die Adressleiste des Browsers des Clients den umgeleiteten Endpunkt wieder.For web apps, the client's browser address bar reflects the redirected endpoint.
  • Den ursprünglichen Statuscode mit der anfänglichen Umleitungsantwort nicht beibehalten und zurückgeben.Shouldn't preserve and return the original status code with the initial redirect response.

UseStatusCodePagesWithReExecuteUseStatusCodePagesWithReExecute

Die Erweiterungsmethode UseStatusCodePagesWithReExecute:The UseStatusCodePagesWithReExecute extension method:

  • Gibt den ursprünglichen Statuscode an den Client zurück.Returns the original status code to the client.
  • Generiert den Antworttext durch die erneute Ausführung der Anforderungspipeline mithilfe eines alternativen Pfads.Generates the response body by re-executing the request pipeline using an alternate path.
app.UseStatusCodePagesWithReExecute("/StatusCode","?code={0}");

Wenn Sie in der App auf einen Endpunkt verweisen, müssen Sie eine MVC-Ansicht oder Razor-Seite für den Endpunkt erstellen.If you point to an endpoint within the app, create an MVC view or Razor page for the endpoint. Stellen Sie sicher, dass UseStatusCodePagesWithReExecute vor UseRouting platziert wird, damit die Anforderung an die Statusseite umgeleitet werden kann.Ensure UseStatusCodePagesWithReExecute is placed before UseRouting so the request can be rerouted to the status page. Ein Razor Pages-Beispiel finden Sie unter Pages/StatusCode.cshtml in der Beispiel-App.For a Razor Pages example, see Pages/StatusCode.cshtml in the sample app.

Diese Methode wird häufig verwendet, wenn die App Folgendes tun soll:This method is commonly used when the app should:

  • Die Anforderung ohne Umleitung an einen anderen Endpunkt verarbeiten.Process the request without redirecting to a different endpoint. Für Web-Apps gibt die Adressleiste des Browsers des Clients den ursprünglich angeforderten Endpunkt wieder.For web apps, the client's browser address bar reflects the originally requested endpoint.
  • Den ursprünglichen Statuscode mit der Antwort beibehalten und zurückgeben.Preserve and return the original status code with the response.

Die Vorlagen für URL und Abfragezeichenfolgen können für den Statuscode einen Platzhalter ({0}) enthalten.The URL and query string templates may include a placeholder ({0}) for the status code. Die URL-Vorlage muss mit einem Schrägstrich (/) beginnen.The URL template must start with a slash (/). Wenn Sie im Pfad einen Platzhalter verwenden, vergewissern Sie sich, dass der Endpunkt (Seite oder Controller) das Pfadsegment verarbeiten kann.When using a placeholder in the path, confirm that the endpoint (page or controller) can process the path segment. Eine Razor Page für Fehler sollte z. B. den Wert des optionalen Pfadsegments mit der @page-Anweisung akzeptieren:For example, a Razor Page for errors should accept the optional path segment value with the @page directive:

@page "{code?}"

Der Endpunkt, der den Fehler verarbeitet, kann die ursprüngliche URL abrufen, die den Fehler generiert hat (siehe folgendes Beispiel):The endpoint that processes the error can get the original URL that generated the error, as shown in the following example:

var statusCodeReExecuteFeature = HttpContext.Features.Get<IStatusCodeReExecuteFeature>();
if (statusCodeReExecuteFeature != null)
{
    OriginalURL =
        statusCodeReExecuteFeature.OriginalPathBase
        + statusCodeReExecuteFeature.OriginalPath
        + statusCodeReExecuteFeature.OriginalQueryString;
}

Markieren Sie die Aktionsmethode für die Fehlerbehandlung nicht mit HTTP-Methodenattributen wie HttpGet.Don't mark the error handler action method with HTTP method attributes, such as HttpGet. Durch explizite Verben könnte bei einigen Anforderungen verhindert werden, dass diese Methode zum Einsatz kommt.Explicit verbs prevent some requests from reaching the method. Lassen Sie den anonymen Zugriff auf die Methode zu, wenn nicht authentifizierten Benutzern die Fehleransicht angezeigt werden soll.Allow anonymous access to the method if unauthenticated users should see the error view.

Deaktivieren von StatuscodeseitenDisable status code pages

Verwenden Sie das Attribut [SkipStatusCodePages], um Statuscodeseiten für einen MVC-Controller oder eine MVC-Aktionsmethode zu deaktivieren.To disable status code pages for an MVC controller or action method, use the [SkipStatusCodePages] attribute.

Verwenden Sie IStatusCodePagesFeature, um Statuscodeseiten für bestimmte Anforderungen in der Handlermethode von Razor Pages oder in einem MVC-Controller zu deaktivieren:To disable status code pages for specific requests in a Razor Pages handler method or in an MVC controller, use IStatusCodePagesFeature:

var statusCodePagesFeature = HttpContext.Features.Get<IStatusCodePagesFeature>();

if (statusCodePagesFeature != null)
{
    statusCodePagesFeature.Enabled = false;
}

AusnahmebehandlungscodeException-handling code

Code auf Seiten zur Ausnahmebehandlung kann Ausnahmen auslösen.Code in exception handling pages can throw exceptions. Es ist häufig empfehlenswert, wenn Produktionsfehlerseiten nur statische Inhalte aufweisen.It's often a good idea for production error pages to consist of purely static content.

AntwortheaderResponse headers

Nachdem die Header für eine Antwort gesendet wurden:Once the headers for a response are sent:

  • Die App kann den Statuscode der Antwort nicht ändern.The app can't change the response's status code.
  • Weder Ausnahmeseiten noch Handler können ausgeführt werden.Any exception pages or handlers can't run. Die Antwort muss abgeschlossen oder die Verbindung unterbrochen werden.The response must be completed or the connection aborted.

Sichere AusnahmebehandlungServer exception handling

Neben der Ausnahmebehandlungslogik in Ihrer App kann die HTTP-Serverimplementierung einige Ausnahmebehandlungen durchführen.In addition to the exception handling logic in your app, the HTTP server implementation can handle some exceptions. Wenn der Server eine Ausnahme erfasst, bevor die Antwortheader gesendet werden, sendet der Server die Antwort 500 – Interner Serverfehler ohne Antworttext.If the server catches an exception before response headers are sent, the server sends a 500 - Internal Server Error response without a response body. Wenn der Server eine Ausnahme auffängt, nachdem die Antwortheader gesendet wurden, schließt der Server die Verbindung.If the server catches an exception after response headers are sent, the server closes the connection. Anforderungen, die nicht von Ihrer App verarbeitet werden, werden vom Server verarbeitet.Requests that aren't handled by your app are handled by the server. Jede Ausnahme, die bei der Anforderungsverarbeitung durch den Server auftritt, wird durch die Ausnahmebehandlung des Servers verarbeitet.Any exception that occurs when the server is handling the request is handled by the server's exception handling. Die benutzerdefinierten Fehlerseiten der App, Middleware zur Fehlerbehandlung und Filter haben keine Auswirkungen auf dieses Verhalten.The app's custom error pages, exception handling middleware, and filters don't affect this behavior.

Fehlerbehandlung während des StartsStartup exception handling

Nur auf Hostebene können Ausnahmen behandelt werden, die während des Starts einer App auftreten.Only the hosting layer can handle exceptions that take place during app startup. Der Host kann für das Erfassen von Startfehlern und Erfassen detaillierter Fehler konfiguriert werden.The host can be configured to capture startup errors and capture detailed errors.

Die Hostingebene kann nur dann für einen beim Start erfassten Fehler eine Fehlerseite anzeigen, wenn der Fehler nach der Bindung an die Hostadresse bzw. den Port auftritt.The hosting layer can show an error page for a captured startup error only if the error occurs after host address/port binding. Wenn die Bindung misslingt:If binding fails:

  • Die Hostebene protokolliert eine kritische Ausnahme.The hosting layer logs a critical exception.
  • Der DotNet-Prozess stürzt ab.The dotnet process crashes.
  • Wenn der HTTP-Server Kestrel heißt, wird keine Fehlerseite angezeigt.No error page is displayed when the HTTP server is Kestrel.

Wenn sie auf IIS (oder Azure App Service) oder IIS Express ausgeführt wird, wird ein Prozessfehler 502.5 vom ASP.NET Core-Modul zurückgegeben, wenn der Prozess nicht starten kann.When running on IIS (or Azure App Service) or IIS Express, a 502.5 - Process Failure is returned by the ASP.NET Core Module if the process can't start. Weitere Informationen finden Sie unter Problembehandlung bei ASP.NET Core in Azure App Service und IIS.For more information, see Problembehandlung bei ASP.NET Core in Azure App Service und IIS.

Datenbank-FehlerseiteDatabase error page

Die Middleware „Datenbank-Fehlerseite“ erfasst datenbankbezogene Ausnahmen, die mithilfe von Entity Framework-Migrationen aufgelöst werden können.Database Error Page Middleware captures database-related exceptions that can be resolved by using Entity Framework migrations. Wenn diese Ausnahmen auftreten, wird eine HTML-Antwort mit Details zu möglichen Aktionen zum Beheben des Problems generiert.When these exceptions occur, an HTML response with details of possible actions to resolve the issue is generated. Diese Seite darf nur in der Entwicklungsumgebung aktiviert werden.This page should be enabled only in the Development environment. Aktivieren Sie die Seite, indem Sie Startup.Configure Code hinzufügen:Enable the page by adding code to Startup.Configure:

if (env.IsDevelopment())
{
    app.UseDatabaseErrorPage();
}

UseDatabaseErrorPage benötigt das Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore-NuGet-Paket.UseDatabaseErrorPage requires the Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore NuGet package.

AusnahmefilterException filters

In MVC-Apps können Ausnahmefilter global oder auf einen Controller oder eine Aktion bezogen konfiguriert werden.In MVC apps, exception filters can be configured globally or on a per-controller or per-action basis. In Razor Pages-Apps können sie global oder auf ein Seitenmodell bezogen konfiguriert werden.In Razor Pages apps, they can be configured globally or per page model. Diese Filter verarbeiten jede nicht behandelte Ausnahme, die während der Ausführung eine Controlleraktion oder eines anderen Filters auftritt.These filters handle any unhandled exception that occurs during the execution of a controller action or another filter. Weitere Informationen finden Sie unter Filter in ASP.NET Core.For more information, see Filter in ASP.NET Core.

Tipp

Ausnahmefilter eignen sich zum Auffangen von Ausnahmen, die in MVC-Aktionen auftreten. Sie sind jedoch nicht so flexibel wie Middleware für die Ausnahmebehandlung.Exception filters are useful for trapping exceptions that occur within MVC actions, but they're not as flexible as the Exception Handling Middleware. Es wird empfohlen, die Middleware zu verwenden.We recommend using the middleware. Verwenden Sie Filter nur dann, wenn Sie für die Fehlerbehandlung auf Grundlage einer ausgewählten MVC-Aktion eine andere Strategie wählen müssen.Use filters only where you need to perform error handling differently based on which MVC action is chosen.

ModellstatusfehlerModel state errors

Informationen zum Behandeln von Modellstatusfehlern finden Sie unter Modellbindung und Modellvalidierung.For information about how to handle model state errors, see Model binding and Model validation.

Zusätzliche RessourcenAdditional resources