Manipular erros em APIs de ASP.NET Core

Observação

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

Aviso

Esta versão do ASP.NET Core não tem mais suporte. Para obter mais informações, consulte o .NET e .NET Core Support Policy. Para ver a versão atual, consulte a versão .NET 10 deste artigo.

APIs mínimas

Este artigo descreve como lidar com erros em APIs de ASP.NET Core. A documentação para APIs Mínimas está selecionada. Para ver a documentação das APIs baseadas em controlador, selecione a guia Controllers. Para diretrizes de tratamento de erros, consulte Blazor.

Controllers

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

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 de desenvolvedor é executada no início do pipeline do middleware, para que ela possa capturar exceções sem tratamento lançadas no middleware subsequente.

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

• Em execução no ambiente Development.
• 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 Development ambiente. 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 Core ambientes de runtime.

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 Registro em log para obter informações de erro completas.

A imagem a seguir mostra um exemplo de página de exceção de desenvolvedor, 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

APIs mínimas

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

• Execute o aplicativo de exemplo no Development ambiente.
• Acesse o endpoint /exception.

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 lança uma exceção quando o endpoint /exception é 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();

Controllers

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 lança uma exceção quando o endpoint é 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 que não são de desenvolvimento, use o middleware de tratamento de exceções para gerar uma carga de erro.

APIs mínimas

Para configurar a exception handler middleware, chame 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();

Controllers

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

   [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 erro 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)]

Permitir acesso anônimo ao método se os usuários não autenticados devem 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 endpoint produz 200 OK com uma representação json de User quando id é maior que 0; caso contrário, 400 BAD REQUEST código de status sem corpo de resposta. Para obter mais informações sobre como criar uma resposta, consulte Criar respostas em aplicativos de API mínimos.

O Status Code Pages middleware pode ser configurado para produzir um conteúdo comum para o corpo, quando vazio, para todas as respostas de cliente HTTP (400-499) ou de 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 ao cliente com uma carga útil compatível com RFC 7807 para todas as respostas de cliente e de 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);

Controllers

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 de API HTTP; no entanto, eles geralmente são usados para relatar erros para APIs HTTP.

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

Em aplicativos ASP.NET Core, o middleware a seguir gera respostas HTTP de detalhes do problema quando AddProblemDetails é chamado, exceto quando o cabeçalho HTTP da solicitação Accept não inclui um dos tipos de conteúdo compatíveis com o IProblemDetailsWriter registrado (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 de API mínima podem ser configurados para gerar respostas com detalhes do problema para todas as respostas de erro HTTP do cliente e do servidor que ainda não têm corpo, usando o método de extensão AddProblemDetails.

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 o problemDetailsService não conseguir gravar um ProblemDetails. Por exemplo, um ponto de extremidade em que o cabeçalho de solicitação Accept especifica um tipo de mídia ao qual o DefaultProblemDetailsWriter não oferece suporte.
• Usa o middleware de tratamento de exceções.

Observação

O DefaultProblemDetailsWriter suporta os seguintes tipos de mídia no cabeçalho de solicitação Accept:

• application/json
• application/problem+json
• Tipos curinga, como */* e application/*

Tipos de mídia não JSON, como application/xml ou text/html, não têm suporte e disparam o comportamento de fallback.

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

Controllers

Serviço de detalhes sobre o 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 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 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.
• Ocorreu uma exceção não tratada.

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

Implementa 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 por falha de validação
• ControllerBase.Problem e ControllerBase.ValidationProblem

Para personalizar a resposta de detalhes sobre o problema, registre uma implementação personalizada de ProblemDetailsFactory em 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 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 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. Substitua filtros de ação por filtros de endpoint 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ções
4. Configurar detalhes do problema usando AddProblemDetails() para respostas de erro consistentes

Quando usar o tratamento de erros baseado em controlador

Considere APIs baseadas em controlador se 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 .

Controllers

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 de InvalidModelStateResponseFactory para construir a resposta de erro em caso de falha de validação. O exemplo a seguir substitui a fábrica padrão por uma implementação que também oferece 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();

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 sejam 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: Substitua InvalidModelStateResponseFactory para personalizar a formatação dos erros de validação

Recursos adicionais

• Como usar a validação modelstate em ASP.NET Core API Web
• Visualize ou baixe o código de exemplo
• Hellang.Middleware.ProblemDetails