Fouten in ASP.NET Core API's verwerken

Opmerking

Dit is niet de nieuwste versie van dit artikel. Zie de .NET 10-versie van dit artikel voor de huidige release.

Waarschuwing

Deze versie van ASP.NET Core wordt niet meer ondersteund. Zie het .NET en .NET Core Support Policy voor meer informatie. Zie de .NET 10-versie van dit artikel voor de huidige release.

Minimale API's

In dit artikel wordt beschreven hoe u fouten in ASP.NET Core API's kunt verwerken. Documentatie voor minimale API's is geselecteerd. Selecteer het tabblad Controllers voor documentatie voor api's op basis van een controller. Zie Blazor voor Blazor foutafhandelingsrichtlijnen.

Controllers

In dit artikel wordt beschreven hoe u fouten in ASP.NET Core API's kunt verwerken. Documentatie voor controller-gebaseerde API's is geselecteerd. Als u de documentatie voor Minimale API's wilt bekijken, selecteert u het tabblad Minimale API's. Zie Blazor voor Blazor foutafhandelingsrichtlijnen.

Uitzonderingspagina voor ontwikkelaars

Op de uitzonderingspagina voor ontwikkelaars wordt gedetailleerde informatie weergegeven over niet-verwerkte aanvraag-uitzonderingen. Het maakt gebruik DeveloperExceptionPageMiddleware van het vastleggen van synchrone en asynchrone uitzonderingen van de HTTP-pijplijn en voor het genereren van foutreacties. De foutpagina voor ontwikkelaars draait vroeg in de middleware-pijplijn, zodat niet-verwerkte uitzonderingen kunnen worden opgevangen die optreden in de daaropvolgende middleware.

ASP.NET Core apps de uitzonderingspagina voor ontwikkelaars standaard inschakelen wanneer beide:

• Wordt uitgevoerd in de Development omgeving.
• De app is gemaakt met de huidige sjablonen, dat wil gezegd met behulp van WebApplication.CreateBuilder.

Apps die zijn gemaakt met behulp van eerdere sjablonen, dat wil zeggen door WebHost.CreateDefaultBuilder te gebruiken, kunnen de uitzonderingspagina voor ontwikkelaars inschakelen door app.UseDeveloperExceptionPage aan te roepen.

Waarschuwing

Schakel de uitzonderingspagina voor ontwikkelaars alleen in als de app wordt uitgevoerd in de Development omgeving. Deel geen gedetailleerde uitzonderingsgegevens openbaar wanneer de app in productie wordt uitgevoerd. Zie ASP.NET Core runtime-omgevingen voor meer informatie over het configureren van omgevingen.

De uitzonderingspagina voor ontwikkelaars kan de volgende informatie bevatten over de uitzondering en de aanvraag:

• Stacktracering
• Queryreeksparameters, indien van toepassing
• Cookies, indien van toepassing
• Headers
• Eindpuntmetagegevens, indien van toepassing

De uitzonderingspagina voor ontwikkelaars is niet gegarandeerd informatie te verstrekken. Gebruik Logging voor volledige foutinformatie.

In de volgende afbeelding ziet u een voorbeeld van een uitzonderingspagina voor ontwikkelaars met animatie om de tabbladen en de weergegeven informatie weer te geven:

Als reactie op een aanvraag met een Accept: text/plain header retourneert de uitzonderingspagina voor ontwikkelaars tekst zonder opmaak in plaats van HTML. Voorbeeld:

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 API's

De uitzonderingspagina voor ontwikkelaars in een minimale API bekijken:

• Voer de voorbeeld-app uit in de Development omgeving.
• Ga naar het /exception eindpunt.

Deze sectie verwijst naar de volgende voorbeeld-app om manieren te demonstreren voor het afhandelen van uitzonderingen in een minimale API. Er wordt een uitzondering gegenereerd wanneer het eindpunt /exception wordt aangevraagd:

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

Controllers

De uitzonderingspagina voor ontwikkelaars bekijken in een API op basis van een controller:

• Voeg de volgende controlleractie toe aan een controller-gebaseerde API. De actie genereert een uitzondering wanneer het eindpunt wordt aangevraagd.

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

• Voer de app uit in de ontwikkelomgeving.

• Ga naar het eindpunt dat is gedefinieerd door de controlleractie.

Uitzonderingshandler

Gebruik in niet-ontwikkelomgevingen de middleware voor uitzonderingsafhandeling om een foutpayload te genereren.

Minimale API's

Om de exception handler middleware te configureren, roept u UseExceptionHandler aan. De volgende code zorgt er bijvoorbeeld voor dat de app reageert met een RFC 7807-compatibele payload aan de client. Zie de sectie Probleemdetails verderop in dit artikel voor meer informatie.

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

Controllers

1. Program.cs Roep UseExceptionHandlerin aan om de middleware voor het verwerken van uitzonderingen toe te voegen:

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

2. Configureer een controlleractie om te reageren op de /error route:

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

Met de bovenstaande HandleError actie wordt een RFC 7807-compatibele payload naar de client verzonden.

Waarschuwing

Markeer de actiemethode voor de fouthandler niet met HTTP-methodekenmerken, zoals HttpGet. Expliciete werkwoorden voorkomen dat sommige aanvragen de actiemethode bereiken.

Voor web-API's die gebruikmaken van Swagger/OpenAPI, markeert u de actie fouthandler met het kenmerk [ApiExplorerSettings] en stelt u de eigenschap in IgnoreApi op true. Deze kenmerkconfiguratie sluit de actie fouthandler uit van de OpenAPI-specificatie van de app:

[ApiExplorerSettings(IgnoreApi = true)]

Anonieme access aan de methode toestaan als niet-geverifieerde gebruikers de fout moeten zien.

Antwoorden op client- en serverfouten

Minimale API's

Houd rekening met de volgende 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);

Het /users eindpunt produceert 200 OK met een json weergave van User wanneer id deze groter is dan 0, anders een 400 BAD REQUEST statuscode zonder antwoordtekst. Zie Antwoorden maken in minimale API-apps voor meer informatie over het maken van een antwoord.

De Status Code Pages middleware kan worden geconfigureerd om een algemene hoofdtekstinhoud te produceren, wanneer deze leeg is, voor alle HTTP-clientreacties (400-499) of serverreacties.500 -599 De middleware wordt geconfigureerd door de useStatusCodePages-extensiemethode aan te roepen.

In het volgende voorbeeld wordt de app bijvoorbeeld gewijzigd zodat deze voor alle client- en serverreacties, inclusief routeringsfouten (bijvoorbeeld ), met een 404 NOT FOUND aan de client reageert. Zie de sectie Probleemdetails voor meer informatie.

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

Controllers

Voor api's op basis van een controller kan het foutbericht op een van de volgende manieren worden geconfigureerd:

1. De service voor probleemdetails gebruiken
2. ProblemDetailsFactory implementeren
3. ApiBehaviorOptions.ClientErrorMapping gebruiken

Er wordt een foutresultaat gedefinieerd als resultaat met een HTTP-statuscode van 400 of hoger. Voor web-API-controllers zet MVC een foutresultaat om in een ProblemDetails.

Het automatisch maken van een ProblemDetails voor foutcodes is standaard ingeschakeld.

Details van probleem

Probleemdetails zijn niet de enige antwoordindeling voor het beschrijven van een HTTP-API-fout. Ze worden echter vaak gebruikt om fouten voor HTTP-API's te rapporteren.

De service voor probleemdetails implementeert de interface IProblemDetailsService, die ondersteuning biedt voor het maken van probleemdetails in ASP.NET Core. De AddProblemDetails(IServiceCollection)-extensiemethode op IServiceCollection registreert de standaard IProblemDetailsService-implementatie.

In ASP.NET Core-apps genereert de volgende middleware HTTP-probleemdetaillantwoorden wanneer AddProblemDetails wordt aangeroepen, behalve wanneer de HTTP-header van het Accept verzoek geen van de inhoudstypen bevat die worden ondersteund door de geregistreerde IProblemDetailsWriter (standaard: application/json):

• ExceptionHandlerMiddleware: Genereert een antwoord met probleemdetails wanneer er geen aangepaste handler is gedefinieerd.
• StatusCodePagesMiddleware: genereert standaard een antwoord met details van het probleem.
• DeveloperExceptionPageMiddleware: Genereert een probleemdetailreactie tijdens ontwikkeling wanneer de HTTP-header van de Accept aanvraag text/html niet bevat.

Minimale API's

Minimale API-apps kunnen worden geconfigureerd om antwoord op probleemdetails te genereren voor alle HTTP-client- en serverfoutreacties die nog geen hoofdtekstinhoud hebben met behulp van de AddProblemDetails extensiemethode.

Met de volgende code wordt de app geconfigureerd voor het genereren van probleemdetails:

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

Zie AddProblemDetails voor meer informatie over het gebruik van

Fallback IProblemDetailsService

In de volgende code retourneert httpContext.Response.WriteAsync("Fallback: An error occurred.") een fout als de implementatie van IProblemDetailsService niet in staat is een ProblemDetails te genereren:

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

De voorgaande code:

• Schrijft een foutbericht met de terugvalcode als de problemDetailsService geen ProblemDetails kan schrijven. Bijvoorbeeld een eindpunt waarbij de header Aanvraag accepteren een mediatype opgeeft dat het DefaultProblemDetailsWriter niet ondersteunt.
• Maakt gebruik van de middleware voor uitzonderingsafhandeling.

Opmerking

DefaultProblemDetailsWriter ondersteunt de volgende mediatypen in de Accept requestheader:

• application/json
• application/problem+json
• Wildcardtypen zoals */* en application/*

Niet-JSON-mediatypen, zoals application/xml of text/html, worden niet ondersteund en activeren het terugvalgedrag.

Het volgende voorbeeld is vergelijkbaar met het voorgaande, behalve dat het de Status Code Pages middleware aanroept.

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

Controllers

Service voor probleemdetails

ASP.NET Core ondersteunt het maken van Problem Details voor HTTP-API's met behulp van de IProblemDetailsService.

Met de volgende code wordt de app geconfigureerd voor het genereren van een antwoord op probleemdetails voor alle HTTP-client- en serverfoutreacties die nog geen hoofdtekstinhoud hebben:

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

Houd rekening met de API-controller uit de vorige sectie, die retourneert BadRequest wanneer de invoer ongeldig is:

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

Er wordt een antwoord voor probleemdetails gegenereerd met de voorgaande code wanneer een van de volgende voorwaarden van toepassing is:

• Er wordt een ongeldige invoer opgegeven.
• De URI heeft geen overeenkomend eindpunt.
• Er treedt een onverwerkte uitzondering op.

Probleemdetails aanpassen met CustomizeProblemDetails

De volgende code gebruikt ProblemDetailsOptions om in te stellen 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();

ProblemDetailsFactory implementeren

MVC gebruikt Microsoft.AspNetCore.Mvc.Infrastructure.ProblemDetailsFactory om alle instanties van ProblemDetails en ValidationProblemDetails te genereren. Deze fabriek wordt gebruikt voor:

• Klantfoutreacties
• Foutreacties bij validatiefouten
• ControllerBase.Problem en ControllerBase.ValidationProblem

Om de probleemdetailsreactie aan te passen, registreert u een aangepaste implementatie van ProblemDetailsFactory in Program.cs:

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

Gebruik ApiBehaviorOptions.ClientErrorMapping

Gebruik de ClientErrorMapping eigenschap om de inhoud van het ProblemDetails antwoord te configureren. De volgende code in Program.cs werkt bijvoorbeeld de eigenschap Link bij voor 404-reacties:

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

Aanvullende functies voor foutafhandeling

Minimale API's

Migratie van controllers naar minimale API's

Als u migreert van api's op basis van een controller naar minimale API's:

1. Actiefilters vervangen door eindpuntfilters of middleware
2. Modelvalidatie vervangen door handmatige validatie of aangepaste binding
3. Uitzonderingsfilters vervangen door middleware voor uitzonderingsafhandeling
4. Probleemdetails configureren met AddProblemDetails() voor consistente foutreacties

Wanneer gebruikt men controller-gebaseerde foutafhandeling?

Overweeg api's op basis van een controller als u het volgende nodig hebt:

• Complexe modelvalidatiescenario's
• Gecentraliseerde verwerking van uitzonderingen op meerdere controllers
• Fijnmazige controle over de opmaak van foutmeldingen
• Integratie met MVC-functies zoals filters en conventies

Zie de tabbladsecties Controllers voor gedetailleerde informatie over foutafhandeling op basis van controller, waaronder validatiefouten, aanpassing van probleemdetails en uitzonderingsfilters .

Controllers

Foutreactie bij validatiefout

Voor web-API-controllers reageert MVC met een ValidationProblemDetails antwoordtype wanneer modelvalidatie mislukt. MVC gebruikt de resultaten van InvalidModelStateResponseFactory om de foutrespons voor een validatiefout op te stellen. In het volgende voorbeeld wordt de standaardfactory vervangen door een implementatie die ook ondersteuning biedt voor het opmaken van antwoorden als XML, 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();

Uitzonderingen gebruiken om het antwoord te wijzigen

De inhoud van het antwoord kan worden gewijzigd van buiten de controller met behulp van een aangepaste uitzondering en een actiefilter:

1. Maak een bekend uitzonderingstype met de naam 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. Maak een actiefilter met de naam 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;
           }
       }
   }
   

   Het voorgaande filter geeft een Order van de maximumwaarde voor gehele getallen min 10 op. Hierdoor Order kunnen andere filters aan het einde van de pijplijn worden uitgevoerd.

3. Voeg in Program.cs het actiefilter toe aan de verzameling filters:

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

Belangrijkste verschillen voor controllers

• Automatische modelvalidatie: Controllers valideren de modelstatus automatisch en retourneren antwoorden 400 Bad Request op validatiefouten
• Uitzonderingsfilters: Actiefilters en uitzonderingsfilters gebruiken voor gecentraliseerde foutafhandeling
• Ingebouwde probleemdetails: Configureren ApiBehaviorOptions voor gestandaardiseerde foutreacties
• Aangepaste foutreacties: Overschrijven InvalidModelStateResponseFactory voor aangepaste validatiefoutopmaak

Aanvullende bronnen

• De validatie van ModelState gebruiken in ASP.NET Core web-API
• Voorbeeldcode weergeven of downloaden
• Hellang.Middleware.ProblemDetails