Behandeln von Fehlern in controllerbasierten Web-APIs von ASP.NET Core

Dieser Artikel beschreibt die Behandlung von Fehlern sowie die Anpassung der Fehlerbehandlung mit controllerbasierten ASP.NET Core-Web-APIs. Informationen zur Fehlerbehandlung in minimalen APIs finden Sie unter Behandeln von Fehlern in ASP.NET Core und Behandeln von Fehlern in minimalen APIs.

Seite mit Ausnahmen für Entwickler

Die Seite mit Ausnahmen für Entwickler enthält ausführliche Informationen zu unbehandelten Anforderungsausnahmen. Es verwendet DeveloperExceptionPageMiddleware, um synchrone und asynchrone Ausnahmen aus der HTTP-Pipeline zu erfassen und um Fehlerantworten zu generieren. Die Seite mit Ausnahmen für Entwickler wird früh in der Middlewarepipeline ausgeführt, sodass in der nachfolgenden Middleware ausgelöste unbehandelte Ausnahmen abgefangen werden.

ASP.NET Core-Apps aktivieren standardmäßig die Seite mit Ausnahmen für Entwickler, wenn die folgenden Aussagen beide zutreffen:

• Die Ausführung erfolgt in der Entwicklungsumgebung.
• Die App wurde mit den aktuellen Vorlagen erstellt, d. h. mithilfe von WebApplication.CreateBuilder.

Apps, die mit früheren Vorlagen erstellt wurden, d. h. mithilfe von WebHost.CreateDefaultBuilder, können die Seite mit Ausnahmen für Entwickler durch Aufrufen von app.UseDeveloperExceptionPage aktivieren.

Warnung

Aktivieren Sie die Seite für Entwicklerausnahmen nur, wenn die App in der Entwicklungsumgebung ausgeführt wird. Wenn die App in der Produktionsumgebung ausgeführt wird, sollten Sie keine detaillierten Ausnahmeinformationen öffentlich teilen. Weitere Informationen zum Konfigurieren der Umgebung finden Sie unter Verwenden mehrerer Umgebungen in ASP.NET Core.

Die Seite mit Ausnahmen für Entwickler kann die folgenden Informationen zu der Ausnahme und der Anforderung enthalten:

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

Es ist nicht garantiert, dass auf der Seite mit Ausnahmen für Entwickler Informationen angezeigt werden. Vollständige Informationen zu Fehlern finden Sie unter Protokollierung.

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 Seite mit Ausnahmen für Entwickler nur Text anstelle von HTML zurück. Zum 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 gelangen Sie zur Seite mit Ausnahmen für Entwickler:

• 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.

• Navigieren Sie zum Endpunkt, der von der Controlleraktion definiert wurde.

Ausnahmehandler

In Nicht-Entwicklungsumgebungen kann Middleware zur Ausnahmebehandlung verwendet werden, um Fehlernutzdaten zu generieren:

1. Rufen Sie in Program.csUseExceptionHandler auf, um die Middleware zur 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 antworten:

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

Die oben stehende HandleError-Aktion sendet eine mit RFC 7807 konforme Nutzlast an den Client.

Warnung

Markieren Sie die Aktionsmethode für die Fehlerbehandlung nicht mit HTTP-Methodenattributen wie HttpGet. Durch explizite Verben könnte bei einigen Anforderungen verhindert werden, dass diese Aktionsmethode zum Einsatz kommt.

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

[ApiExplorerSettings(IgnoreApi = true)]

Lassen Sie den anonymen Zugriff auf die Methode zu, wenn nicht authentifizierten Benutzern der Fehler angezeigt werden soll.

Die Middleware zur Ausnahmebehandlung kann auch in der Entwicklungsumgebung verwendet werden, um ein konsistentes Nutzdatenformat für alle Umgebungen zu erzeugen:

1. Registrieren Sie umgebungsspezifische Middleware zur Ausnahmebehandlung in Program.cs:

   if (app.Environment.IsDevelopment())
   {
       app.UseExceptionHandler("/error-development");
   }
   else
   {
       app.UseExceptionHandler("/error");
   }
   

   Im oben stehenden Code ist die Middleware mit Folgendem registriert:

   • Route /error-development in der Entwicklungsumgebung.
   • Eine /error-Route in Nicht-Entwicklungsumgebungen.

2. Fügen Sie Controlleraktionen sowohl für die Entwicklungs- als auch für die Nicht-Entwicklungsrouten hinzu:

   [Route("/error-development")]
   public IActionResult HandleErrorDevelopment(
       [FromServices] IHostEnvironment hostEnvironment)
   {
       if (!hostEnvironment.IsDevelopment())
       {
           return NotFound();
       }
   
       var exceptionHandlerFeature =
           HttpContext.Features.Get<IExceptionHandlerFeature>()!;
   
       return Problem(
           detail: exceptionHandlerFeature.Error.StackTrace,
           title: exceptionHandlerFeature.Error.Message);
   }
   
   [Route("/error")]
   public IActionResult HandleError() =>
       Problem();
   

Verwenden von Ausnahmen zum Ändern der Antwort

Der Inhalt der Antwort kann von außerhalb des Controllers mithilfe einer benutzerdefinierten Ausnahme und eines Aktionsfilters 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 Sie einen Aktionsfilter namens 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 vorherige Filter gibt eine Order des maximalen ganzzahligen Werts minus 10 an. Durch diese Order können andere Filter am Ende der Pipeline ausgeführt werden.

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

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

Antwort auf Überprüfungsfehler

Bei Web-API-Controllern antwortet MVC mit dem Antworttyp ValidationProblemDetails, wenn bei der Modellüberprüfung ein Fehler auftritt. MVC verwendet die Ergebnisse von InvalidModelStateResponseFactory, um die Fehlerantwort auf einen Überprüfungsfehler zu erstellen. Im folgenden Beispiel wird die Standardfactory durch eine Implementierung ersetzt, die auch das Formatieren von Antworten als XML in Program.cs unterstützt:

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

Fehlerantwort des Clients

Ein Fehlerergebnis ist als Ergebnis mit dem HTTP-Statuscode 400 oder höher definiert. Bei Web-API-Controllern transformiert MVC ein Fehlerergebnis so, dass ProblemDetails erzeugt werden.

Die automatische Erstellung von ProblemDetails für Fehlerstatuscodes ist standardmäßig aktiviert, aber Fehlerantworten können auf eine der folgenden Arten konfiguriert werden:

1. Verwenden des Diensts für Problemdetails
2. Implementieren der ProblemDetailsFactory
3. Verwenden von ApiBehaviorOptions.ClientErrorMapping

Standardantwort mit Problemdetails

Die folgende Program.cs-Datei wurde von den Webanwendungsvorlagen für API-Controller generiert:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Betrachten Sie den folgenden Controller, der BadRequest 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 mit Problemdetails wird mit dem vorherigen Code generiert, wenn eine der folgenden Bedingungen zutrifft:

• Der Endpunkt /api/values2/divide wird mit einem Nenner von Null aufgerufen.
• Der Endpunkt /api/values2/squareroot wird mit einem Radikanden kleiner als Null aufgerufen.

Der Text der Standardantwort mit Problemdetails weist die folgenden type-, title- und status-Werte auf:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "traceId": "00-84c1fd4063c38d9f3900d06e56542d48-85d1d4-00"
}

Dienst für Problemdetails

ASP.NET Core unterstützt das Erstellen von Problemdetails für HTTP-APIs mithilfe von IProblemDetailsService. Weitere Informationen finden Sie im Abschnitt Dienst für Problemdetails.

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

Betrachten Sie den API-Controller aus dem vorherigen Abschnitt, der BadRequest 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 mit Problemdetails wird mit dem vorherigen Code generiert, wenn eine der folgenden Bedingungen zutrifft:

• Es wird eine ungültige Eingabe bereitgestellt.
• Der URI verfügt über keinen übereinstimmenden Endpunkt.
• Es tritt eine unbehandelte Ausnahme auf.

Die automatische Erstellung einer ProblemDetails-Antwort für Fehlerstatuscodes ist deaktiviert, wenn die SuppressMapClientErrors-Eigenschaft auf true festgelegt ist:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
        options.SuppressMapClientErrors = true;
    });

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Wenn ein API-Controller BadRequest zurückgibt, wird unter Verwendung des vorherigen Codes ein HTTP 400-Antwortstatus ohne Antworttext zurückgegeben. SuppressMapClientErrors verhindert, dass eine ProblemDetails-Antwort erstellt wird, auch wenn WriteAsync für einen API-Controller-Endpunkt aufgerufen wird. WriteAsync wird später im Artikel erläutert.

Im nächsten Abschnitt wird gezeigt, wie Sie den Text der Problemdetailantwort mithilfe von CustomizeProblemDetails anpassen, um eine hilfreichere Antwort zurückzugeben. Weitere Anpassungsoptionen finden Sie unter Anpassen von Problemdetails.

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

Der aktualisierte API-Controller:

[Route("api/[controller]/[action]")]
[ApiController]
public class ValuesController : ControllerBase
{
    // /api/values/divide/1/2
    [HttpGet("{Numerator}/{Denominator}")]
    public IActionResult Divide(double Numerator, double Denominator)
    {
        if (Denominator == 0)
        {
            var errorType = new MathErrorFeature
            {
                MathError = MathErrorType.DivisionByZeroError
            };
            HttpContext.Features.Set(errorType);
            return BadRequest();
        }

        return Ok(Numerator / Denominator);
    }

    // /api/values/squareroot/4
    [HttpGet("{radicand}")]
    public IActionResult Squareroot(double radicand)
    {
        if (radicand < 0)
        {
            var errorType = new MathErrorFeature
            {
                MathError = MathErrorType.NegativeRadicandError
            };
            HttpContext.Features.Set(errorType);
            return BadRequest();
        }

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

}

Der folgende Code enthält MathErrorFeature und MathErrorType, die mit dem vorherigen Beispiel verwendet werden:

// Custom Http Request Feature
class MathErrorFeature
{
    public MathErrorType MathError { get; set; }
}

// Custom math errors
enum MathErrorType
{
    DivisionByZeroError,
    NegativeRadicandError
}

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

• Der Endpunkt /divide wird mit einem Nenner von Null aufgerufen.
• Der Endpunkt /squareroot wird mit einem Radikanden kleiner als Null aufgerufen.
• Der URI verfügt über keinen übereinstimmenden Endpunkt.

Der Text der Problemdetailantwort enthält Folgendes, wenn ein squareroot-Endpunkt mit einem Radikanden kleiner als Null aufgerufen wird:

{
  "type": "https://en.wikipedia.org/wiki/Square_root",
  "title": "Bad Input",
  "status": 400,
  "detail": "Negative or complex numbers are not allowed."
}

Anzeigen oder Herunterladen von Beispielcode

Implementieren Sie ProblemDetailsFactory.

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

• Clientfehlerantworten
• Überprüfungsfehlerantworten
• ControllerBase.Problem und ControllerBase.ValidationProblem

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

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

Verwenden Sie ApiBehaviorOptions.ClientErrorMapping

Verwenden Sie die ClientErrorMapping-Eigenschaft zum Konfigurieren des Inhalts der ProblemDetails-Antwort. Der folgende Code in Program.cs aktualisiert beispielsweise die Link-Eigenschaft für 404-Antworten:

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

Zusätzliche Ressourcen

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