Behandeln von Fehlern in ASP.NET Core-APIs

Hinweis

Dies ist nicht die neueste Version dieses Artikels. Die aktuelle Version finden Sie in der .NET 10-Version dieses Artikels.

Warnung

Diese Version von ASP.NET Core wird nicht mehr unterstützt. Weitere Informationen finden Sie in der .NET- und .NET Core-Supportrichtlinie. Informationen zum aktuellen Release finden Sie in der .NET 9-Version dieses Artikels.

Minimale APIs

In diesem Artikel wird beschrieben, wie Fehler in ASP.NET Core-APIs behandelt werden. Die Dokumentation für minimale APIs ist ausgewählt. Um die Dokumentation für controllerbasierte APIs anzuzeigen, wählen Sie die Registerkarte "Controller" aus. Blazor Anleitungen zur Fehlerbehandlung finden Sie unter Behandeln von Fehlern in ASP.NET Core-AppsBlazor.

Controller

In diesem Artikel wird beschrieben, wie Fehler in ASP.NET Core-APIs behandelt werden. Die Dokumentation für controllerbasierte APIs ist ausgewählt. Um die Dokumentation für minimale APIs anzuzeigen, wählen Sie die Registerkarte "Minimale APIs" aus. Blazor Anleitungen zur Fehlerbehandlung finden Sie unter "Behandeln von Fehlern in ASP.NET Core-AppsBlazor".

Seite "Entwickler exception"

Auf der Entwickler ausnahmeseite werden detaillierte Informationen zu nicht behandelten Anforderungs ausnahmen angezeigt. Es wird DeveloperExceptionPageMiddleware verwendet, um synchrone und asynchrone Ausnahmen von der HTTP-Pipeline zu erfassen und Fehlerantworten zu generieren. Die Entwickler exception page runs early in the middleware pipeline, so that it can catch unhandled exceptions thrown in middleware that follows.

ASP.NET Core-Apps aktivieren standardmäßig die Entwickler ausnahmeseite, wenn beides:

• Wird in der Entwicklungsumgebung ausgeführt.
• Die App wurde mit den aktuellen Vorlagen erstellt, d. h. mithilfe WebApplication.CreateBuildervon .

Apps, die mithilfe früherer Vorlagen erstellt wurden, WebHost.CreateDefaultBuilderkönnen die Entwickler-Ausnahmeseite durch Aufrufen app.UseDeveloperExceptionPageaktivieren.

Warnung

Aktivieren Sie die Entwickler exception Page nicht, es sei denn, die App wird in der Entwicklungsumgebung ausgeführt. Geben Sie keine detaillierten Ausnahmeinformationen öffentlich frei, wenn die App in der Produktion ausgeführt wird. Weitere Informationen zum Konfigurieren von Umgebungen finden Sie unter ASP.NET Core-Laufzeitumgebungen.

Die Entwickler exception page can include the following information about the exception and the request:

• Stapelüberwachung
• Abfragezeichenfolgenparameter( falls vorhanden)
• Cookies, falls vorhanden
• Headers
• Endpunktmetadaten( falls vorhanden)

Die Entwickler exception page isn't guaranteed to provide any information. Verwenden Sie die Protokollierung für vollständige Fehlerinformationen.

Die folgende Abbildung zeigt eine Beispielseite für Entwicklerausnahmen mit Animation, um die Registerkarten und die angezeigten Informationen anzuzeigen:

Als Reaktion auf eine Anforderung mit einem Accept: text/plain Header gibt die Entwickler-Ausnahmeseite nur Text anstelle von HTML zurück. Beispiel:

Status: 500 Internal Server Error
Time: 9.39 msSize: 480 bytes
FormattedRawHeadersRequest
Body
text/plain; charset=utf-8, 480 bytes
System.InvalidOperationException: Sample Exception
   at WebApplicationMinimal.Program.<>c.<Main>b__0_0() in C:\Source\WebApplicationMinimal\Program.cs:line 12
   at lambda_method1(Closure, Object, HttpContext)
   at Microsoft.AspNetCore.Diagnostics.DeveloperExceptionPageMiddlewareImpl.Invoke(HttpContext context)

HEADERS
=======
Accept: text/plain
Host: localhost:7267
traceparent: 00-0eab195ea19d07b90a46cd7d6bf2f

Minimale APIs

So zeigen Sie die Entwickler ausnahmeseite in einer minimalen API an:

• Führen Sie die Beispiel-App in der Entwicklungsumgebung aus.
• Wechseln Sie zum /exception Endpunkt.

Dieser Abschnitt bezieht sich auf die folgende Beispiel-App, um Möglichkeiten zum Behandeln von Ausnahmen in einer minimalen API zu veranschaulichen. Es löst eine Ausnahme aus, wenn der Endpunkt /exception angefordert wird:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/exception", () => 
{
    throw new InvalidOperationException("Sample Exception");
});

app.MapGet("/", () => "Test by calling /exception");

app.Run();

Controller

So zeigen Sie die Entwickler ausnahmeseite in einer controllerbasierten API an:

• Fügen Sie der controllerbasierten API die folgende Controlleraktion hinzu. Die Aktion löst eine Ausnahme aus, wenn der Endpunkt angefordert wird.

  [HttpGet("Throw")]
  public IActionResult Throw() =>
      throw new Exception("Sample exception.");
  

• Führen Sie die App in der Entwicklungsumgebung aus.

• Wechseln Sie zum endpunkt, der von der Controlleraktion definiert wurde.

Ausnahmehandler

Verwenden Sie in Nicht-Entwicklungsumgebungen die Ausnahmehandler-Middleware , um eine Fehlernutzlast zu erzeugen.

Minimale APIs

Rufen Sie Exception Handler Middlewarezum Konfigurieren des Aufrufs UseExceptionHandlerauf. Der folgende Code ändert beispielsweise die App so, dass sie mit einer RFC 7807-kompatiblen Nutzlast auf den Client reagiert. Weitere Informationen finden Sie im Abschnitt "Problemdetails " weiter unten in diesem Artikel.

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.UseExceptionHandler(exceptionHandlerApp 
    => exceptionHandlerApp.Run(async context 
        => await Results.Problem()
                     .ExecuteAsync(context)));

app.MapGet("/exception", () => 
{
    throw new InvalidOperationException("Sample Exception");
});

app.MapGet("/", () => "Test by calling /exception");

app.Run();

Controller

1. Rufen Program.csSie in , um UseExceptionHandler die Middleware für die Ausnahmebehandlung hinzuzufügen:

   var app = builder.Build();
   
   app.UseHttpsRedirection();
   
   if (!app.Environment.IsDevelopment())
   {
       app.UseExceptionHandler("/error");
   }
   
   app.UseAuthorization();
   
   app.MapControllers();
   
   app.Run();
   

2. Konfigurieren Sie eine Controlleraktion, um auf die /error Route zu reagieren:

   [Route("/error")]
   public IActionResult HandleError() =>
       Problem();
   

Die vorangehende HandleError Aktion sendet eine RFC 7807-kompatible Nutzlast an den Client.

Warnung

Markieren Sie die Fehlerhandleraktionsmethode nicht mit HTTP-Methodenattributen, z HttpGet. B. . Explizite Verben verhindern, dass einige Anforderungen die Aktionsmethode erreichen.

Markieren Sie für Web-APIs, die Swagger / OpenAPI verwenden, die Fehlerhandleraktion mit dem Attribut [ApiExplorerSettings] und legen Sie dessen IgnoreApi Eigenschaft auf true. Diese Attributkonfiguration schließt die Fehlerhandleraktion aus der OpenAPI-Spezifikation der App aus:

[ApiExplorerSettings(IgnoreApi = true)]

Anonymen Zugriff auf die Methode zulassen, wenn nicht authentifizierte Benutzer den Fehler sehen sollten.

Client- und Serverfehlerantworten

Minimale APIs

Betrachten Sie die folgende Minimale API-App.

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/users/{id:int}", (int id) 
    => id <= 0 ? Results.BadRequest() : Results.Ok(new User(id)));

app.MapGet("/", () => "Test by calling /users/{id:int}");

app.Run();

public record User(int Id);

Der /users Endpunkt erzeugt 200 OK eine json Darstellung, User wenn id größer als 0ist, andernfalls einen 400 BAD REQUEST Statuscode ohne Antworttext. Weitere Informationen zum Erstellen einer Antwort finden Sie unter Erstellen von Antworten in minimalen API-Apps.

Die Status Code Pages middleware Konfiguration kann so konfiguriert werden, dass für alle HTTP-Clientantworten (400-) oder Server (499500 -) ein allgemeiner Textkörperinhalt erzeugt wird, 599 ist. Die Middleware wird durch Aufrufen der UseStatusCodePages-Erweiterungsmethode konfiguriert.

Im folgenden Beispiel wird die App beispielsweise so geändert, dass sie mit einer RFC 7807-kompatiblen Nutzlast für alle Client- und Serverantworten reagiert, einschließlich Routingfehlern (z 404 NOT FOUND. B. ). Weitere Informationen finden Sie im Abschnitt "Problemdetails ".

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.UseStatusCodePages(async statusCodeContext 
    => await Results.Problem(statusCode: statusCodeContext.HttpContext.Response.StatusCode)
                 .ExecuteAsync(statusCodeContext.HttpContext));

app.MapGet("/users/{id:int}", (int id) 
    => id <= 0 ? Results.BadRequest() : Results.Ok(new User(id)) );

app.MapGet("/", () => "Test by calling /users/{id:int}");

app.Run();

public record User(int Id);

Controller

Bei controllerbasierten APIs kann die Fehlerantwort auf eine der folgenden Arten konfiguriert werden:

1. Verwenden des Problemdetailseitediensts
2. Implementieren von ProblemDetailsFactory
3. Verwenden von ApiBehaviorOptions.ClientErrorMapping

Ein Fehlerergebnis wird als Ergebnis mit einem HTTP-Statuscode von 400 oder höher definiert. Bei Web-API-Controllern transformiert MVC ein Fehlerergebnis, um ein ProblemDetails.

Die automatische Erstellung einer ProblemDetails Für Fehlerstatuscodes ist standardmäßig aktiviert.

Problemdetails

Problemdetails sind nicht das einzige Antwortformat zur Beschreibung eines HTTP-API-Fehlers, sie werden jedoch häufig verwendet, um Fehler für HTTP-APIs zu melden.

Der Problemdetailsdienst implementiert die IProblemDetailsService Schnittstelle, die das Erstellen von Problemdetails in ASP.NET Core unterstützt. Die AddProblemDetails(IServiceCollection) Erweiterungsmethode bei IServiceCollection der Registrierung der Standardimplementierung IProblemDetailsService .

In ASP.NET Core-Apps generiert die folgende Middleware beim Aufruf Http-Antworten AddProblemDetails mit Problemdetails, außer wenn der Accept Anforderungs-HTTP-Header keinen der von der registrierten IProblemDetailsWriter (Standardeinstellung) unterstützten Inhaltstypen enthält: application/json

• ExceptionHandlerMiddleware: Generiert eine Antwort auf Problemdetails, wenn kein benutzerdefinierter Handler definiert ist.
• StatusCodePagesMiddleware: Generiert standardmäßig eine Antwort auf Problemdetails.
• DeveloperExceptionPageMiddleware: Generiert eine Antwort auf Problemdetails in der Entwicklung, wenn der Accept HTTP-Anforderungsheader nicht enthalten text/htmlist.

Minimale APIs

Minimale API-Apps können so konfiguriert werden, dass die Antwort auf Problemdetails für alle HTTP-Client- und Serverfehlerantworten generiert wird, die noch keinen Textinhalt haben , indem sie die AddProblemDetails Erweiterungsmethode verwenden.

Mit dem folgenden Code wird die App so konfiguriert, dass Problemdetails generiert werden:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddProblemDetails();

var app = builder.Build();

app.UseExceptionHandler();
app.UseStatusCodePages();

app.MapGet("/users/{id:int}", (int id) 
    => id <= 0 ? Results.BadRequest() : Results.Ok(new User(id)));

app.MapGet("/", () => "Test by calling /users/{id:int}");

app.Run();

public record User(int Id);

Weitere Informationen zur Verwendung AddProblemDetailsfinden Sie unter Problemdetails

IProblemDetailsService-Fallback

Gibt im folgenden Code einen Fehler zurück, wenn die Implementierung nicht in der httpContext.Response.WriteAsync("Fallback: An error occurred.") Lage ist, IProblemDetailsService eine ProblemDetails:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddProblemDetails();

var app = builder.Build();

app.UseExceptionHandler(exceptionHandlerApp =>
{
    exceptionHandlerApp.Run(async httpContext =>
    {
        var pds = httpContext.RequestServices.GetService<IProblemDetailsService>();
        if (pds == null
            || !await pds.TryWriteAsync(new() { HttpContext = httpContext }))
        {
            // Fallback behavior
            await httpContext.Response.WriteAsync("Fallback: An error occurred.");
        }
    });
});

app.MapGet("/exception", () =>
{
    throw new InvalidOperationException("Sample Exception");
});

app.MapGet("/", () => "Test by calling /exception");

app.Run();

Der vorherige Code:

• Schreibt eine Fehlermeldung mit dem Fallbackcode, wenn der problemDetailsService Fehler nicht geschrieben ProblemDetailswerden kann. Ein Endpunkt, auf dem der Accept-Anforderungsheader beispielsweise einen Medientyp angibt, der DefaulProblemDetailsWriter nicht unterstützt wird.
• Verwendet die Middleware des Ausnahmehandlers.

Das folgende Beispiel ähnelt dem vorherigen, mit der Ausnahme, dass es die Status Code Pages middleware.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddProblemDetails();

var app = builder.Build();

app.UseStatusCodePages(statusCodeHandlerApp =>
{
    statusCodeHandlerApp.Run(async httpContext =>
    {
        var pds = httpContext.RequestServices.GetService<IProblemDetailsService>();
        if (pds == null
            || !await pds.TryWriteAsync(new() { HttpContext = httpContext }))
        {
            // Fallback behavior
            await httpContext.Response.WriteAsync("Fallback: An error occurred.");
        }
    });
});

app.MapGet("/users/{id:int}", (int id) =>
{
    return id <= 0 ? Results.BadRequest() : Results.Ok(new User(id));
});

app.MapGet("/", () => "Test by calling /users/{id:int}");

app.Run();

public record User(int Id);

Controller

Problemdetails service

ASP.NET Core unterstützt das Erstellen von Problemdetails für HTTP-APIs mithilfe der IProblemDetailsService.

Der folgende Code konfiguriert die App so, dass eine Problemdetailseantwort für alle HTTP-Client- und Serverfehlerantworten generiert wird, die noch keinen Textinhalt haben:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddProblemDetails();

var app = builder.Build();

app.UseExceptionHandler();
app.UseStatusCodePages();

if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}

app.MapControllers();
app.Run();

Berücksichtigen Sie den API-Controller aus dem vorherigen Abschnitt, der zurückgibt BadRequest , wenn die Eingabe ungültig ist:

[Route("api/[controller]/[action]")]
[ApiController]
public class Values2Controller : ControllerBase
{
    // /api/values2/divide/1/2
    [HttpGet("{Numerator}/{Denominator}")]
    public IActionResult Divide(double Numerator, double Denominator)
    {
        if (Denominator == 0)
        {
            return BadRequest();
        }

        return Ok(Numerator / Denominator);
    }

    // /api/values2 /squareroot/4
    [HttpGet("{radicand}")]
    public IActionResult Squareroot(double radicand)
    {
        if (radicand < 0)
        {
            return BadRequest();
        }

        return Ok(Math.Sqrt(radicand));
    }
}

Eine Antwort auf Problemdetails wird mit dem vorherigen Code generiert, wenn eine der folgenden Bedingungen zutrifft:

• Es wird eine ungültige Eingabe bereitgestellt.
• Der URI hat keinen übereinstimmenden Endpunkt.
• Eine unbehandelte Ausnahme tritt auf.

Anpassen von Problemdetails mit CustomizeProblemDetails

Der folgende Code verwendet ProblemDetailsOptions zum Festlegen CustomizeProblemDetails:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

builder.Services.AddProblemDetails(options =>
        options.CustomizeProblemDetails = (context) =>
        {

            var mathErrorFeature = context.HttpContext.Features
                                                       .Get<MathErrorFeature>();
            if (mathErrorFeature is not null)
            {
                (string Detail, string Type) details = mathErrorFeature.MathError switch
                {
                    MathErrorType.DivisionByZeroError =>
                    ("Divison by zero is not defined.",
                                          "https://wikipedia.org/wiki/Division_by_zero"),
                    _ => ("Negative or complex numbers are not valid input.",
                                          "https://wikipedia.org/wiki/Square_root")
                };

                context.ProblemDetails.Type = details.Type;
                context.ProblemDetails.Title = "Bad Input";
                context.ProblemDetails.Detail = details.Detail;
            }
        }
    );

var app = builder.Build();

app.UseHttpsRedirection();

app.UseStatusCodePages();

app.UseAuthorization();

app.MapControllers();

app.Run();

Werkzeug ProblemDetailsFactory

MVC verwendet Microsoft.AspNetCore.Mvc.Infrastructure.ProblemDetailsFactory , um alle Instanzen von ProblemDetails und ValidationProblemDetails. Diese Factory wird für Folgendes verwendet:

• Clientfehlerantworten
• Fehlerantworten bei Überprüfungsfehlern
• ControllerBase.Problem und ControllerBase.ValidationProblem

Um die Problemdetails-Antwort anzupassen, registrieren Sie eine benutzerdefinierte Implementierung von ProblemDetailsFactory in Program.cs:

builder.Services.AddControllers();
builder.Services.AddTransient<ProblemDetailsFactory, SampleProblemDetailsFactory>();

Verwende ApiBehaviorOptions.ClientErrorMapping

Verwenden Sie die ClientErrorMapping Eigenschaft, um den Inhalt der ProblemDetails Antwort zu konfigurieren. Der folgende Code in Program.cs der Link Eigenschaft wird beispielsweise für 404 Antworten aktualisiert:

builder.Services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
        options.ClientErrorMapping[StatusCodes.Status404NotFound].Link =
            "https://httpstatuses.com/404";
    });

Zusätzliche Fehlerbehandlungsfeatures

Minimale APIs

Migration von Controllern zu minimalen APIs

Wenn Sie von controllerbasierten APIs zu minimalen APIs migrieren:

1. Ersetzen von Aktionsfiltern durch Endpunktfilter oder Middleware
2. Ersetzen der Modellüberprüfung durch manuelle Überprüfung oder benutzerdefinierte Bindung
3. Ersetzen von Ausnahmefiltern durch Middleware für die Ausnahmebehandlung
4. Konfigurieren von Problemdetails mithilfe konsistenter AddProblemDetails() Fehlerantworten

Gründe für die Verwendung der controllerbasierten Fehlerbehandlung

Berücksichtigen Sie bei Bedarf controllerbasierte APIs:

• Komplexe Modellüberprüfungsszenarien
• Zentralisierte Ausnahmebehandlung über mehrere Controller hinweg
• Feinkörnige Kontrolle über die Fehlerantwortformatierung
• Integration in MVC-Features wie Filter und Konventionen

Ausführliche Informationen zur controllerbasierten Fehlerbehandlung, einschließlich Validierungsfehlern, Anpassung von Problemen und Ausnahmefiltern, finden Sie in den Registerkartenabschnitten " Controller ".

Controller

Fehlerantwort bei Überprüfungsfehlern

Bei Web-API-Controllern antwortet MVC mit einem ValidationProblemDetails Antworttyp, wenn die Modellüberprüfung fehlschlägt. MVC verwendet die Ergebnisse, um InvalidModelStateResponseFactory die Fehlerantwort für einen Überprüfungsfehler zu erstellen. Im folgenden Beispiel wird die Standardfactory durch eine Implementierung ersetzt, die auch Formatierungsantworten als XML unterstützt, in Program.cs:

builder.Services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
        options.InvalidModelStateResponseFactory = context =>
            new BadRequestObjectResult(context.ModelState)
            {
                ContentTypes =
                {
                    // using static System.Net.Mime.MediaTypeNames;
                    Application.Json,
                    Application.Xml
                }
            };
    })
    .AddXmlSerializerFormatters();

Verwenden von Ausnahmen zum Ändern der Antwort

Der Inhalt der Antwort kann über eine benutzerdefinierte Ausnahme und einen Aktionsfilter von außerhalb des Controllers geändert werden:

1. Erstellen Sie einen bekannten Ausnahmetyp namens HttpResponseException:

   public class HttpResponseException : Exception
   {
       public HttpResponseException(int statusCode, object? value = null) =>
           (StatusCode, Value) = (statusCode, value);
   
       public int StatusCode { get; }
   
       public object? Value { get; }
   }
   

2. Erstellen eines Aktionsfilters mit dem Namen HttpResponseExceptionFilter:

   public class HttpResponseExceptionFilter : IActionFilter, IOrderedFilter
   {
       public int Order => int.MaxValue - 10;
   
       public void OnActionExecuting(ActionExecutingContext context) { }
   
       public void OnActionExecuted(ActionExecutedContext context)
       {
           if (context.Exception is HttpResponseException httpResponseException)
           {
               context.Result = new ObjectResult(httpResponseException.Value)
               {
                   StatusCode = httpResponseException.StatusCode
               };
   
               context.ExceptionHandled = true;
           }
       }
   }
   

   Der vorangehende Filter gibt einen Order wert der maximalen ganzzahligen Zahl minus 10 an. Dadurch Order können andere Filter am Ende der Pipeline ausgeführt werden.

3. Program.csFügen Sie in der Filtersammlung den Aktionsfilter hinzu:

   builder.Services.AddControllers(options =>
   {
       options.Filters.Add<HttpResponseExceptionFilter>();
   });
   

Wichtige Unterschiede für Controller

• Automatische Modellüberprüfung: Controller überprüfen den Modellstatus automatisch und geben Antworten auf Überprüfungsfehler zurück 400 Bad Request .
• Ausnahmefilter: Verwenden von Aktionsfiltern und Ausnahmefiltern für die zentrale Fehlerbehandlung
• Integrierte Problemdetails: Konfigurieren für ApiBehaviorOptions standardisierte Fehlerantworten
• Benutzerdefinierte Fehlerantworten: Außerkraftsetzung InvalidModelStateResponseFactory für die benutzerdefinierte Fehlerformatierung der Gültigkeitsprüfung

Weitere Ressourcen

• Verwenden der ModelState-Validierung in ASP.NET Core Web API
• Anzeigen oder Herunterladen von Beispielcode
• Hellang.Middleware.ProblemDetails