Manipular erros em APIs do ASP.NET Core

Observação

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

Advertência

Esta versão do ASP.NET Core não é mais suportada. Para obter mais informações, consulte a Política de suporte do .NET e do .NET Core. Para a versão atual, consulte a versão .NET 9 deste artigo.

APIs mínimas

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

Controladores

Este artigo descreve como lidar com erros em ASP.NET APIs principais. 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 Blazor obter orientações sobre tratamento de erros, consulte Manipular erros em aplicativos ASP.NET CoreBlazor.

Página de exceção do desenvolvedor

A página de exceção do desenvolvedor exibe informações detalhadas sobre 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 de middleware, para que possa capturar exceções não tratadas lançadas no middleware a seguir.

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

• 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.

Advertência

Não habilite a Página de Exceção do Desenvolvedor , a menos que o aplicativo esteja sendo executado 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 Core runtime environments.

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 da cadeia de caracteres de consulta, se houver
• Cookies, se existirem
• Headers
• Metadados do ponto final, se houver

Não é garantido que a Página de Exceção do Desenvolvedor forneça nenhuma informação. Use o registro em log para obter informações completas sobre erros.

A imagem a seguir mostra uma página de exceção de 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 lança uma exceção quando o ponto de extremidade /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();

Controladores

Para ver a página de exceção do desenvolvedor em uma API baseada em controlador:

• Adicione a seguinte ação do controlador a uma API baseada em controlador. A ação lança 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ções

Em ambientes que não sejam de desenvolvimento, use o Exception Handler Middleware para produzir uma carga útil de erro.

APIs mínimas

Para configurar o , chame Exception Handler Middleware.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. No 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 à /error rota:

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

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

Advertência

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 cheguem ao método de ação.

Para APIs da 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 acesso anônimo ao método se usuários não autenticados devem ver o erro.

Respostas de erro do cliente e do servidor

APIs mínimas

Considere o seguinte aplicativo de API mínima.

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 quando User é maior que id, caso contrário, um 0 código de status sem um corpo de 400 BAD REQUEST resposta. Para obter mais informações sobre como criar uma resposta, consulte Criar respostas em aplicativos de API mínima.

O Status Code Pages middleware pode 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 do cliente e do 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 um resultado com um código de status HTTP de 400 ou superior. Para controladores de API da Web, o MVC transforma um resultado de erro para produzir um ProblemDetailsarquivo .

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

Detalhes do problema

Detalhes do problema não são o único formato de resposta para descrever um erro de API HTTP, no entanto, eles são comumente usados para relatar erros para APIs HTTP.

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

Nos 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 suportados pelo registrado IProblemDetailsWriter (padrão: application/json):

• ExceptionHandlerMiddleware: Gera uma resposta de detalhes do problema quando um manipulador personalizado não está 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 Accept da solicitação não inclui text/html.

APIs mínimas

Aplicativos de API mínimos podem ser configurados para gerar resposta de detalhes de problema para todas as respostas de erro de cliente e servidor HTTP que ainda não têm conteúdo de corpo usando o AddProblemDetails método de 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 o AddProblemDetails, consulte Detalhes do problema

Fallback IProblemDetailsService

No código a seguir, httpContext.Response.WriteAsync("Fallback: An error occurred.") retorna 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 escrever um ProblemDetailsarquivo . Por exemplo, um ponto de extremidade em que o cabeçalho Aceitar solicitação especifica um tipo de mídia que o DefaulProblemDetailsWriter não suporta.
• Usa o middleware do manipulador de exceções.

O exemplo a seguir é semelhante ao anterior, exceto que ele chama 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 suporta a 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 corporal:

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 não tratada.

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

Implementar 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 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 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. Substitua filtros de ação por filtros de ponto de extremidade ou middleware
2. Substitua a validação do modelo pela validação manual ou vinculação personalizada
3. Substitua 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 modelos
• Tratamento centralizado de exceções em vários controladores
• Controle refinado sobre a formatação da resposta a erros
• Integração com recursos MVC, como filtros e convenções

Para obter informações detalhadas sobre o tratamento de erros com base no 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 da Web, o MVC responde com um tipo de ValidationProblemDetails resposta quando a validação do modelo falha. O MVC usa os resultados de para construir a resposta de erro para uma falha de InvalidModelStateResponseFactory 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 do valor inteiro máximo menos 10. Isso Order permite que outros filtros sejam executados no final do pipeline.

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

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

Principais diferenças para os controladores

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

Recursos adicionais

• Como usar a validação ModelState na API Web principal ASP.NET
• Ver ou transferir código de exemplo
• Hellang.Middleware.ProblemDetails