Fouten in ASP.NET Core-API's verwerken

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 om documentatie te bekijken voor api's op basis van een controller. Zie BlazorFouten afhandelen in ASP.NET Core-apps Blazor voor hulp bij het afhandelen van fouten.

In dit artikel wordt beschreven hoe u fouten in ASP.NET Core-API's kunt verwerken. Documentatie voor api's op basis van controller is geselecteerd. Als u de documentatie voor minimale API's wilt bekijken, selecteert u het tabblad Minimale API's . Zie BlazorFouten afhandelen in ASP.NET Core-apps Blazor voor hulp bij het afhandelen van fouten.

De uitzonderingspagina voor ontwikkelaars in een minimale API bekijken:

• Voer de voorbeeld-app uit in de ontwikkelomgeving.
• 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();

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

• Voeg de volgende controlleractie toe aan een api op basis van een controller. 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.

Als u de aanroep wilt configureren, roept u het Exception Handler Middlewareaan UseExceptionHandler. De volgende code wijzigt bijvoorbeeld de app om te reageren met een RFC 7807-compatibele nettolading 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. Program.cs Roep UseExceptionHandlerin aan om de Middleware voor uitzonderingsafhandeling 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 voorgaande HandleError actie wordt een rfC 7807-compatibele nettolading naar de client verzonden.

[ApiExplorerSettings(IgnoreApi = true)]

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 om te reageren met een rfC 7807-compatibele nettolading naar de client voor alle client- en serverreacties, inclusief routeringsfouten (bijvoorbeeld 404 NOT FOUND). 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 ProblemDetails.

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

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

Terugval IProblemDetailsService

Retourneert in de volgende code httpContext.Response.WriteAsync("Fallback: An error occurred.") een fout als de IProblemDetailsService implementatie geen ProblemDetails:

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:

• Hiermee schrijft u een foutbericht met de terugvalcode als de problemDetailsService terugvalcode een ProblemDetails. Bijvoorbeeld een eindpunt waarbij de header Aanvraag accepteren een mediatype opgeeft dat het DefaulProblemDetailsWriter niet ondersteunt.
• Maakt gebruik van de Exception Handler Middleware.

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

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 biedt ondersteuning voor het maken van probleemdetails 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();

Implementeren ProblemDetailsFactory

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

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

Registreer een aangepaste implementatie van ProblemDetailsFactory :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. Met de volgende code wordt Program.cs bijvoorbeeld de Link eigenschap bijgewerkt voor 404-antwoorden:

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

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 AddProblemDetails() consistente foutreacties

Wanneer gebruikt u foutafhandeling op basis van controller

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 foutreacties
• 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 ValidationProblemDetails antwoordtype wanneer modelvalidatie mislukt. MVC gebruikt de resultaten van het samenstellen van InvalidModelStateResponseFactory 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 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 Program.csin 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 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