Como tratar exceções através de Middleware do ASP.NET Core

Neste artigo vou apresentar uma maneira de tratar exceções em uma API ASP.NET Core utilizando o Middleware de Exception Handler.

Como funciona

Na classe Startup, mais especificamente no método Configure utilizando a interface IApplicationBuilder, é possível configurar um Exception Handler, que atuará como um Middleware e permitirá manipular a resposta que será retornada pela API.

Logo abaixo mostrarei o passo a passo para definir e utilizar um Exception Handler.

Criando o Controller e Action

O primeiro passo é definir uma rota para a Action que vai ser executada após a exceção acontecer. Geralmente se cria um Controller para isso, e é preciso ignorar a Action para que o Swagger funcione corretamente.

Na imagem abaixo é mostrado o código do Controller e Action a serem utilizados. Note que utilizo injeção de dependência para obter IWebHostEnvironment e poder controlar as informações retornadas baseado no ambiente. Cada caso é um caso, então dependendo do seu uso você poderá realizar outras operações, como Logging.

Além disso, utilizo o atributo ApiExplorerSettings junto com a propriedade IgnoreApi para que a Action seja ignorada pelo Swagger. Já o atributo Route é utilizado para definir a rota da Action de erro.

A classe ErrorController e Action Get para tratamento de exceções

Note o retorno Problem. Ele resulta em um objeto de tipo ProblemDetails, com código 500 para o usuário, junto com detalhes como Type (tipo do problema), Detail (detalhes do problema) e Title (título do problema). Ele segue um padrão de informações que visa definir os dados que representam detalhes de problemas.

Além disso, note que é possível checar informações sobre a exceção, permitindo realizar outra operação caso ela seja de algum tipo específico.

Configurando na classe Startup

Em seguida, na classe Startup e método Configure, basta adicionar IApplicationBuilder.UseExceptionHandler, passando a rota da Action a ser chamada em caso de exceção.

app.UseExceptionHandler("/error");

Lembrar de remover outros Exception Handlers, como o app.UseDeveloperExceptionPage(); que já vem adicionado por padrão.

Testando o Exception Handler

Adiciono o código abaixo para provocar um erro bem conhecido por nós desenvolvedores, para então verificar o retorno.

throw new NullReferenceException();

Executando uma Action que conheça essa linha em seu início, o objeto abaixo é retornado. Utilizei a Action Get do Controller que é criado por padrão no projeto, chamado WeatherForecastController.

Mensagem de erro padronizada

Lembrando que você pode alterar o conteúdo do objeto dependendo do seu ambiente de execução.


Inscreva-se na lista de espera do Método .NET Direto ao Ponto, um treinamento completo sobre C#, APIs com ASP.NET Core e Microsserviços:  Inscreva-se aqui.

São quase 200 vídeo-aulas sobre temas como C#, ASP NET Core 5, EF Core, CQRS, Clean Architecture, Autenticação e autorização com JWT, Testes Unitários, além de mini-cursos em Microsserviços, Performance em .NET, ASP NET Core e Azure, Docker, Carreira Internacional em .NET, e mais.


Espero que o artigo possa ter contribuído em seu conhecimento, até o próximo!