Demonstra Passo a passo: Filtragem de saída do My.Application.Log (Visual Basic)

Artigo
08/01/2011

Essa explicação passo a passo demonstra como alterar a filtragem de log padrão filtrando do objeto My.Application.Log, para controlar quais informações são passadas do objeto Log para os ouvintes e quais informações são escritas pelos ouvintes. Você pode alterar o comportamento de log, mesmo após a criação do aplicativo, porque as informações de configuração são armazenadas no arquivo de configuração do aplicativo.

Guia de Introdução

Cada mensagem que My.Application.Log grava possui um nível de gravidade associado, que os mecanismos de filtragem usam para controlar a saída de log. Este aplicativo de exemplo usa métodos de My.Application.Log para gravar diversas mensagens de log com níveis diferentes de gravidade.

Criar o aplicativo de exemplo

Abra um novo projeto de Aplicativo do Windows Visual Basic.
Adicione um botão denominado Button1 para Form1.

No manipulador de eventos Click para Button1, adicione o seguinte código:

' Activity tracing information
My.Application.Log.WriteEntry("Entering Button1_Click", TraceEventType.Start)

' Tracing information
My.Application.Log.WriteEntry("In Button1_Click", TraceEventType.Information)

' Create an exception to log.
Dim ex As New ApplicationException
' Exception information
My.Application.Log.WriteException(ex)

' Activity tracing information
My.Application.Log.WriteEntry("Leaving Button1_Click", TraceEventType.Stop)

Execute o aplicativo no depurador.
Pressione Button1.

O aplicativo grava as informações a seguir para no arquivo de saída e no log de depuração do aplicativo.

DefaultSource Information: 0 : In Button1_Click

DefaultSource Error: 2 : Error in the application.
Feche o aplicativo.

Para obter informações sobre como exibir a janela de saída de depuração do aplicativo, consulte Janela de saída.. Para obter informações sobre o local do arquivo de log do aplicativo, consulte Demonstra Passo a passo: Determinar onde My.Application.Log grava informações (Visual Basic).

Observação
Por padrão, o aplicativo libera a saída do arquivo de log quando o aplicativo for fechado.

No exemplo acima, a segunda chamada para o WriteEntry método e a chamada para o WriteException método produz a saída de log, enquanto as chamadas de primeira e últimos para o WriteEntry método fazer não. Isso ocorre porque os níveis de gravidade de WriteEntry e WriteException são "Information" e "Error", ambos que são permitidas pela filtragem padrão de log do objeto My.Application.Log. No entanto, os eventos com níveis de gravidade "Start" e "Stop" são impedidos de produzir saída de log.

Filtro para todos os My.Application.Log Listeners

O objeto My.Application.Log usa um SourceSwitch chamado DefaultSwitch para controlar quais mensagens ele passa dos métodos WriteEntry WriteException e para os ouvintes do log. Você pode configurar DefaultSwitch no arquivo de configuração do aplicativo, definindo seu valor como um dos valores da enumeração SourceLevels. Por padrão, seu valor é "Information".

Esta tabela mostra o nível de gravidade necessário para o Log gravar uma mensagem para os ouvintes, fornecida uma determinada configuração DefaultSwitch.

Valor DefaultSwitch	Gravidade da mensagem necessária para saída
Critical	Critical
Error	CriticalouError
Warning	Critical, Error, ou Warning
Information	Critical, Error, Warning, ou Information
Verbose	Critical, Error, Warning, Information, ou Verbose
ActivityTracing	Start, Stop, Suspend, Resume, ou Transfer
All	Todas as mensagens são permitidas.
Off	Todas as mensagens são bloqueadas.

Observação
Os métodos WriteEntry e WriteException têm uma sobrecarga que não especifica um nível de gravidade. O nível implícito de gravidade para a sobrecarga WriteEntry é "Information", e o nível de gravidade implícito para a sobrecarga WriteException é "Error".

Esta tabela explica a saída de log, mostrada no exemplo anterior: com o padrão DefaultSwitch a definição de "Informações", apenas a segunda é chamada da WriteEntry método e a chamada para o WriteException método produzir saída de log.

Para registrar somente eventos de rastreamento de atividades

Clique com o botão direito do mouse em app.config no Solution Explorer e selecione Open.

- ou -

Se não houver nenhum arquivo app.config:
1. No menu Project, escolha Add New Item.
2. No caixa de diálogo Add New Item escolha Application Configuration File.
3. Clique em Adicionar.
Localize a seção <switches>, que está na seção <system.diagnostics>, que está na seção de nível superior <configuration>.
Localize o elemento que adiciona DefaultSwitch à coleção de opções. Ele deve ser semelhante a este elemento:

<add name="DefaultSwitch" value="Information" />
Altere o valor do atributo value para "ActivityTracing".

O conteúdo do arquivo app.config deve ser semelhante ao XML a seguir:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <system.diagnostics>
    <sources>
      <!-- This section configures My.Application.Log -->
      <source name="DefaultSource" switchName="DefaultSwitch">
        <listeners>
          <add name="FileLog"/>
        </listeners>
      </source>
    </sources>
    <switches>
      <add name="DefaultSwitch" value="ActivityTracing" />
    </switches>
    <sharedListeners>
      <add name="FileLog"
           type="Microsoft.VisualBasic.Logging.FileLogTraceListener, 
                 Microsoft.VisualBasic, Version=8.0.0.0, 
                 Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a, 
                 processorArchitecture=MSIL" 
           initializeData="FileLogWriter"/>
    </sharedListeners>
  </system.diagnostics>
</configuration>

Execute o aplicativo no depurador.
Pressione Button1.

O aplicativo grava as informações a seguir nos arquivos de saída de depuração e de log do aplicativo.

DefaultSource Start: 4 : Entering Button1_Click

DefaultSource Stop: 5 : Leaving Button1_Click
Feche o aplicativo.
Altere o valor do atributo value de volta para "Information".

Observação
O DefaultSwitch alterna apenas controles de configuração My.Application.Log. Ela não altera como o .NET Framework System.Diagnostics.Trace e System.Diagnostics.Debug se comportam.

Filtragem individual para My.Application.Log Listeners

O anterior exemplo mostra como alterar a filtragem de todas as saídas do My.Application.Log. Este exemplo demonstra como filtrar um ouvinte de log individual. Por padrão, um aplicativo tem dois ouvintes que gravam para saída de depuração e o arquivo de log do aplicativo.

O arquivo de configuração controla o comportamento do ouvinte de log, permitindo que cada um tenha um filtro, que é semelhante a uma opção para My.Application.Log. Um ouvinte de log irá gerar uma saída de uma mensagem somente se a gravidade da mensagem for permitida por ambos o DefaultSwitch do log e do filtro do ouvinte de log.

Este exemplo demonstra como configurar a filtragem para um novo ouvinte de depuração e adicioná-lo ao objeto Log. O ouvinte de depuração padrão deve ser removido do objeto Log, para que seja que as mensagens de depuração são provenientes do novo ouvinte de depuração.

Para registrar somente eventos de rastreamento de atividades

Clique com o botão direito do mouse em app.config no Solution Explorer e escolha Open.

- ou -

Se não houver nenhum arquivo app.config:
1. No menu Project, escolha Add New Item.
2. No caixa de diálogo Add New Item escolha Application Configuration File.
3. Clique em Adicionar.
Clique com o botão direito do mouse em app.config no Solution Explorer. Escolha Open.
Localize a seção <listeners>, na seção <source> com o atributo name "DefaultSource", que está sob a seção <sources>. A seção <sources> está sob a seção <system.diagnostics>, na seção de nível superior <configuration>.

Adicione esse elemento à seção <listeners>.

<!-- Remove the default debug listener. -->
<remove name="Default"/>
<!-- Add a filterable debug listener. -->
<add name="NewDefault"/>

Localize a seção <sharedListeners>, na seção <system.diagnostics>, na seção de nível superior <configuration>.

Adicione esse elemento à seção <sharedListeners>.

<add name="NewDefault" 
     type="System.Diagnostics.DefaultTraceListener, 
           System, Version=2.0.0.0, Culture=neutral, 
           PublicKeyToken=b77a5c561934e089, 
           processorArchitecture=MSIL">
    <filter type="System.Diagnostics.EventTypeFilter" 
            initializeData="Error" />
</add>

O filtro EventTypeFilter utiliza um dos valores de enumeração SourceLevels como seu atributo initializeData.

O conteúdo do arquivo app.config deve ser semelhante ao XML a seguir:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <system.diagnostics>
    <sources>
      <!-- This section configures My.Application.Log -->
      <source name="DefaultSource" switchName="DefaultSwitch">
        <listeners>
          <add name="FileLog"/>
          <!-- Remove the default debug listener. -->
          <remove name="Default"/>
          <!-- Add a filterable debug listener. -->
          <add name="NewDefault"/>
        </listeners>
      </source>
    </sources>
    <switches>
      <add name="DefaultSwitch" value="Information" />
    </switches>
    <sharedListeners>
      <add name="FileLog"
           type="Microsoft.VisualBasic.Logging.FileLogTraceListener, 
                 Microsoft.VisualBasic, Version=8.0.0.0, 
                 Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a, 
                 processorArchitecture=MSIL" 
           initializeData="FileLogWriter"/>
      <add name="NewDefault" 
           type="System.Diagnostics.DefaultTraceListener, 
                 System, Version=2.0.0.0, Culture=neutral, 
                 PublicKeyToken=b77a5c561934e089, 
                 processorArchitecture=MSIL">
        <filter type="System.Diagnostics.EventTypeFilter" 
                initializeData="Error" />
      </add>
    </sharedListeners>
  </system.diagnostics>
</configuration>

Execute o aplicativo no depurador.
Pressione Button1.

O aplicativo grava as informações a seguir no arquivo de log do aplicativo.

Default Information: 0 : In Button1_Click

Default Error: 2 : Error in the application.

O aplicativo grava menos informações na saída de depuração do aplicativo devido à filtragem mais restritiva.

Default Error 2 Error
Feche o aplicativo.

Para obter mais informações sobre como alterar as configurações de log após a implantação, consulte Trabalhando com logs de aplicativos em Visual Basic.