Há algum tempo eu escrevi aqui sobre o ApiExplorer, que é uma funcionalidade que nos permite expor uma documentação sobre a nossa API. Basicamente ela consiste em nos fornecer metadados dos controllers, ações, parâmetros e resultados para que assim possamos criar uma interface amigável com o usuário (leia-se outro desenvolvedor).

Apesar de termos certa flexibilidade na criação e exibição da documentação, o nosso foco sempre é desenvolvermos a funcionalidade proposta pela API, enquanto a documentação sempre fica em segundo plano, e que na maioria das vezes, nem sempre ganha a atenção que merece. Vale lembrar que é isso que o mundo externo irá utilizar para estudar antes de consumir.

Existe uma especificação chamada Swagger, que tenta padronizar as informações extraídas da APIs Web e, consequentemente, expor de uma forma intuitiva e com bastante riqueza ao mundo. Além do padrão, ainda existe um conjunto de ferramentas (consulte o site oficial), e entre elas, tenho a Swagger UI, que consiste em um conjunto de documentos CSS, HTML e Javascript, e que dinamicamente geram uma interface rica com todas as informações extraídas da API, incluindo o formato das mensagens de requisição e resposta, e ainda, uma opção para já invocar as ações que estão disponíveis, sem precisar recorrer à outras ferramentas, tais como Fiddler. Como um diferencial, os parâmetros já são mapeados e consistidos pela própria interface, garantido que os tipos estejam de acordo com o esperado pela API.

Vale lembrar que o Swagger é completamente independente de plataforma, e não é algo exclusivo do .NET ou da Microsoft. Felizmente existe uma pacote chamado Swashbuckle, que nada mais é que uma implementação desta especificação para Web APIs escritas com o ASP.NET, e que nos bastidores, recorre ao ApiExplorer para gerar a documentação neste – novo – padrão. Por fim, com uma simples linha de código, é possível fazer com que a nossa API tenha uma documentação extremamente rica. Para utiliza-la, basta adicionar o pacote através do Nuget, conforme vemos no comando abaixo:

PM> Install-Package Swashbuckle

Depois de instalado, podemos perceber a criação de uma arquivo chamado SwaggerConfig.cs, que já habilita as configurações mais básicas para o seu funcionamento. Abaixo temos a versão simplificada dela, mas se reparar na classe gerada pela instalação do pacote, há uma série de comentários que são bastante autoexplicativos em relação a cada funcionalidade que ela expõe.

public class SwaggerConfig
{
    public static void Register()
    {
        var thisAssembly = typeof(SwaggerConfig).Assembly;

        GlobalConfiguration.Configuration
            .EnableSwagger(c => c.SingleApiVersion(“v1”, “Minha API”))
            .EnableSwaggerUi();
    }
}

Com essa configuração realizada, ao rodar a aplicação e colocar /swagger depois do endereço (url) onde está rodando o serviço, teremos a interface com os métodos da nossa API sendo exibidos.

E ao clicar em um dos botões “Try It Out”, mais detalhes da requisição e da resposta serão apresentados, e também a ação será invocada na API. Note que se estivéssemos optando por testar uma ação que estivesse sendo exposta através do método HTTP POST, um textarea seria exibido para que você colocasse o corpo da requisição (em JSON ou XML, você escolhe) para assim enviar ao serviço.

Guardando-se as devidas proporções, para quem trabalha ou já trabalhou com SOAP, pode notar certa semelhança com o WSDL (Swagger) e com o SOAP UI (Swagger UI), onde o que vimos aqui, é voltando para o ambiente REST.

Em algumas situações precisamos, de alguma forma, catalogar as seções que são acessadas em uma aplicação Web para fins de auditoria ou até mesmo log de segurança. Uma técnica que é comumente utilizada é ter uma página ou ação que receba toda a demanda para qualquer link que se clique, e a partir de parâmetros que são colocadas em querystrings, este centralizador será capaz de realizar o log, e em seguida, redirecionar o usuário para a página solicitada.

Podemos eleger uma ação que será a centralizadora e todos os links serão renderizados apontando para ela incluindo o parâmetro o caminho da ação real a ser executada. No exemplo abaixo, o método responsável para fazer tudo isso será o RedirectUser.

public class TesteController : Controller
{
    public ActionResult Index()
    {
        return View();
    }

    public ActionResult Executar()
    {
        return View();
    }

    public ActionResult RedirectUser(string path)
    {
        //realiza o log

        return Redirect(path);
    }
}

Se acompanharmos o fluxo através de algum monitor de tráfego HTTP, veremos o redirecionamento sendo realizado. Vale lembrar que os redirecionamentos que estão sendo feitos aqui são realizados pelo navegados, exigindo o round-trip (código 302) entre o cliente e o serviço. Esse round-trip pode ser visualizado na imagem abaixo, através do ícone branco que está no segundo item da listagem.

Para facilitar estes cenários, o HTML 5 introduziu um novo atributo no elemetro <a /> chamando ping. Enquanto o atributo href deve ser o link de destino para o recurso desejado, o atributo ping servirá para apontar a ação que será utilizada para realizar o log quando o usuário clicar no respectivo link. A finalidade deste log vai ser, de fato, apenas catalogar o clique sem a necessidade de redirecionar o usuário para o local desejado/solicitado. Abaixo o exemplo de como configurar este atributo:

<a ping=”/Teste/Log” href=”/Teste/Executar”>Executar</a>

A imagem abaixo ilustra o procedimento em execução, postando assincronamente para o método Log enquanto também já encaminha o usuário para o destino clicado.

O interessante é que é realizado um POST para o método Log, incluindo várias informações extremamente relevantes, tais como a origem e o destino do ping, que podem ser capturadas pela ação de log para catalogar as informações das seções que foram solicitadas/acessadas. Abaixo temos as mensagens extraídas do Fiddler contendo os headers que foram enviados para o método Log neste exemplo, que faz uso também de um novo MIME que é o text/ping. O ponto negativo é que nem todos os navegadores implementaram este recurso. Infelizmente ele está somente implementando no Chrome e no Safari. Já há uma requisição aberta para que o time do Internet Explorer faça a adequação para suportar este atributo.

[ Requisição ]

POST http://localhost:17479/Teste/Log HTTP/1.1
Host: localhost:17479
Connection: keep-alive
Content-Length: 4
Cache-Control: max-age=0
Origin: null
Ping-From: http://localhost:17479/Teste/Index
User-Agent: Mozilla/5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/33.0.1750.117 Safari/537.36
Ping-To: http://localhost:17479/Teste/Executar
Content-Type: text/ping
Accept: */*
Accept-Encoding: gzip,deflate,sdch
Accept-Language: pt-BR,pt;q=0.8,en-US;q=0.6,en;q=0.4

PING

[ Resposta ]

HTTP/1.1 200 OK
Cache-Control: private
Server: Microsoft-IIS/8.0
X-AspNetMvc-Version: 5.0
X-AspNet-Version: 4.0.30319
X-SourceFiles: =?UTF-8?B?QzpcVXNlcnNcSXNyYWVsXERlc2t0b3BcV2ViQXBwbGljYXRpb24xXFdlYkFwcGxpY2F0aW9uMVxUZXN0ZVxMb2c=?=
X-Powered-By: ASP.NET
Date: Wed, 26 Feb 2014 02:01:12 GMT
Content-Length: 0

Para todo e qualquer tipo de aplicação, uma necessidade que temos é a captura dos erros não tratados pela aplicação e o log destes, para que seja possível a depuração e análise depois que o problema acontecesse, sendo necessário incluir o máximo de informações relevantes para essa apuração.

Apesar de existir algumas técnicas já bastante conhecidas no ASP.NET, a versão 2.1 do ASP.NET Web API, a Microsoft criou um novo namespace chamado System.Web.Http.ExceptionHandling e colocou ali alguns recursos específicos para a interceptação e log das exceções disparadas e não tratadas em qualquer nível da API, ou seja, tanto para as exceções que ocorrem no interior do código dos controllers, bem como os códigos de infraestrutura (formatadores, handlers, etc.).

Para utilizar este serviço de log, devemos recorrer à interface IExceptionLogger, que define um único método chamado LogAsync, que como o próprio nome sugere, já traz suporte para realizar esta tarefa de forma assíncrona, passando como parâmetro para ele uma instância da classe ExceptionLoggerContext, qual contém toda informação pertinente ao problema que ocorreu e onde ocorreu (ExceptionContext). Para facilitar as implementações, também já existe uma classe chamada ExceptionLogger, que implementa esta interface define um método chamado Log, que é onde customizeremos o log da exceção que ocorreu.

Para exemplificar, o código abaixo captura a exceção que ocorreu e armazena em um arquivo texto toda a stack trace. Só que criar a classe não é suficiente, pois precisamos acoplá-la à exceção, e para isso, devemos recorrer novamente ao arquivo Global.asax, que está logo no próximo trecho de código.

public class ExceptionTextLogger : ExceptionLogger
{
    private readonly string filePath;

    public ExceptionTextLogger(string filePath)
    {
        this.filePath = filePath;
    }

    public override void Log(ExceptionLoggerContext context)
    {
        File.AppendAllText(filePath, context.Exception.ToString());
    }
}

config.Services.Add(typeof(IExceptionLogger), 
    new ExceptionTextLogger(@”C:TempLog.txt”));

Quando as exceções ocorrem, lembrando que não são somente aquelas exceções referentes ao código que escrevemos no interior da API, mas incluem também os erros que ocorrem dentro das partes referente à infraestrutura, todos eles são repassados para os loggers configurados na aplicação.

Depois que o log é realizado, entra em cena um novo recurso chamado de exception handler. Este recurso que a Microsoft criou nos permitirá avaliar o erro que ocorreu e determinar se a exceção deverá ou não ser disparada. Caso o handler opte por não tratar o erro que ocorreu, a exceção será lançada. Aqui é feito o uso da classe ExceptionDispatchInfo, que captura o contexto onde ocorreu a exceção e posterga o disparo até que o handler faça a análise da mesma.

Seguindo a mesma estrutura do logger, temos uma interface chamada IExceptionHandler que fornece um método assíncrono chamado HandleAsync, recebendo como parâmetro uma classe chamada ExceptionHandlerContext, que informa os detalhes sobre o problema ocorrido através da propriedade ExceptionContext. E, novamente, temos uma classe base chamada ExceptionHandler com a implementação básica da interface IExceptionHandler, qual já podemos utilizar em nosso código:

public class ExceptionMessageHandler : ExceptionHandler
{
    public override void Handle(ExceptionHandlerContext context)
    {
        if (context.Exception is BusinessException)
            context.Result = new BusinessBadRequest(context);
    }

    private class BusinessBadRequest : IHttpActionResult
    {
        private readonly ExceptionHandlerContext exceptionContext;

        public BusinessBadRequest(ExceptionHandlerContext exceptionContext)
        {
            this.exceptionContext = exceptionContext;
        }

        public Task<HttpResponseMessage> ExecuteAsync(CancellationToken cancellationToken)
        {
            return Task.FromResult(
                this.exceptionContext.Request.CreateErrorResponse(
                    HttpStatusCode.BadRequest, 
                    new HttpError(this.exceptionContext.Exception, true)));
        }
    }
}

O código acima implementa o método Handle e avalia se a exceção que ocorreu foi do tipo BusinessException. Caso tenha sido, ele cria uma mensagem de retorno específica, atribuindo à propriedade Result. Caso essa propriedade não seja abastecida (no nosso caso, se não for uma BusinessException), então o ASP.NET Web API irá disparar o erro. E, finalmente, para colocá-lo em execução, vamos recorrer ao arquivo Global.asax:

config.Services.Replace(typeof(IExceptionHandler), new BusinessExceptionHandler());

Desde as primeiras versões do ASP.NET MVC, a Microsoft criou um atributo chamado HandleErrorAttribute, que nada mais do que um filtro (de exceção) e tem a finalidade de interceptar todas as exceções que não são tratadas pelas ações “in-place”. E este filtro pode ser aplicado em nível de ação, de controller ou globalmente, no arquivo Global.asax e, este último nível, já vem configurado por padrão nos projetos ASP.NET MVC.

Este atributo garante com que qualquer exceção não seja exibida no navegador, apresentando aquela tela com detalhes do erro e que o usuário final dificilmente entende. Em sua configuração padrão, quando este atributo é acionado, ele redireciona o usuário para uma view chamada Error. Mas tanto o acionamento quanto a view a ser exibida pode ser customizada em qualquer nível, recorrendo às propriedades ExceptionType e View, conforme é mostrado no trecho de código abaixo. É importante dizer que este atributo pode ser decorado múltiplas vezes, possibilitando a seleção da view de acordo com a exceção que foi disparada.

[HandleError(ExceptionType = typeof(DivideByZeroException), View = “DivideByZeroException”)]
public class SiteController : Controller { }

Simplesmente o fato de existir este atributo decorado na ação, na classe ou globalmente, não é suficiente para acioná-lo, a não ser que configuremos a seção de customErrors no arquivo Web.Config. Esta seção está presente desde a primeira versão do ASP.NET, e agora pode e deve ser usada em conjunto com o atributo HandleErrorAttribute para garantir ou não o redirecionamento do usuário para a view desejada. A configuração mínima para o correto funcionamento deste atributo deve ser:

<configuration>
  <system.web>
    <customErrors mode=”On” />
  </system.web>
</configuration>

E uma vez que o atributo é adicionado, o ASP.NET passará a redirecionar o usuário para a view que exibirá a mensagem amigável. Só que além disso, o ASP.NET MVC faz captura o controller, da ação e da exceção que foi disparada, e configura a instância da classe HandleErrorInfo com todas essas informações referente ao erro que ocorreu, e a adiciona na propriedade ViewData da view que será exibida. Isso irá permitir capturar as informações para exibir na tela caso seja necessário informar ao usuário os detalhes do erro que ocorreu.

@model System.Web.Mvc.HandleErrorInfo

<html>
<head>
    <title>Error</title>
</head>
<body>
   

</body>
</html>

É importante mencionar que o atributo HandlerErrorAttribute somente é acionado, por padrão, quando há erros de número 500 do HTTP. Para outros casos, como 401 (Unauthorized), ele não é acionado e, consequentemente, o erro é exibido para o usuário. Para garantir que seja apresentado, também de forma amigável, outros erros que não sejam do tipo 500, podemos recorrer ao customErrors especificando o erro e a respectiva página de erro que deve ser apresentada quando o mesmo ocorrer.

<customErrors mode=”On”>
  <error statusCode=”401″ redirect=”/401.htm” />
  <error statusCode=”404″ redirect=”/404.htm” />
</customErrors>

Para finalizar, é importante se atentar em casos onde uma determinada ação (que faz uso deste atributo) é utilizada também por uma aplicação Javascript, pois quando um erro ocorrer, neste cenário o que o cliente está esperando é uma mensagem do erro e não um redirecionamento para uma view. A ideia é que o erro seja tratado pelo próprio cliente (Javascript), que exibirá alguma informação para informar o erro. Uma opção aqui seria herdar da classe HandleErrorAttribute e avaliar se a ação está ou não sendo invocada por uma aplicação Javascript, e para isso, podemos recorrer ao header X-Requested-With, verificando se é igual à XMLHttpRequest, retornando um objeto do tipo JsonResult devidamente configurado.

Há uma funcionalidade que foi criada no ASP.NET 2.0 chamada de Health Monitoring. Este recurso foi desenvolvido para servir como tratador de eventos que ocorrem em uma aplicação web. Utilizando um schema de configuração bastante elaborado, podemos customizar quais tipos de eventos queremos armazenar, onde será salvo, com qual periodicidade, intervalo, etc. Entre os tipos de eventos disponíveis, podemos citar: o sucesso e/ou falha no login, páginas não encontradas, erros não tratados, e assim por diante.

Apesar dela ter sido criada quando ainda não existia o ASP.NET MVC, isso não quer dizer que não pode utilizá-la com este tipo de projeto. O Health Monitoring trata-se de uma funcionalidade de “nível global”, onde você poderá utilizar em qualquer tipo de projeto ASP.NET (WebForms ou MVC). Sendo assim, para habilitar este recurso em uma aplicação MVC, basta realizar uma configuração no arquivo Web.config, conforme é mostrado abaixo. Note que estamos optando por armazenar os eventos no Event Log do Windows:

<system.web>
  <healthMonitoring enabled=”true”>
    <rules>
      <clear />
      <add
        name=”All Errors Default”
        eventName=”All Errors”
        provider=”EventLogProvider”
        profile=”Default”
        minInterval=”00:01:00″/>
    </rules>
  </healthMonitoring>
</system.web>

Vale lembrar que exceções não tratadas são catalogadas como esperado, porém o ASP.NET MVC possui um atributo chamado HandleErrorAttribute, que tem a finalidade de interceptar as requisições para este atributo quando uma exceção não tratada ocorre dentro da ação que está sendo requisitada, e ele, por sua vez, reencaminha a requisição para uma View padrão chamada Error, para exibir uma mensagem amigável ao usuário.

Para garantir que esta exceção também seja catalogada pelo Health Monitoring, é necessário criarmos um evento customizado, herdando da classe WebRequestErrorEvent. Essa classe será utilizada por uma customização da classe HandleErrorAttribute, onde invocaremos dentro do método OnException, o método Raise da classe WebRequestErrorEvent, passando a ele a exceção capturada pelo ASP.NET. Com isso, todas as exceções não tratadas serão encaminhadas para o atributo CatalogarErroNoHealthMonitoring, catalogadas pelo Health Monitoring e, finalmente, o usuário será redirecionado para a View Error (padrão do MVC).

public class CatalogarErroNoHealthMonitoring : HandleErrorAttribute
{
    public override void OnException(ExceptionContext filterContext)
    {
        base.OnException(filterContext);
        new DescricaoDeErro(this, filterContext.Exception).Raise();
    }
}

public class DescricaoDeErro : WebRequestErrorEvent
{
    private static readonly int eventCode = WebEventCodes.WebExtendedBase + 1;

    public DescricaoDeErro(object eventSource, Exception exception)
        : base(“Exceção Não Tratada”, eventSource, eventCode, exception) { }
}