Manipular erros nas APIs principais do ASP.NET

Observação

Esta não é a versão mais recente deste artigo. Para a versão atual, consulte a versão do .NET 10 deste artigo.

Aviso

Esta versão do ASP.NET Core não tem mais suporte. Para obter mais informações, consulte a Política de Suporte do .NET e do .NET Core. Para informações sobre a versão vigente, confira a versão .NET 9 deste artigo.

APIs mínimas

Este artigo descreve como lidar com erros nas APIs principais do ASP.NET. A documentação para APIs Mínimas está selecionada. Para ver a documentação das APIs baseadas em controlador, selecione a guia Controladores. Para obter diretrizes de Blazor tratamento de erros, consulte Manipular erros em aplicativos do ASP.NET CoreBlazor.

Controladores

Este artigo descreve como lidar com erros nas APIs principais do ASP.NET. A documentação para APIs baseadas em controlador está selecionada. Para ver a documentação de APIs mínimas, selecione a guia APIs Mínimas. Para obter diretrizes de Blazor tratamento de erros, consulte Manipular erros em aplicativos do ASP.NET CoreBlazor.

Página exceção do desenvolvedor

A Página de Exceção do Desenvolvedor exibe informações detalhadas sobre exceções de solicitação sem tratamento. Ele usa DeveloperExceptionPageMiddleware para capturar exceções síncronas e assíncronas do pipeline HTTP e gerar respostas de erro. A página de exceção do desenvolvedor é executada no início do pipeline do middleware, para que ele possa capturar exceções sem tratamento geradas no middleware a seguir.

ASP.NET Principais aplicativos habilitam a página de exceção do desenvolvedor por padrão quando ambos:

• Em execução no ambiente de desenvolvimento.
• O aplicativo foi criado com os modelos atuais, ou seja, usando WebApplication.CreateBuilder.

Os aplicativos criados usando modelos anteriores, ou seja, usando WebHost.CreateDefaultBuilder, podem habilitar a página de exceção do desenvolvedor chamando app.UseDeveloperExceptionPage.

Aviso

Não habilite a Página de Exceção do Desenvolvedor, a menos que o aplicativo esteja em execução no ambiente de desenvolvimento. Não compartilhe informações detalhadas de exceção publicamente quando o aplicativo for executado em produção. Para obter mais informações sobre como configurar ambientes, consulte ASP.NET Ambientes de runtime do Core.

A Página de Exceção do Desenvolvedor pode incluir as seguintes informações sobre a exceção e a solicitação:

• Rastreamento de pilha
• Parâmetros de cadeia de caracteres de consulta, se houver
• Cookies, se houver
• Headers
• Metadados de ponto de extremidade, se houver

A Página de Exceção do Desenvolvedor não tem garantia de fornecer nenhuma informação. Use o registro em log para obter informações de erro completas.

A imagem a seguir mostra uma página de exceção do desenvolvedor de exemplo com animação para mostrar as guias e as informações exibidas:

Em resposta a uma solicitação com um Accept: text/plain cabeçalho, a Página de Exceção do Desenvolvedor retorna texto sem formatação em vez de HTML. Por exemplo:

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

APIs mínimas

Para ver a página de exceção do desenvolvedor em uma API mínima:

• Execute o aplicativo de exemplo no ambiente de desenvolvimento.
• Vá para o /exception ponto de extremidade.

Esta seção refere-se ao aplicativo de exemplo a seguir para demonstrar maneiras de lidar com exceções em uma API Mínima. Ele gera uma exceção quando o ponto /exception de extremidade é solicitado:

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

Controladores

Para ver a Página de Exceção do Desenvolvedor em uma API baseada em controlador:

• Adicione a ação do controlador a seguir a uma API baseada em controlador. A ação gera uma exceção quando o ponto de extremidade é solicitado.

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

• Execute o aplicativo no ambiente de desenvolvimento.

• Vá para o ponto de extremidade definido pela ação do controlador.

Manipulador de exceção

Em ambientes de não desenvolvimento, use o Middleware do Manipulador de Exceções para produzir um conteúdo de erro.

APIs mínimas

Para configurar a Exception Handler Middlewarechamada UseExceptionHandler. Por exemplo, o código a seguir altera o aplicativo para responder com uma carga compatível com RFC 7807 para o cliente. Para obter mais informações, consulte a seção Detalhes do Problema mais adiante neste artigo.

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

Controladores

1. Em Program.cs, chame UseExceptionHandler para adicionar o middleware de tratamento de exceção:

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

2. Configure uma ação do controlador para responder à /error rota:

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

A ação anterior HandleError envia um conteúdo compatível com RFC 7807 para o cliente.

Aviso

Não marque o método de ação do manipulador de erros com atributos de método HTTP, como HttpGet. Verbos explícitos impedem que algumas solicitações atinjam o método de ação.

Para APIs Web que usam Swagger/OpenAPI, marque a ação do manipulador de erros com o atributo [ApiExplorerSettings] e defina sua IgnoreApi propriedade como true. Essa configuração de atributo exclui a ação do manipulador de erros da especificação OpenAPI do aplicativo:

[ApiExplorerSettings(IgnoreApi = true)]

Permita o acesso anônimo ao método se os usuários não autenticados deverem ver o erro.

Respostas de erro de cliente e servidor

APIs mínimas

Considere o aplicativo de API Mínimo a seguir.

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

O /users ponto de extremidade produz 200 OK com uma json representação de User quando id é maior que 0, caso contrário, um 400 BAD REQUEST código de status sem um corpo de resposta. Para obter mais informações sobre como criar uma resposta, consulte Criar respostas em aplicativos de API mínimos.

Pode Status Code Pages middleware ser configurado para produzir um conteúdo de corpo comum, quando vazio, para todas as respostas de cliente HTTP (400-499) ou servidor ().500 -599 O middleware é configurado chamando o método de extensão UseStatusCodePages .

Por exemplo, o exemplo a seguir altera o aplicativo para responder com uma carga compatível com RFC 7807 para o cliente para todas as respostas de cliente e servidor, incluindo erros de roteamento (por exemplo, 404 NOT FOUND). Para obter mais informações, consulte a seção Detalhes do Problema .

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

Controladores

Para APIs baseadas em controlador, a resposta de erro pode ser configurada de uma das seguintes maneiras:

1. Usar o serviço de detalhes do problema
2. Implementar ProblemDetailsFactory
3. Usar ApiBehaviorOptions.ClientErrorMapping

Um resultado de erro é definido como resultado com um código de status HTTP igual a 400 ou superior. Para controladores de API Web, o MVC transforma um resultado de erro para produzir um ProblemDetails.

A criação automática de um ProblemDetails para códigos de status de erro é habilitada por padrão.

Detalhes do problema

Os detalhes do problema não são o único formato de resposta a descrever um erro da API HTTP, no entanto, eles geralmente são usados para relatar erros para APIs HTTP.

O serviço de detalhes do problema implementa a IProblemDetailsService interface, que dá suporte à criação de detalhes do problema no ASP.NET Core. O AddProblemDetails(IServiceCollection) método de extensão no IServiceCollection registro da implementação padrão IProblemDetailsService .

Em aplicativos ASP.NET Core, o middleware a seguir gera respostas HTTP de detalhes do problema quando AddProblemDetails é chamado, exceto quando o Accept cabeçalho HTTP da solicitação não inclui um dos tipos de conteúdo com suporte pelo registrado IProblemDetailsWriter (padrão: application/json):

• ExceptionHandlerMiddleware: gera uma resposta de detalhes do problema quando um manipulador personalizado não é definido.
• StatusCodePagesMiddleware: gera uma resposta de detalhes do problema por padrão.
• DeveloperExceptionPageMiddleware: gera uma resposta de detalhes do problema no desenvolvimento quando o cabeçalho HTTP da solicitação Accept não inclui text/html.

APIs mínimas

Aplicativos mínimos de API podem ser configurados para gerar a resposta de detalhes do problema para todas as respostas de erro do cliente HTTP e do servidor que ainda não têm conteúdo do corpo usando o método de AddProblemDetails extensão.

O código a seguir configura o aplicativo para gerar detalhes do problema:

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

Para obter mais informações sobre como usar AddProblemDetails, consulte Detalhes do problema

Fallback IProblemDetailsService

No código a seguir, httpContext.Response.WriteAsync("Fallback: An error occurred.") retornará um erro se a IProblemDetailsService implementação não for capaz de gerar um 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();

O código anterior:

• Grava uma mensagem de erro com o código de fallback se não problemDetailsService for possível gravar um ProblemDetails. Por exemplo, um ponto de extremidade em que o cabeçalho aceitar solicitação especifica um tipo de mídia que DefaulProblemDetailsWriter não dá suporte.
• Usa o middleware do manipulador de exceções.

O exemplo a seguir é semelhante ao anterior, exceto pelo fato de chamar o 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);

Controladores

Serviço de detalhes do problema

ASP.NET Core dá suporte à criação de Detalhes do Problema para APIs HTTP usando o IProblemDetailsService.

O código a seguir configura o aplicativo para gerar uma resposta de detalhes do problema para todas as respostas de erro do cliente HTTP e do servidor que ainda não têm conteúdo do corpo:

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

Considere o controlador de API da seção anterior, que retorna BadRequest quando a entrada é inválida:

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

Uma resposta de detalhes do problema é gerada com o código anterior quando qualquer uma das seguintes condições se aplica:

• Uma entrada inválida é fornecida.
• O URI não tem nenhum ponto de extremidade correspondente.
• Ocorre uma exceção sem tratamento.

Personalizar detalhes do problema com CustomizeProblemDetails

O código a seguir usa ProblemDetailsOptions para definir 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();

Implemento ProblemDetailsFactory

O MVC usa Microsoft.AspNetCore.Mvc.Infrastructure.ProblemDetailsFactory para produzir todas as instâncias de ProblemDetails e ValidationProblemDetails. Esta fábrica é usada para:

• Respostas de erro do cliente
• Respostas de erro de falha de validação
• ControllerBase.Problem e ControllerBase.ValidationProblem

Para personalizar a resposta de detalhes do problema, registre uma implementação personalizada deProblemDetailsFactory:Program.cs

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

Utilize ApiBehaviorOptions.ClientErrorMapping

Use a ClientErrorMapping propriedade para configurar o conteúdo da ProblemDetails resposta. Por exemplo, o código a seguir atualiza Program.cs a Link propriedade para 404 respostas:

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

Recursos adicionais de tratamento de erros

APIs mínimas

Migração de controladores para APIs mínimas

Se você estiver migrando de APIs baseadas em controlador para APIs mínimas:

1. Substituir filtros de ação por filtros de ponto de extremidade ou middleware
2. Substituir validação de modelo por validação manual ou associação personalizada
3. Substituir filtros de exceção por middleware de tratamento de exceção
4. Configurar detalhes do problema usando AddProblemDetails() respostas de erro consistentes

Quando usar o tratamento de erros baseado em controlador

Considere AS APIs baseadas em controlador se você precisar:

• Cenários complexos de validação de modelo
• Tratamento centralizado de exceções entre vários controladores
• Controle refinado sobre a formatação de resposta de erro
• Integração com recursos do MVC, como filtros e convenções

Para obter informações detalhadas sobre o tratamento de erros baseados em controlador, incluindo erros de validação, personalização de detalhes do problema e filtros de exceção, consulte as seções da guia Controladores .

Controladores

Resposta de erro de falha de validação

Para controladores de API Web, o MVC responde com um ValidationProblemDetails tipo de resposta quando a validação do modelo falha. O MVC usa os resultados para construir a resposta de InvalidModelStateResponseFactory erro para uma falha de validação. O exemplo a seguir substitui a fábrica padrão por uma implementação que também dá suporte a respostas de formatação como XML, em 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();

Usar exceções para modificar a resposta

O conteúdo da resposta pode ser modificado de fora do controlador usando uma exceção personalizada e um filtro de ação:

1. Crie um tipo de exceção conhecido chamado 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. Crie um filtro de ação chamado 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;
           }
       }
   }
   

   O filtro anterior especifica um Order valor inteiro máximo menos 10. Isso Order permite que outros filtros são executados no final do pipeline.

3. In Program.cs, adicione o filtro de ação à coleção de filtros:

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

Principais diferenças para controladores

• Validação automática de modelo: controladores validam automaticamente o estado do modelo e retornam 400 Bad Request respostas para falhas de validação
• Filtros de exceção: usar filtros de ação e filtros de exceção para tratamento centralizado de erros
• Detalhes do problema interno: configurar ApiBehaviorOptions para respostas de erro padronizadas
• Respostas de erro personalizadas: substituir InvalidModelStateResponseFactory a formatação de erro de validação personalizada

Recursos adicionais

• Como usar a validação modelstate na API Web do ASP.NET Core
• Exibir ou baixar o código de exemplo
• Hellang.Middleware.ProblemDetails