Identificador de erros nas APIs da Web baseadas no controlador do ASP.NET Core

Este artigo descreve como lidar com erros e personalizar o tratamento de erros nas APIs da Web do ASP.NET Core baseadas no controlador. Para obter informações sobre o tratamento de erros nas APIs mínimas, consulte Identificador de erros no ASP.NET Core e Identificador de erros nas APIs mínimas.

Página de exceção do desenvolvedor

A Página de exceção do desenvolvedor exibe informações detalhadas sobre as exceções de solicitação não tratadas. Ele usa DeveloperExceptionPageMiddleware para capturar exceções síncronas e assíncronas do pipeline HTTP e para 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.

Os aplicativos ASP.NET Core 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 ativar 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 de exceção detalhadas publicamente quando o aplicativo é executado em produção. Para obter mais informações sobre como configurar ambientes, confira Use vários ambientes no ASP.NET 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
• Cabeçalhos
• Metadados de ponto de extremidade, se houver

Não existe garantia de que a Página de Exceção do Desenvolvedor fornecerá alguma informação. Use 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 cabeçalho Accept: text/plain, 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

Para ver a Página de Exceção do Desenvolvedor:

• Adicione a ação do controlador a seguir a uma API baseada no 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.

• Acesse o ponto de extremidade definido pela ação do controlador.

Manipulador de exceção

Em ambientes de não desenvolvimento, use o Middleware de Tratamento de Exceções para produzir um payload de erro:

1. Em Program.cs, chame UseExceptionHandler para adicionar o Middleware de Tratamento de Exceções:

   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 à rota /error:

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

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

Aviso

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

Para APIs web que usam Swagger/OpenAPI, marque a ação do manipulador de erros com o atributo [ApiExplorerSettings] e defina sua propriedade IgnoreApi 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 tiverem que ver o erro.

O Middleware de Tratamento de Exceções também pode ser usado no ambiente de desenvolvimento para produzir um formato de payload consistente em todos os ambientes:

1. No Program.cs, registre instâncias de Middleware de Tratamento de Exceção específicas do ambiente:

   if (app.Environment.IsDevelopment())
   {
       app.UseExceptionHandler("/error-development");
   }
   else
   {
       app.UseExceptionHandler("/error");
   }
   

   No código anterior, o middleware é registrado com:

   • uma rota de /error-development no ambiente de Desenvolvimento.
   • Uma rota de /error em ambientes de Não Desenvolvimento.

2. Adicione ações de controlador para as rotas Desenvolvimento e Não Desenvolvimento:

   [Route("/error-development")]
   public IActionResult HandleErrorDevelopment(
       [FromServices] IHostEnvironment hostEnvironment)
   {
       if (!hostEnvironment.IsDevelopment())
       {
           return NotFound();
       }
   
       var exceptionHandlerFeature =
           HttpContext.Features.Get<IExceptionHandlerFeature>()!;
   
       return Problem(
           detail: exceptionHandlerFeature.Error.StackTrace,
           title: exceptionHandlerFeature.Error.Message);
   }
   
   [Route("/error")]
   public IActionResult HandleError() =>
       Problem();
   

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 do valor inteiro máximo menos 10. Esse Order permite que outros filtros sejam executados no final do pipeline.

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

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

Resposta de erro de falha de validação

Para controladores de API web, o MVC responde com um tipo de resposta ValidationProblemDetails quando a validação do modelo falha. O MVC usa os resultados de InvalidModelStateResponseFactory para construir a resposta de 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 à formatação de respostas 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();

Resposta de erro do cliente

Um resultado de erro é definido como um resultado com um código de status HTTP de 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, mas as respostas de erro podem ser configuradas usando uma das seguintes maneiras:

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

Resposta padrão aos detalhes do problema

O arquivo Program.cs a seguir foi gerado pelos modelos de aplicativo Web para controladores de API:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Considere o seguinte controlador, 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 for aplicável:

• O ponto de extremidade /api/values2/divide é chamado com um denominador zero.
• O ponto de extremidade /api/values2/squareroot é chamado com um radicando menor que zero.

O corpo da resposta aos detalhes do problema padrão tem os seguintes valores type, title e status:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "traceId": "00-84c1fd4063c38d9f3900d06e56542d48-85d1d4-00"
}

Serviço de detalhes do problema

O ASP.NET Core dá suporte à criação de Detalhes do Problema para APIs HTTP usando o IProblemDetailsService. Para obter mais informações, confira a seção Serviço de detalhes do problema.

O código a seguir configura o aplicativo para gerar uma resposta de detalhes do problema para todas as respostas de erro do cliente e servidor HTTP que ainda não possuem conteúdo no 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 da 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 for aplicável:

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

A criação automática de um ProblemDetails para códigos de status de erro fica desabilitada quando a propriedade SuppressMapClientErrors é definida como true:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
        options.SuppressMapClientErrors = true;
    });

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Usando o código anterior, quando um controlador de API retorna BadRequest, um status de resposta HTTP 400 é retornado sem nenhum corpo de resposta. SuppressMapClientErrors impede que uma resposta ProblemDetails seja criada, mesmo ao chamar WriteAsync para um ponto de extremidade do Controlador de API. O WriteAsync é explicado posteriormente neste artigo.

A próxima seção mostra como personalizar o corpo da resposta aos detalhes do problema, usando CustomizeProblemDetails, para retornar uma respostas mais útil. Para obter mais opções de personalização, confira como Personalizar detalhes do problema.

Personalizar detalhes do problema com CustomizeProblemDetails

O código abaixo 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();

O controlador de API atualizado:

[Route("api/[controller]/[action]")]
[ApiController]
public class ValuesController : ControllerBase
{
    // /api/values/divide/1/2
    [HttpGet("{Numerator}/{Denominator}")]
    public IActionResult Divide(double Numerator, double Denominator)
    {
        if (Denominator == 0)
        {
            var errorType = new MathErrorFeature
            {
                MathError = MathErrorType.DivisionByZeroError
            };
            HttpContext.Features.Set(errorType);
            return BadRequest();
        }

        return Ok(Numerator / Denominator);
    }

    // /api/values/squareroot/4
    [HttpGet("{radicand}")]
    public IActionResult Squareroot(double radicand)
    {
        if (radicand < 0)
        {
            var errorType = new MathErrorFeature
            {
                MathError = MathErrorType.NegativeRadicandError
            };
            HttpContext.Features.Set(errorType);
            return BadRequest();
        }

        return Ok(Math.Sqrt(radicand));
    }

}

O código a seguir contém MathErrorFeature e MathErrorType, que são usados com o exemplo anterior:

// Custom Http Request Feature
class MathErrorFeature
{
    public MathErrorType MathError { get; set; }
}

// Custom math errors
enum MathErrorType
{
    DivisionByZeroError,
    NegativeRadicandError
}

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

• O ponto de extremidade /divide é chamado com um denominador zero.
• O ponto de extremidade /squareroot é chamado com um radicando menor que zero.
• O URI não tem nenhum ponto de extremidade correspondente.

O corpo da resposta aos detalhes do problema contém o seguinte quando qualquer ponto de extremidade squareroot é chamado com um radicando menor que zero:

{
  "type": "https://en.wikipedia.org/wiki/Square_root",
  "title": "Bad Input",
  "status": 400,
  "detail": "Negative or complex numbers are not allowed."
}

Exibir ou baixar o código de exemplo

Implementa ProblemDetailsFactory

O MVC usa Microsoft.AspNetCore.Mvc.Infrastructure.ProblemDetailsFactory para produzir todas as instâncias de ProblemDetails e ValidationProblemDetails. Este alocador é usado para:

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

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

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

Use ApiBehaviorOptions.ClientErrorMapping.

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

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

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