Health Monitoring no ASP.NET MVC

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) { }
}

Anúncios

Geração de Documentação para ASP.NET WebApi

Há algum tempo eu comentei aqui sobre REST e WSDL, onde a ideia era apontar a maneira de se trabalhar com serviços sem a necessidade de ter um schema que define o que serviço disponibiliza e, principalmente, toda a estrutura das mensagens (SOAP) que são trocadas entre as partes.

Mas é importante dizer que mesmo serviços baseados em REST, também precisam, de alguma forma, expor alguma espécie de documentação, para descrever as ações que as APIs estão disponibilizando aos consumidores, apontando o caminho (URI) até aquele ponto, método/verbo (HTTP), informações que precisam ser passadas, formatos suportados, etc.

A ideia é apenas ser informativo, ou seja, isso não será utilizado pelo cliente para a criação automática de uma proxy. Pensando nisso, a Microsoft incluiu no ASP.NET Web API a opção para gerar e customizar as documentações de uma API.

Mas a documentação é sempre exibida, na maioria das vezes, de forma amigável ao consumidor, para que ele possa entender cada uma das ações, suas exigências, para que ele possa construir as requisições da forma correta. Sendo assim, podemos na própria aplicação onde nós temos as APIs, criar um controller que retorna uma view (HTML), contendo a descrição das APIs que estão sendo hospedadas naquela mesma aplicação.

public class DeveloperController : Controller
{
    public ActionResult Apis()
    {
        var explorer = GlobalConfiguration.Configuration.Services.GetApiExplorer();

        return View(explorer.ApiDescriptions);
    }
}

Note que estamos recorrendo ao – novo – método GetApiExplorer, disponibilizado através da configuração global das APIs. Este método retorna um objeto que implementa a interface IApiExplorer, que como o próprio nome sugere, define a estrutura que permite obter a descrição das APIs. Nativamente já temos uma implementação chamada ApiExplorer, que materializa todoas as APIs em instâncias da classe ApiDescription, e uma coleção deste objeto é retornada através da propriedade ApiDescriptions, e que repassamos para que a view possa renderizar isso.

Na view, tudo o que precisamos fazer é iterar pelo modelo, e cada elemento dentro deste laço representa uma ação específica que está dentro da API. A classe que representa a ação, possui várias propriedades, fornecendo tudo o que é necessário para que os clientes possam consumir qualquer ums destas ações. Abaixo temos o código que percorre e exibe cada uma delas:

@model IEnumerable<System.Web.Http.Description.ApiDescription>

<body>
    @foreach (var descriptor in this.Model)
    {
        <ul>
            <li><b>@descriptor.HttpMethod – @descriptor.RelativePath</b></li>
            <li>Documentation: @descriptor.Documentation</li>

            @if (descriptor.SupportedResponseFormatters.Count > 0)
            {
              <li>Media Types
                <ul>
                  @foreach (var mediaType in descriptor.SupportedResponseFormatters.Select(
                     mt => mt.SupportedMediaTypes.First().MediaType))
                  {
                    <li>@mediaType</li>
                  }
                </ul>
              </li>
            }

            @if (descriptor.ParameterDescriptions.Count > 0)
            {
              <li>Parameters
                  <ul>
                    @foreach (var parameter in descriptor.ParameterDescriptions)
                    {
                      <li>Name: @parameter.Name</li>
                      <li>Type: @parameter.ParameterDescriptor.ParameterType</li>
                      <li>Source: @parameter.Source</li>
                    }
                  </ul>
              </li>
            }
        </ul>
    }
</body>

Ao acessar essa view no navegador, temos a relação de todas as ações que estão expostas pelas APIs. A visibilidade das ações é controlada a partir do atributo ApiExplorerSettingsAttribute, que possui uma propriedade boleana chamada IgnoreApi, que quando definida como True, omite a extração e, consequentemente, a sua visualização.

É importante notar que na imagem acima, estamos apresentando a propriedade Documentation. A mensagem que aparece ali é uma customização que podemos fazer para prover essa informação, extraindo-a de algum lugar. Para definir a descrição da ação, vamos criar um atributo customizado para que quando decorado no método, ele será extraído por parte da infraestrutura do ASP.NET, alimentando a propriedade Documentation. O primeiro passo, consiste na criação de um atributo para definir a mensagem:

[AttributeUsage(AttributeTargets.Method, AllowMultiple = false)]
public class ApiDocumentationAttribute : Attribute
{
    public ApiDocumentationAttribute(string message)
    {
        this.Message = message;
    }

    public string Message { get; private set; }
}

O próximo passo é decorá-lo em cada uma das ações que quisermos apresentar uma informação/descrição. A classe abaixo representa a nossa API, e o atributo recentemente criado foi decorado em todas as ações, descrevendo suas respectivas funcionalidades:

public class ClientesController : ApiController
{
    [ApiDocumentation(“Retorna todos os clientes.”)]
    public IEnumerable<Cliente> Get()
    {
        //…
    }

    [ApiDocumentation(“Retorna um cliente pelo seu Id.”)]
    public Cliente Get(int id)
    {
        //…
    }

    [ApiDocumentation(“Inclui um novo cliente.”)]
    public void Post(Cliente cliente)
    {
        //…
    }

    [ApiDocumentation(“Exclui um cliente existente.”)]
    public void Delete(int id)
    {
        //…
    }
}

Só que o atributo por si só não funciona. Precisamos de algum elemento para extrair essa customização que fizemos, e para isso, a temos uma segunda interface, chamada IDocumentationProvider, que fornece dois métodos com o mesmo nome: GetDocumentation. A diferença entre eles é o parâmetro que cada um deles recebe. O primeiro recebe um parâmetro do tipo HttpParameterDescriptor, o que permitirá descrever, também, cada um dos parâmetros de uma determinada ação. Já o segundo método, recebe um parâmetro do tipo HttpActionDescriptor, qual utilizaremos para extrair as informações pertinentes à uma ação específica.

public class ApiDocumentationAttributeProvider : IDocumentationProvider
{
    public string GetDocumentation(HttpParameterDescriptor parameterDescriptor)
    {
        return null;
    }

    public string GetDocumentation(HttpActionDescriptor actionDescriptor)
    {
        var attributes =
            actionDescriptor.GetCustomAttributes<ApiDocumentationAttribute>();

        if (attributes.Count > 0)
            return attributes.First().Message;

        return null;
    }
}

Aqui extraímos o atributo que criamos, e se ele for encontrado, retornamos o valor definido na propriedade Message. A ausência deste atributo, faz com que um valor nulo seja retornado, fazendo com que nenhuma informação extra seja incluída para a ação.

E, finalmente, para incluir o provedor de documentação ao runtime do ASP.NET, recorremos à configuração das APIs, substituindo qualquer implementação existente para este serviço, para o nosso provedor que extraí a documentação do atributo customizado.

GlobalConfiguration.Configuration.Services.Replace(
    typeof(IDocumentationProvider),
    new ApiDocumentationAttributeProvider());

Coletando e analisando arquivos de Dump

Ao instalar uma aplicação em seu local de funcionamento, começa uma nova etapa, que é o monitoramento da mesma, que permite diagnosticar eventuais falhas e tentar trabalhar sempre de uma forma preventiva. Só que muitas vezes, estes problemas podem acontecer durante a execução, problemas estes que podem ser por falta de testes que atendiam aquelas condições, ou ainda, referente à algum problema de infraestrutura.

Se você toma o devido cuidado de catalogar as exceções que estão sendo disparadas, você pode recorrer aos arquivos onde elas estão armazenadas e inspecionar o que aconteceu e, consequentemente, encontrar a região do código responsável por aquele problema, e resolvê-lo, para em seguida, distribuir a correção para ele. Só que para detectar o problema, geralmente precisamos muito mais do que simplesmente o tipo da exceção que foi disparada, mas também quais foram os parâmetros informados, os valores que as variáveis estavam definidas naquele momento, e assim por diante.

Quando estamos em ambiente de desenvolvimento, podemos recorrer ao debugger do Visual Studio para executar a aplicação passo à passo, parando nos pontos que são importantes e naqueles que podem estar ocasionando o problema, e atenciosamente analisar e detectar o problema. Só que se essa aplicação já estiver em funcionamento, isso não é possível, pelo menos não de uma forma simples. Neste caso podemos recorrer a criação de um arquivo de dump da aplicação em questão. Ao gerar este arquivo, ele “fotografa” o estado atual do processo e gera várias informações para que possamos depurá-la mais tarde, algo mais ou menos parecido com o reporte de bugs do Windows.

Esse recurso é algo que podemos utilizar tanto em aplicações cliente como aquelas que rodam em um servidor, como é o caso de aplicações ASP.NET ou de serviços WCF. No caso de aplicações cliente, você pode recorrer ao Doctor Watson do Windows ou indo diretamente através da Task Manager. Como eu quero demonstrar a coleta do dump de um serviço WCF, vamos recorrer à segunda opção. Como sabemos, ao hospedar um serviço WCF no IIS, quem será responsável por executá-lo é um processo, chamado de w3wp.exe, que pode ser configurado através da opção Application Pools. Abaixo temos a imagem que ilustra como extrair o dump do processo do IIS:

Basicamente, este serviço recebe uma requisição e gera uma massa de informações para o respectivo cliente. Depois do arquivo de dump criado (extensão *.dmp), você receberá uma notificação informando onde ele foi salvo. Tudo o que precisamos fazer agora, é abrir o arquivo no Visual Studio 2010. A partir desta versão, o Visual Studio é capaz de interpretar esses arquivos. Ao abrí-lo, você irá se deparar com uma página, que detalha as informações sobre o processo. Podemos visualizar o nome do processo de onde o dump foi extraído, versão do sistema operacional, da CLR, etc. Outro ponto importante são os módulos que foram carregados à este processo, que aqui, por questões de espaço, não estão sendo exibidos todos eles. A imagem abaixo ilustra este resumo:

Como este arquivo contém o estado da aplicação naquele momento, o Visual Studio nos permite analisar o estado das informações (variáveis, parâmetros, etc.) que tínhamos, de uma forma tão simples quanto depurar a aplicação. Só que para isso funcionar, é necessário definirmos os símbolos, que são responsáveis por armazenarem informações para guiar o debugger até o código fonte. A opção “Set symbol paths” nos permite definir o endereço até o arquivo *.pdb, gerado durante o desenvolvimento do serviço.

Depois disso definido, podemos clicar na opção “Debug with Mixed”, e o debugger do Visual Studio entra em ação. Ele lerá as informações contidas no arquivo de dump e irá exibí-las através das ferramentas de depuração que o próprio Visual Studio já nos fornece. A imagem que veremos a seguir já é uma dessas ferramentas: a janela Parallel Stacks. Essa janela é útil para depurarmos aplicações multi-thread, como é o caso de serviços WCF. Como podemos visualizar, temos a stack da execução e dentro dela, a chamada para o método Executar, que faz parte do serviço criado para o teste.

Ao clicar com o botão direito em um dos itens, podemos alternar entre as threads que estavam em execução naquele momento, acessando a operação Executar. Note que entre parênteses há o valor do parâmetro que está sendo passado para a operação. Abaixo temos a imagem que ilustra as três threads que temos em execução:

Finalmente, ao selecionar uma das opções listadas na imagem acima, somos encaminhados para o código correspondente, conseguindo visualizar o estado das informações, simplesmente passando o mouse por cima das mesmas. Além disso, você ainda pode recorrer as janelas de depuração que já existem há algum tempo no Visual Studio, como é caso das janelas de Threads, Modules e Locals, que trazem informações pertinentes aquele código que está sendo depurado no momento. A imagem abaixo exibe o estado das variáveis e parâmetros da operação Executar no momento em que o arquivo de dump foi gerado: