Como Adicionar Rastreamento aos Módulos Gerenciados do IIS 7.0

  • Artigo

por Saad Ladki

Introdução

O IIS 7.0 e superiores permite o uso de plug-ins e módulos gerenciados desenvolvidos sob medida para realizar várias tarefas diferentes e usar esses módulos para todo tipo de conteúdo. No entanto, a pergunta surge: o que acontece se o módulo tiver problemas ou dificuldades? Antes, você usava o System.Diagnostics para rastrear o evento quando ocorriam problemas. Infelizmente, esses rastreamentos são completamente separados dos rastreamentos do IIS.

Não é assim com o IIS 7.0 e superior. Agora você pode adicionar rastreamentos ao código do módulo usando System.Diagnostics.TraceSource (novo no .Net 2.0). Você pode rotear esses rastreamentos para a infraestrutura de rastreamento do IIS para que eles estejam disponíveis para módulos que consomem rastreamentos, por exemplo, Rastreamento de Solicitação com Falha.

A equipe do IIS incentiva a instrumentação de código usando padrões básicos, como:

  • Eventos START e STOP relativos a atividades-chave dentro do código
  • Eventos WARNINGe ERROR para ocorrências inesperadas que podem causar falha na solicitação (como autenticação com falha)
  • Eventos INFORMATIONAL e VERBOSE para obter ajuda com o diagnóstico, como a configuração do módulo que está sendo usada

As tarefas ilustradas neste passo a passo incluem:

  • Adicionar rastreamento ao módulo usando System.Diagnostics.TraceSource
  • Configurar o rastreamento de solicitação com falha para capturar esses rastreamentos
  • Gerar a condição de falha e exibindo o rastreamento resultante

Pré-requisitos

Siga as etapas abaixo antes de executar as tarefas neste artigo.

Etapa 1: Instalar o IIS

Primeiro, o IIS deve ser instalado. Verifique se o IIS está instalado navegando até http://localhost/. Se o IIS estiver instalado, você verá a página "em construção". Se o IIS não estiver instalado, consulte Como instalar o IIS para obter instruções. Instale os seguintes componentes do IIS:

  • ASP (em World Wide Web Services => recursos de desenvolvimento de aplicativos => ASP)
  • ASP.Net (em World Wide Web Services => Recursos de desenvolvimento de aplicativos => ASP.Net)
  • Rastreamento (em World Wide Web Services => Integridade e diagnóstico => Rastreamento)

Etapa 2: Fazer logon como Administrador

Faça logon como na conta de administrador ou no grupo Administradores.

Observação

Estar no grupo Administradores não concede privilégios completos de administrador por padrão. Você deve executar muitos aplicativos como Administrador. Clique com o botão direito do mouse no ícone do aplicativo e escolha "Executar como administrador".

Etapa 3: Fazer um backup

Faça um backup da configuração antes de executar as tarefas neste artigo. Execute o seguinte:

  1. Clique no botão Iniciar –> Todos os Programas –> Acessórios –> (r-click)Prompt de Comando –> Executar como Administrador
    Screenshot of the Windows Start menu with a focus on the Run as administrator option in the right-click drop-down menu.

  2. Execute o seguinte comando no prompt de comando:

    %windir%\system32\inetsrv\appcmd add backup

Etapa 4: Criar conteúdo de exemplo

  1. Exclua tudo na pasta c:\inetpub\wwwroot.
  2. No prompt de comando administrador iniciado acima, cole o código anexado em um arquivo em inetpub\wwwroot chamado test.htm:
<h2>HOWTO: Adding tracing to modules </h2>

This is a sample page served by the static file handler (native code).

Criar e rastrear um módulo simples

Nesta seção, você vai criar um módulo de exemplo para o instrumento.

Etapa 1: Criar um módulo simples

Usando o prompt de comando administrador, copie e cole o seguinte código em um arquivo chamado IIS_MOD_REQDATA.cs:

using System;
using System.Collections.Generic;
using System.Text;
using System.Web;

namespace IIS_MOD_REQDATA
{
    public class IIS_MOD_REQDATA : IHttpModule
    {
        public void Init(HttpApplication application)
        {
            application.EndRequest += (new EventHandler(this.Application_EndRequest));
        }

        private void Application_EndRequest(Object source, EventArgs e)
        {
            HttpApplication application = (HttpApplication)source;
            HttpContext context = application.Context;

            // start writing out the request data

            context.Response.Write("<hr>");
            context.Response.Write("<b><font size=2 color=green>REQUEST HEADERS</font></b><br>");
            context.Response.Write("<font size=2>");
            context.Response.Write("METHOD : " + context.Request.HttpMethod + "<br>");
            context.Response.Write("URL : " + context.Request.Url + "<br>");
            context.Response.Write("QUERYSTRING : " + context.Request.QueryString + "<br>");
            context.Response.Write("</font><br>");

            // now response data

            context.Response.Write("<b><font size=2 color=blue>RESPONSE HEADERS</font></b><br>");
            context.Response.Write("<font size=2>");
            context.Response.Write("STATUS CODE : " + context.Response.StatusCode.ToString() + "." + context.Response.SubStatusCode.ToString() + "<br>");
            context.Response.Write("CONTENT TYPE : " + context.Response.ContentType.ToString() + "<br>");
            context.Response.Write("EXPIRES : " + context.Response.Expires.ToString() + "<br>");
            context.Response.Write("</font><br>");

            // set cache policy on response so it's not cached.

            context.Response.DisableKernelCache();
        }

        public void Dispose()
        {
        }
    }
}

Etapa 2: Adicionar rastreamento ao módulo gerenciado

Para adicionar o rastreamento ao módulo e rotear seus eventos de rastreamento para o IIS, use a origem System.Diagnostics.Trace. Adicione a seguinte linha nas instruções using:

using System.Diagnostics;

Você deve criar um TraceSource dentro do código – observe a definição do traceSource dentro da declaração do módulo IIS_MOD_REQDATA:

public class IIS_MOD_REQDATA : IHttpModule
{
    TraceSource tsStatus;

O membro tsStatus é inicializado durante o método Init() do IHttpModule:

public void Init(HttpApplication application)    
{    
    application.EndRequest += (new EventHandler(this.Application_EndRequest));
    // setup traceSource
    tsStatus = new TraceSource("tsStatus");    
}

O nome do TraceSource ("tsStatus") é importante, pois é referenciado depois no arquivo web.config. O módulo agora está configurado para emitir eventos, se necessário.

Para adicionar um evento de rastreamento, use tsStatus.TraceEvent(<type>, 0, <somestring>) para gravar eventos. Adicione os eventos Start e End recomendados ao método Application_EndRequest():

private void Application_EndRequest(Object source, EventArgs e)        
{    
    tsStatus.TraceEvent(TraceEventType.Start, 0, "[REQDATA MODULE] START EndRequest");

    // other code

    tsStatus.TraceEvent(TraceEventType.Stop, 0, "[REQDATA MODULE] END EndRequest");    
}

Observe os >diferentes< tipos – os tipos com suporte, entre outros, incluem:

  • TraceEventType.Start
  • TraceEventType.Stop
  • TraceEventType.Error
  • TraceEventType.Warning
  • TraceEventType.Information
  • TraceEventType.Verbose

Para abranger todo o conteúdo, todo a origem para o módulo (incluindo os eventos de rastreamento) pode ser copiada daqui:

using System;
using System.Collections.Generic;
using System.Text;
using System.Web;
using System.Diagnostics;

namespace IIS_MOD_REQDATA
{
    public class IIS_MOD_REQDATA : IHttpModule
    {

        TraceSource tsStatus;

        public void Init(HttpApplication application)
        {
            application.EndRequest += (new EventHandler(this.Application_EndRequest));

            // TRACING

            tsStatus = new TraceSource("tsStatus");
        }

        private void Application_EndRequest(Object source, EventArgs e)
        {
            HttpApplication application = (HttpApplication)source;
            HttpContext context = application.Context;

            tsStatus.TraceEvent(TraceEventType.Start, 0, "[REQDATA MODULE] START EndRequest");

            // start writing out the request data

            context.Response.Write("<hr>");
            context.Response.Write("<b><font size=2 color=green>REQUEST HEADERS</font></b><br>");
            context.Response.Write("<font size=2>");
            context.Response.Write("METHOD : " + context.Request.HttpMethod + "<br>");
            context.Response.Write("URL : " + context.Request.Url + "<br>");
            context.Response.Write("QUERYSTRING : " + context.Request.QueryString + "<br>");
            context.Response.Write("</font><br>");

            tsStatus.TraceEvent(TraceEventType.Verbose, 0, "[REQDATA MODULE] done with Req Data, moving onto Response");

            // now response data

            context.Response.Write("<b><font size=2 color=blue>RESPONSE HEADERS</font></b><br>");
            context.Response.Write("<font size=2>");
            context.Response.Write("STATUS CODE : " + context.Response.StatusCode.ToString() + "." + context.Response.SubStatusCode.ToString() + "<br>");
            context.Response.Write("CONTENT TYPE : " + context.Response.ContentType.ToString() + "<br>");
            context.Response.Write("EXPIRES : " + context.Response.Expires.ToString() + "<br>");
            context.Response.Write("</font><br>");

            if (context.Response.StatusCode > 399)
            {
                tsStatus.TraceEvent(TraceEventType.Warning, 0, "[REQDATA MODULE] error status code detected");
            }

            tsStatus.TraceEvent(TraceEventType.Verbose, 0, "[REQDATA MODULE] done with Response Data");

            // set cache policy on response so it's not cached.

            context.Response.DisableKernelCache();
            tsStatus.TraceEvent(TraceEventType.Verbose, 0, "[REQDATA MODULE] cache setting is (" + context.Response.Cache.ToString() + ")");

            tsStatus.TraceEvent(TraceEventType.Stop, 0, "[REQDATA MODULE] STOP - EndRequest");
        }

        public void Dispose()
        {
        }
    }
}

Etapa 3: Compilar nosso módulo rastreado

Agora, para compilar o módulo e implantá-lo. Em um prompt de comando de elevado (administrador), execute o seguinte comando:

%systemroot%\Microsoft.NET\Framework\v2.0.50727\csc.exe /target:library /out:IIS_MOD_REQDATA.dll /debug /d:TRACE /R:System.Web.dll IIS_MOD_REQDATA.cs

Screenshot of the exclamation code dash consoleMain command in Notepad.

Observação

Se você estiver executando isso em um sistema de 64 bits, compile usando o compilador C# de 64 bits no %windir%\microsoft.net\framework64\v2.0.50727\csc.exe

Observe o uso das opções /debug e /d:TRACE. Você deve usar essas opções para compilar os eventos de rastreamento no binário. Não compilar com essas opções significa que o módulo não terá nenhum evento de rastreamento.

Depois de compilar o módulo, implante o módulo e execute um teste inicial para ver se o módulo funciona antes de capturar seus rastreamentos.

Adicionar módulos à configuração do site

Esta seção inclui adicionar e testar o módulo.

Etapa 1: Adicionar o módulo à configuração do site

  1. Usando o mesmo prompt de comando administrador, crie um diretório chamado \inetpub\wwwroot\bin e copie IIS_MOD_REQDATA.dll para esse diretório.
  2. Habilite o módulo. No prompt de comando do administrador, digite start inetmgr para abrir a interface do usuário de administração do IIS.
  3. No painel Conexões, expanda o nome do computador local e depois Sites, então clique em Site Padrão.
  4. No IIS no painel central, clique duas vezes em Módulos:
    Screenshot of the Default Web Site Home screen with the Modules option being highlighted.
  5. Você verá uma grande lista de módulos configurados para uso por este site. No lado direito da interface do usuário em Ações, clique em Adicionar Módulo Gerenciado:
    Screenshot of the Actions pane with a focus on the Add Managed Module option.
  6. Na janela exibida, dê ao módulo o nome gerenciado IIS_MOD_REQDATA e o tipo do módulo é IIS_MOD_REQDATA.IIS_MOD_REQDATA (selecione isso na caixa de lista suspensa):
    Screenshot of the Add Managed Module dialog box, showing the Name and Type fields.
  7. Clique em OK. O módulo recém-rastreado agora está configurado para uso do site.
    Screenshot of the Modules screen, showing the newly traced module.

Etapa 2: Testar nosso módulo

Teste o módulo abrindo o Internet Explorer e navegando até http://localhost/test.htm. Você verá a seguinte janela:

Screenshot of a webpage reading here is a sample page that is served by static file handler.

O conteúdo "CABEÇALHOS DE SOLICITAÇÃO" e "CABEÇALHOS DE RESPOSTA" veio do nosso módulo, indicando que isso funciona.

Rotear eventos para o IIS

Esta tarefa conecta o TraceSource do Módulo ao rastreamento do IIS para que seus eventos sejam emitidos por meio do IIS e então configura o Rastreamento de Solicitação de Falha para capturar esses eventos de rastreamento.

Etapa 1: Habilitar o TraceSource do módulo e rotear seus eventos para o IIS

O módulo é atualizado para incluir eventos de rastreamento. Configure System.Diagnostics e IIS para capturar esses eventos de rastreamento e roteá-los para o módulo de Falha no rastreamento da solicitação do IIS. Faça isso configurando a seção <system.diagnostics> no arquivo web.config para configurar o TraceSource e rotear seus eventos de acordo.

  1. Usando o prompt de comando Administrador, navegue até c:\inetpub\wwwroot e use o bloco de notas para editar seu arquivo web.config.

  2. É preciso concluir três configurações para que os eventos emitidos pelo módulo sejam roteados para a infraestrutura de rastreamento do IIS:

    • Definir o evento traceListener do IIS como um ouvinte compartilhado
    • Definir um comutador para habilitar todos os eventos
    • Definir a origem do rastreamento, anexando o comutador que definimos, bem como definindo o ouvinte de rastreamento para nossa origem.

  3. O IIS envia um novo System.Diagnostics.TraceListener usado para rotear eventos TraceSource para a infraestrutura de rastreamento do IIS. Esse provedor também deve ser definido em seu arquivo web.config.

  4. Define o traceSource pelo seu nome (tsStatus) e conecte-o ao DefaultSwitch e ao IisTraceListener.

  5. Copie e cole esta seção <system.Diagnostics> em seu arquivo web.config (após sua seção <system.webServer>).

    <system.diagnostics>
    <sharedListeners>
      <add name="IisTraceListener" type="System.Web.IisTraceListener, System.Web, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" />
    </sharedListeners>

    <switches>
      <add name="DefaultSwitch" value="All" />
    </switches>

    <sources>
      <source name="tsStatus" switchName="DefaultSwitch">
        <listeners>
          <add name="IisTraceListener" type="System.Web.IisTraceListener, System.Web, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" />
        </listeners>
      </source>
    </sources>
</system.diagnostics>

O traceSource tsStatus é conectado ao IIS7TraceListener, que emitirá eventos para a infraestrutura de rastreamento do IIS. Siga para a próxima etapa para conectar esses eventos ao provedor de rastreamento de solicitação com falha.

Etapa 2: Habilitar o rastreamento de solicitação com falha para capturar eventos de rastreamento de módulo

Quando esses eventos de diagnóstico são emitidos na infraestrutura de rastreamento do IIS, eles são mapeados para o Provedor ASP.net e o sinalizador do Módulo nesse provedor. Seu detalhamento depende do TraceEventType usado. Para configurar o Rastreamento de Solicitação com Falha para selecioná-los:

  1. No prompt de comando administrador, digite start inetmgr. No painel Conexões, expanda o nome do computador e a pasta Sites, então clique no Site Padrão. À direita, no painel Ações, clique no link Rastreamento de Solicitação com Falha… em Configurar:
    Screenshot of the Manage Web Site section of the Actions pane, with the Failed Request Tracing option being highlighted.

  2. Na próxima caixa de diálogo, configure o seguinte:
    Screenshot of the Edit Web Site Failed Request Tracing Settings dialog box.

  3. Marque a caixa de seleção Habilitar. Mantenha os padrões para as outras configurações. Clique em OK para continuar.

  4. Agora que verificamos se o Registro em log de rastreamento de solicitações com falha está habilitado, devemos configurar as definições de falha. De volta ao Gerenciador do IIS, no IIS, clique duas vezes em Regras de Rastreamento de Solicitação com Falha
    Screenshot of the Default Web Site Home screen with the Failed Request Tracing Rules option being highlighted.

  5. No painel Ações, clique em Adicionar… Isso inicia o assistente Adicionar Regra de Rastreamento de Solicitação Com Falha.

  6. Na página Especificar Conteúdo a Rastrear, selecione a opção Todo o Conteúdo (*) para o que rastrear. Clique em Avançar.
    Screenshot of the Add Failed Request Tracing Rule page with a focus on the Next option.

  7. Na tela Definir Condições de Rastreamento, marque a caixa de seleção Códigos de Status e insira "200" como o código de status a ser rastreado.
    Screenshot of the Define Trace Conditions screen with the Status codes field being checked.

  8. Clique em Avançar. A página Selecionar Provedores de Rastreamento é exibida. Marque a caixa de seleção ASPNET e as caixas de seleção Módulo e Página em "Áreas". Em Detalhamento, selecione Detalhado.
    Screenshot of the Select Trace Providers screen with the ASPNET Provider option being highlighted.

    Observação

    Devido a um bug em builds do Server Beta 3, os rastreamentos de módulo só poderão ser capturados se as áreas Módulo e Página estiverem selecionadas. Após o Server Beta 3, apenas o Módulo é necessário para coletar esses eventos.

  9. Clique em Concluir. Você verá a seguinte definição para o Site Padrão:
    Screenshot of the Failed Request Tracing Rules screen.

Testar e exibir os resultados

Nesta tarefa, geramos a solicitação com falha e exibimos o log de rastreamento resultante. Lembre-se de que configuramos o IIS para capturar logs de rastreamento para solicitações http://localhost/* que falham com um 200. Para verificar se funcionou:

  1. Abra uma janela do Internet Explorer. Digite o endereço http://localhost/test.htm. Mais uma vez, você verá o seguinte:
    Screenshot of the sample webpage in an Internet Explorer window.
  2. Para verificar se o módulo gerou rastreamentos que foram capturados, use uma janela do Internet Explorer com privilégios elevados ao administrador, pressione CTRL-O e navegue até c:\inetpub\logs\FailedReqLogFiles\W3SVC1. Na caixa de lista suspensa que diz Arquivos HTML, selecione Todos os Arquivos.
  3. Selecione o arquivo fr######.xml mais recente (data de hoje) e clique em Abrir. Você verá os eventos:
    Screenshot of the Request Diagnostics screen, showing the Custom Module Traces tab.

Resumo

Você terminou de adicionar um evento de rastreamento a um módulo gerenciado, compilou e implantou esse módulo, configurou o System.Diagnostics para rotear seus eventos para a infraestrutura de rastreamento do IIS e, por fim, configurou o recurso rastreamento de solicitação com falha do IIS para capturar seus eventos. Agora você pode adicionar com facilidade novos eventos ao módulo e recompilar o módulo e implantá-lo no diretório \bin. Usando o Rastreamento de Solicitação com Falha, você verá os resultados dos eventos.

Lembre-se de que usar System.Diagnostics.TraceSource permite que você ainda use seu módulo e rastreie o nível inferior de eventos de rastreamento, desde que você o conecte a outro ouvinte de rastreamento.