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 unter .NET und .NET Core Support Policy. Die aktuelle Version finden Sie in der .NET 10-Version dieses Artikels.

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. Informationen zu Blazor Fehlerbehandlungsanleitungen finden Sie unter Handle-Fehler in ASP.NET Core Blazor Apps.

In diesem Artikel wird beschrieben, wie Fehler in ASP.NET Core APIs behandelt werden. Die Dokumentation für Controller-basierte APIs ist ausgewählt. Um die Dokumentation für Minimal-APIs anzuzeigen, wählen Sie die Registerkarte Minimale APIs aus. Informationen zu Blazor Fehlerbehandlungsanleitungen finden Sie unter Handle-Fehler in ASP.NET Core Blazor apps.

Entwickler-Ausnahmeseite

Auf der Entwickler ausnahmeseite werden detaillierte Informationen zu nicht behandelten Anforderungs ausnahmen angezeigt. Es wird verwendet, um synchrone und asynchrone Ausnahmen von der HTTP-Pipeline zu erfassen und Fehlerantworten zu generieren. Die Entwickler-Ausnahmeseite läuft früh in der Middleware-Pipeline, damit sie unbehandelte Ausnahmen erfassen kann, die in der nachfolgenden Middleware ausgelöst werden.

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

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

Apps, die mithilfe früherer Vorlagen erstellt wurden, können die Entwickler-Ausnahmeseite durch Aufrufen aktivieren.

Warnung

Aktivieren Sie die Entwickler-Ausnahmeseite nicht , es sei denn, die App wird in der Umgebung 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-Ausnahmeseite kann die folgenden Informationen über die Ausnahme und die Anfrage enthalten:

• Stack-Trace
• Abfragezeichenfolgenparameter( falls vorhanden)
• Cookies, falls vorhanden
• Headers
• Endpunktmetadaten( falls vorhanden)

Die Entwickler-Ausnahmeseite bietet keine Garantie, dass sie Informationen liefert. Verwenden Sie die Protokollierungsfunktion für vollständige Fehlerinformationen.

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

Entwickler-Ausnahmeseite animiert, um jede ausgewählte Registerkarte anzuzeigen.

Als Reaktion auf eine Anforderung mit einem 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

So zeigen Sie die Entwickler-Ausnahmeseite bei einer minimalen API an:

• Führen Sie die Beispiel-App in der Umgebung aus.
• Gehen Sie zu dem 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 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();

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.

Um zu konfigurieren, rufen Sie auf. 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();

1. Rufen Sie in , auf, um 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 Route zu reagieren:

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

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

Warnung

Markieren Sie die Fehlerhandleraktionsmethode nicht mit HTTP-Methodenattributen, z . 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 Eigenschaft auf . 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 sollen.

Client- und Serverfehlerantworten

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 Endpunkt erzeugt eine Darstellung, wenn größer als ist, andernfalls einen Statuscode ohne Antworttext. Weitere Informationen zum Erstellen einer Antwort finden Sie unter Erstellen von Antworten in minimalen API-Apps.

Es kann konfiguriert werden, um einen allgemeinen Inhalt des Hauptteils zu erzeugen, wenn für alle HTTP-Clientanfragen () oder Serverantworten () keiner vorhanden ist. Die Middleware wird durch Aufrufen der UseStatusCodePages-Erweiterungsmethode konfiguriert.

Im folgenden Beispiel wird die App so geändert, dass sie mit einer RFC 7807-kompatiblen Nutzlast auf alle Client- und Serverantworten reagiert, einschließlich Routingfehlern (z. 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);

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

1. Verwenden des Problemdetailsdiensts
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 wandelt MVC ein Fehlerergebnis um, um eine Fehlermeldung zu erzeugen.

Die automatische Erstellung von 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 Problemdetails-Dienst implementiert die schnittstelle IProblemDetailsService, die das Erstellen von Problemdetails in ASP.NET Core unterstützt. Die Erweiterungsmethode auf dem Register registriert die Standardimplementierung.

In ASP.NET Core Apps generiert die folgende Middleware HTTP-Antworten mit Problemdetails, wenn AddProblemDetails aufgerufen wird, es sei denn, die Accept Anforderungs-HTTP-Header enthält keinen der vom registrierten IProblemDetailsWriter unterstützten Inhaltstypen (Standard: application/json):

• : Generiert eine Antwort auf Problemdetails, wenn kein benutzerdefinierter Handler definiert ist.
• : Generiert standardmäßig eine Antwort auf Problemdetails.
• Generiert eine Problemdetail-Antwort in der Entwicklung, wenn der HTTP-Anforderungsheader etwas nicht enthält.

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 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 finden Sie unter Problemdetails

IProblemDetailsService Fallback

Gibt im folgenden Code einen Fehler zurück, wenn die Implementierung nicht in der Lage ist, eine :

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 das System nicht in der Lage ist, [eine Datei/etwas] zu schreiben. Ein Endpunkt, auf dem der Accept-Anforderungsheader beispielsweise einen Medientyp angibt, der nicht unterstützt wird.
• Verwendet die Middleware des Ausnahmehandlers.

Hinweis

Die folgenden Medientypen werden im Anforderungsheader unterstützt:

• application/json
• application/problem+json
• Wildcardtypen wie und

Nicht-JSON-Medientypen, z . B. oder , werden nicht unterstützt und lösen das Fallbackverhalten aus.

Das folgende Beispiel ähnelt dem vorherigen, mit der Ausnahme, dass es die Methode aufruft.

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);

Problemdetailsdienst

ASP.NET Core unterstützt das Erstellen von Problemdetails für HTTP-APIs unter Verwendung 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 , 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.

Problemdetails anpassen mit

Der folgende Code verwendet zum Festlegen :

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();

Implementieren

MVC verwendet , um alle Instanzen von und zu erzeugen. Diese Factory wird für Folgendes verwendet:

• Clientfehlerantworten
• Fehlerrückmeldungen bei Validierungsfehlern
• und

Um die Problemdetails-Antwort anzupassen, registrieren Sie eine benutzerdefinierte Implementierung von in :

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

Verwende

Verwenden Sie die Eigenschaft, um den Inhalt der Antwort zu konfigurieren. Zum Beispiel aktualisiert der folgende Code die Eigenschaft für 404-Antworten:

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

Zusätzliche Fehlerbehandlungsfunktionen

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. Problemdetails für konsistente Fehlerantworten konfigurieren

Wann die controllerbasierte Fehlerbehandlung verwendet werden sollte

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 controller-basierten Fehlerbehandlung, einschließlich Validierungsfehlern, Anpassung der Problemdetails und Ausnahmefiltern, finden Sie in den Abschnitten des Controllers-Bereichs.

Fehlerantwort bei Validierungsfehlern

Bei Web-API-Controllern antwortet MVC mit einem Antworttyp, wenn die Modellüberprüfung fehlschlägt. MVC verwendet die Ergebnisse, um 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 :

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 :

   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 :

   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 wert der maximalen ganzzahligen Zahl minus 10 an. Dadurch können andere Filter am Ende der Pipeline ausgeführt werden.

3. Fü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 .
• Ausnahmefilter: Verwenden von Aktionsfiltern und Ausnahmefiltern für die zentrale Fehlerbehandlung
• Integrierte Problemdetails: Konfigurieren für standardisierte Fehlerantworten
• Benutzerdefinierte Fehlerantworten: Override für eine benutzerdefinierte Formatierung von Validierungsfehlern

Weitere Ressourcen

• How to Use ModelState Validation in ASP.NET Core Web API
• Beispielcode anzeigen oder herunterladen
• Hellang.Middleware.ProblemDetails