Behandeln von Fehlern in ASP.NET Core-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. 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.

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

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

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.

Um exception handler middleware zu konfigurieren, rufen Sie UseExceptionHandler 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 Program.csUseExceptionHandler 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 /error Route zu reagieren:

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

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

[ApiExplorerSettings(IgnoreApi = true)]

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 liefert 200 OK mit einer json-Darstellung von User, wenn id größer als 0 ist, andernfalls einen 400 BAD REQUEST-Statuscode ohne Antworttextkörper. Weitere Informationen zum Erstellen einer Antwort finden Sie unter Erstellen von Antworten in minimalen API-Apps.

Das Status Code Pages middleware kann so konfiguriert werden, dass wenn leer für alle HTTP-Client- (400-499) oder Serverantworten (500 -599) ein gemeinsamer Antworttext erzeugt wird. Die Middleware wird durch Aufrufen der UseStatusCodePages-Erweiterungsmethode konfiguriert.

So ändert das folgende Beispiel die App beispielsweise so, dass sie bei allen Client- und Serverantworten mit einer RFC 7807-konformen Payload an den Client antwortet, einschließlich Routingfehlern (z. B. 404 NOT FOUND). 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 Sie den Dienst für Problemdetails
2. Implementieren von ProblemDetailsFactory
3. Verwenden Sie 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 in ein ProblemDetails um.

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

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

Im folgenden Code gibt httpContext.Response.WriteAsync("Fallback: An error occurred.") einen Fehler zurück, wenn die IProblemDetailsService-Implementierung nicht in der Lage ist, ProblemDetails zu generieren:

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 Fallback-Code, wenn problemDetailsService nicht in der Lage ist, ein ProblemDetails zu schreiben. Zum Beispiel ein Endpunkt, bei dem der Anforderungsheader Accept einen Medientyp angibt, den DefaultProblemDetailsWriter nicht unterstützt.
• Verwendet die Exception-Handler-Middleware.

Das folgende Beispiel ähnelt dem vorherigen, nur dass es Status Code Pages middleware 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.

Mit dem folgenden Code wird die App so konfiguriert, dass eine Problemdetailantwort für alle Fehlerantworten von HTTP-Client und -Server generiert wird, die noch keinen Textinhalt aufweisen:

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, um CustomizeProblemDetails festzulegen:

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 Sie ProblemDetailsFactory.

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

• Clientfehlerantworten
• Fehlerrückmeldungen bei Validierungsfehlern
• 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>();

ApiBehaviorOptions.ClientErrorMapping verwenden

Verwenden Sie die ClientErrorMapping Eigenschaft, um den Inhalt der ProblemDetails Antwort zu konfigurieren. Beispielsweise aktualisiert der folgende Code in Program.cs die Eigenschaft Link bei 404-Antworten:

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

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 Sie Problemdetails mit AddProblemDetails() für konsistente Fehlerantworten

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 controllerbasierten Fehlerbehandlung, einschließlich Validierungsfehlern, Anpassung von Problemen und Ausnahmefiltern, finden Sie in den Registerkartenabschnitten " Controller ".

Fehlerantwort bei Validierungsfehlern

Bei Web-API-Controllern antwortet MVC mit einem ValidationProblemDetails Antworttyp, wenn die Modellüberprüfung fehlschlägt. MVC verwendet die Ergebnisse von InvalidModelStateResponseFactory, um die Fehlerantwort für einen Validierungsfehler 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 von dem maximalen Integerwert minus 10 an. Dies Order ermöglicht, dass 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: ApiBehaviorOptions für standardisierte Fehlerantworten konfigurieren
• Benutzerdefinierte Fehlerantworten: InvalidModelStateResponseFactory überschreiben, um Validierungsfehler benutzerdefiniert zu formatieren