Hantera fel i ASP.NET Core-API:er

Den här artikeln beskriver hur du hanterar fel i ASP.NET Core-API:er. Dokumentation för minimala API:er har valts. Om du vill se dokumentationen för kontrollantbaserade API:er väljer du fliken Kontrollanter. Vägledning för Blazor felhantering finns i Hantera fel i ASP.NET Core-apparBlazor.

Den här artikeln beskriver hur du hanterar fel i ASP.NET Core-API:er. Dokumentation för kontrollantbaserade API:er har valts. Om du vill se dokumentationen för Minimala API:er väljer du fliken Minimala API:er. Vägledning för Blazor felhantering finns i Hantera fel i ASP.NET Core-apparBlazor.

Så här ser du undantagssidan för utvecklare i ett minimalt API:

• Kör exempelappen i utvecklingsmiljön.
• Gå till /exception slutpunkten.

Det här avsnittet refererar till följande exempelapp för att demonstrera sätt att hantera undantag i ett minimalt API. Det utlöser ett undantag när slutpunkten /exception begärs:

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

Så här ser du sidan Undantag för utvecklare i ett kontrollantbaserat API:

• Lägg till följande kontrollantåtgärd i ett kontrollantbaserat API. Åtgärden utlöser ett undantag när slutpunkten begärs.

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

• Kör appen i utvecklingsmiljön.

• Gå till slutpunkten som definierats av kontrollantåtgärden.

Om du vill konfigurera Exception Handler Middlewareanropar UseExceptionHandlerdu . Följande kod ändrar till exempel appen så att den svarar med en RFC 7807-kompatibel nyttolast till klienten. Mer information finns i avsnittet Probleminformation senare i den här artikeln.

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. I Program.csanropar UseExceptionHandler du för att lägga till mellanprogrammet undantagshantering:

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

2. Konfigurera en kontrollantåtgärd för att /error svara på vägen:

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

HandleError Föregående åtgärd skickar en RFC 7807-kompatibel nyttolast till klienten.

[ApiExplorerSettings(IgnoreApi = true)]

Överväg följande minimala 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);

Slutpunkten /users skapas 200 OK med en json representation av User när id är större än 0, annars en 400 BAD REQUEST statuskod utan svarstext. Mer information om hur du skapar ett svar finns i Skapa svar i Minimala API-appar.

Status Code Pages middleware Kan konfigureras för att skapa ett gemensamt brödtextinnehåll, när det är tomt, för alla HTTP-klientsvar (400-499) eller server (500 -599). Mellanprogrammet konfigureras genom att anropa tilläggsmetoden UseStatusCodePages .

I följande exempel ändras till exempel appen så att den svarar med en RFC 7807-kompatibel nyttolast till klienten för alla klient- och serversvar, inklusive routningsfel (till exempel 404 NOT FOUND). Mer information finns i avsnittet Probleminformation .

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

För kontrollantbaserade API:er kan felsvaret konfigureras på något av följande sätt:

1. Använda probleminformationstjänsten
2. Implementera ProblemDetailsFactory
3. Använda ApiBehaviorOptions.ClientErrorMapping

Ett felresultat definieras som ett resultat med en HTTP-statuskod på 400 eller högre. För webb-API-kontrollanter transformerar MVC ett felresultat för att skapa en ProblemDetails.

Automatiskt skapande av en ProblemDetails för felstatuskoder är aktiverad som standard.

Minimala API-appar kan konfigureras för att generera probleminformationssvar för alla HTTP-klient- och serverfelsvar som ännu inte har brödtextinnehåll med hjälp AddProblemDetails av tilläggsmetoden.

Följande kod konfigurerar appen för att generera probleminformation:

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

Mer information om hur du använder AddProblemDetailsfinns i Probleminformation

Reserv för IProblemDetailsService

I följande kod httpContext.Response.WriteAsync("Fallback: An error occurred.") returnerar ett fel om implementeringen IProblemDetailsService inte kan generera en 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();

Föregående kod:

• Skriver ett felmeddelande med återställningskoden om det problemDetailsService inte går att skriva en ProblemDetails. Till exempel en slutpunkt där rubriken Acceptera begäran anger en medietyp som DefaulProblemDetailsWriter inte stöds.
• Använder undantagshanterarens mellanprogram.

Följande exempel liknar föregående förutom att det anropar 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);

Probleminformationstjänst

ASP.NET Core har stöd för att skapa probleminformation för HTTP-API:er med hjälp av IProblemDetailsService.

Följande kod konfigurerar appen för att generera ett probleminformationssvar för alla HTTP-klient- och serverfelsvar som inte har brödtextinnehåll ännu:

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

Överväg API-kontrollanten från föregående avsnitt, som returnerar BadRequest när indata är ogiltiga:

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

Ett probleminformationssvar genereras med föregående kod när något av följande villkor gäller:

• Ogiltiga indata anges.
• URI:n har ingen matchande slutpunkt.
• Ett ohanterat undantag inträffar.

Anpassa probleminformation med CustomizeProblemDetails

Följande kod använder ProblemDetailsOptions för att ange 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();

Implementera ProblemDetailsFactory

MVC använder Microsoft.AspNetCore.Mvc.Infrastructure.ProblemDetailsFactory för att producera alla instanser av ProblemDetails och ValidationProblemDetails. Den här fabriken används för:

• Svar på klientfel
• Svar på verifieringsfel
• ControllerBase.Problem och ControllerBase.ValidationProblem

Om du vill anpassa probleminformationssvaret registrerar du en anpassad implementering av ProblemDetailsFactory i Program.cs:

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

Använd ApiBehaviorOptions.ClientErrorMapping

Använd egenskapen ClientErrorMapping för att konfigurera innehållet i ProblemDetails svaret. Följande kod i Program.cs uppdaterar Link till exempel egenskapen för 404-svar:

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

Migrering från kontrollanter till minimala API:er

Om du migrerar från kontrollantbaserade API:er till Minimala API:er:

1. Ersätt åtgärdsfilter med slutpunktsfilter eller mellanprogram
2. Ersätt modellverifiering med manuell validering eller anpassad bindning
3. Ersätt undantagsfilter med undantagshantering av mellanprogram
4. Konfigurera probleminformation med hjälp av AddProblemDetails() konsekventa felsvar

När du ska använda kontrollantbaserad felhantering

Överväg kontrollantbaserade API:er om du behöver:

• Komplexa modellvalideringsscenarier
• Centraliserad undantagshantering över flera styrenheter
• Detaljerad kontroll över formatering av felsvar
• Integrering med MVC-funktioner som filter och konventioner

Detaljerad information om kontrollantbaserad felhantering, inklusive valideringsfel, anpassning av probleminformation och undantagsfilter finns i avsnitten på fliken Kontrollanter .

Svar på verifieringsfel

För webb-API-kontrollanter svarar MVC med en ValidationProblemDetails svarstyp när modellverifieringen misslyckas. MVC använder resultatet av InvalidModelStateResponseFactory för att konstruera felsvaret för ett valideringsfel. I följande exempel ersätts standardfabriken med en implementering som också stöder formateringssvar som XML i 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();

Använd undantag för att ändra svaret

Innehållet i svaret kan ändras utanför kontrollanten med ett anpassat undantag och ett åtgärdsfilter:

1. Skapa en välkänd undantagstyp med namnet 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. Skapa ett åtgärdsfilter med namnet 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;
           }
       }
   }
   

   Föregående filter anger ett Order av det maximala heltalsvärdet minus 10. På Order så sätt kan andra filter köras i slutet av pipelinen.

3. I Program.cslägger du till åtgärdsfiltret i filtersamlingen:

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

Viktiga skillnader för kontrollanter

• Automatisk modellvalidering: Kontrollanter validerar automatiskt modelltillstånd och returnerar 400 Bad Request svar för valideringsfel
• Undantagsfilter: Använd åtgärdsfilter och undantagsfilter för centraliserad felhantering
• Inbyggd probleminformation: Konfigurera ApiBehaviorOptions för standardiserade felsvar
• Anpassade felsvar: ÅsidosättningInvalidModelStateResponseFactory för anpassad valideringsfelformatering