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.

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

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

Uitzonderingspagina voor ontwikkelaars

Op de uitzonderingspagina voor ontwikkelaars wordt gedetailleerde informatie weergegeven over niet-verwerkte aanvraag-uitzonderingen. Het maakt gebruik 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 omgeving.
• De app is gemaakt met de huidige sjablonen, dat wil gezegd met behulp van .

Apps die zijn gemaakt met behulp van eerdere sjablonen, kunnen de uitzonderingspagina voor ontwikkelaars inschakelen door aan te roepen .

Waarschuwing

Schakel de uitzonderingspagina voor ontwikkelaars alleen in als de app wordt uitgevoerd in de 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:

Geanimeerde uitzonderingspagina voor ontwikkelaars die elke geselecteerde tab laat zien.

Als reactie op een aanvraag met een 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

De uitzonderingspagina voor ontwikkelaars in een minimale API bekijken:

• Voer de voorbeeld-app uit in de omgeving.
• Ga naar het 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 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();

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 Uitzonderingshandler Middleware om een foutbericht te produceren.

Om de configuratie aan te passen, belt u . De volgende code wijzigt bijvoorbeeld de app om te reageren met een RFC 7807-compliant payload naar 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();

1. Roep in , aan om de 'Exception Handling Middleware' 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 route:

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

De voorgaande actie stuurt een RFC 7807-conforme payload naar de client.

Waarschuwing

Markeer de actiemethode voor de fouthandler niet met HTTP-methodekenmerken, zoals . 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 op . 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

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 eindpunt produceert met een weergave van wanneer deze groter is dan , anders een statuscode zonder antwoordtekst. Zie Antwoorden maken in minimale API-apps voor meer informatie over het maken van een antwoord.

De () kan worden geconfigureerd om een algemene inhoud voor de hoofdtekst te genereren wanneer deze leeg is, voor alle HTTP-clientreacties () of serverreacties (). De middleware wordt geconfigureerd door de useStatusCodePages-extensiemethode aan te roepen.

In het volgende voorbeeld wordt de app gewijzigd om te reageren met een RFC 7807-compatibele payload naar de client voor alle client- en serverreacties, inclusief routeringsfouten. 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);

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 transformeert MVC een foutresultaat om een .

Het automatisch maken van een voor statusfoutcodes staat 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 extensiemethode registreert de standaardimplementatie.

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

• : Genereert een antwoord met probleemdetails wanneer er geen aangepaste handler is gedefinieerd.
• : genereert standaard een antwoord met details van het probleem.
• Genereert een antwoord met probleemdetails tijdens ontwikkeling wanneer de HTTP-header van een aanvraag ontbreekt.

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 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 de probleemdetails voor meer informatie over het gebruik.

Fallback IProblemDetailsService

In de volgende code retourneert een fout als de geen kan 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 niet in staat is om een bestand te schrijven. Bijvoorbeeld een eindpunt waarbij de header Aanvraag accepteren een mediatype opgeeft dat het niet ondersteunt.
• Maakt gebruik van de Exception Handler Middleware.

Opmerking

De ondersteuning biedt de volgende mediatypen in de request-koptekst:

• application/json
• application/problem+json
• Jokertekentypen zoals en

Niet-JSON-mediatypen, zoals of , worden niet ondersteund en activeren het terugvalgedrag.

Het volgende voorbeeld is vergelijkbaar met het voorgaande, behalve dat het de functie 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);

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

De volgende code gebruikt om in te stellen :

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

Implementeren

MVC gebruikt om alle exemplaren van en . Deze fabriek wordt gebruikt voor:

• Klantfoutreacties
• Foutreacties bij validatiefouten
• en

Registreer een aangepaste implementatie van de probleemdetailsrespons in:

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

Gebruik

Gebruik de eigenschap om de inhoud van het antwoord te configureren. Met de volgende code wordt bijvoorbeeld de eigenschap bijgewerkt voor 404-antwoorden:

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

Aanvullende functies voor foutafhandeling

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

Foutreactie bij validatiefout

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

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 :

   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 :

   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 van de maximumwaarde voor gehele getallen min 10 op. Hierdoor kunnen andere filters aan het einde van de pijplijn worden uitgevoerd.

3. Voeg in het actiefilter het volgende 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 op validatiefouten
• Uitzonderingsfilters: Actiefilters en uitzonderingsfilters gebruiken voor gecentraliseerde foutafhandeling
• Ingebouwde probleemdetails: Configureren voor gestandaardiseerde foutreacties
• Aangepaste foutreacties: Overschrijven voor aangepaste validatiefoutopmaak

Aanvullende bronnen

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