Partilhar via

Como: Criar, inicializar e configurar opções de rastreamento

  • Artigo

Nota

Este artigo é específico do .NET Framework. Ele não se aplica a implementações mais recentes do .NET, incluindo o .NET 6 e versões posteriores.

As opções de rastreamento permitem habilitar, desabilitar e filtrar a saída de rastreamento.

Criando e inicializando uma opção de rastreamento

Para usar opções de rastreamento, você deve primeiro criá-las e colocá-las em seu código. Há duas classes predefinidas a partir das quais você pode criar objetos switch: a System.Diagnostics.BooleanSwitch classe e a System.Diagnostics.TraceSwitch classe. Você usaria BooleanSwitch se você se preocupasse apenas se uma mensagem de rastreamento aparece ou não, você usaria TraceSwitch se quiser discriminar entre os níveis de rastreamento. Se você usar um TraceSwitch, poderá definir suas próprias mensagens de depuração e associá-las a diferentes níveis de rastreamento. Você pode usar ambos os tipos de opções com rastreamento ou depuração. Por padrão, a BooleanSwitch está desabilitado e a TraceSwitch está definido como nível TraceLevel.Off. As opções de rastreamento podem ser criadas e colocadas em qualquer parte do seu código que possa usá-las.

Embora você possa definir níveis de rastreamento e outras opções de configuração no código, recomendamos que você use o arquivo de configuração para gerenciar o estado de seus switches. Isso ocorre porque o gerenciamento da configuração de seus switches no sistema de configuração oferece maior flexibilidade — você pode ligar e desligar vários switches e alterar níveis sem recompilar seu aplicativo.

Para criar e inicializar uma opção de rastreamento

  1. Defina um comutador como tipo System.Diagnostics.BooleanSwitch ou tipo System.Diagnostics.TraceSwitch e defina o nome e a descrição do comutador.

  2. Configure sua opção de rastreamento. Para obter mais informações, consulte Configurando opções de rastreamento.

    O código a seguir cria duas opções, uma de cada tipo:

    Dim dataSwitch As New BooleanSwitch("Data", "DataAccess module")
Dim generalSwitch As New TraceSwitch("General", "Entire application")

    System.Diagnostics.BooleanSwitch dataSwitch =
   new System.Diagnostics.BooleanSwitch("Data", "DataAccess module");
System.Diagnostics.TraceSwitch generalSwitch =
   new System.Diagnostics.TraceSwitch("General",
   "Entire application");

Configurando opções de rastreamento

Depois que seu aplicativo tiver sido distribuído, você ainda poderá habilitar ou desabilitar a saída de rastreamento configurando as opções de rastreamento em seu aplicativo. Configurar um switch significa alterar seu valor de uma fonte externa depois que ele foi inicializado. Você pode alterar os valores dos objetos de switch usando o arquivo de configuração. Você configura uma opção de rastreamento para ativá-la e desativá-la ou para definir seu nível, determinando a quantidade e o tipo de mensagens que ela passa para os ouvintes.

Seus switches são configurados usando o arquivo .config. Para um aplicativo Web, este é o arquivo Web.config associado ao projeto. Em um aplicativo do Windows, esse arquivo é chamado (nome do aplicativo).exe.config. Em um aplicativo implantado, esse arquivo deve residir na mesma pasta que o executável.

Quando seu aplicativo executa o código que cria uma instância de um switch pela primeira vez, ele verifica o arquivo de configuração para obter informações de nível de rastreamento sobre o switch nomeado. O sistema de rastreamento examina o arquivo de configuração apenas uma vez para qualquer switch específico — a primeira vez que seu aplicativo cria o switch.

Em um aplicativo implantado, você habilita o código de rastreamento reconfigurando objetos de switch quando seu aplicativo não está em execução. Normalmente, isso envolve ligar e desligar os objetos do interruptor ou alterar os níveis de rastreamento e, em seguida, reiniciar o aplicativo.

Ao criar uma instância de um switch, você também a inicializa especificando dois argumentos: um argumento displayName e um argumento description . O argumento displayName do construtor define a Switch.DisplayName propriedade da instância da Switch classe. O displayName é o nome usado para configurar o switch no arquivo .config, e o argumento description deve retornar uma breve descrição do switch e quais mensagens ele controla.

Além de especificar o nome de um switch a ser configurado, você também deve especificar um valor para o switch. Esse valor é um Inteiro. Para BooleanSwitch, um valor de 0 corresponde a Off, e qualquer valor diferente de zero corresponde a On. Para TraceSwitch, 0,1,2,3 e 4 correspondem a Off, Error, Warning, Info, e Verbose, respectivamente. Qualquer número maior que 4 é tratado como Detalhado, e qualquer número menor que zero é tratado como Desativado.

Nota

No .NET Framework versão 2.0, você pode usar texto para especificar o valor de uma opção. Por exemplo, para um BooleanSwitch ou o texto que representa um valor de enumeração, true como Error para um TraceSwitch. A linha <add name="myTraceSwitch" value="Error" /> é equivalente a <add name="myTraceSwitch" value="1" />.

Para que os usuários finais possam configurar os switches de rastreamento de um aplicativo, você deve fornecer documentação detalhada sobre os switches em seu aplicativo. Você deve detalhar quais switches controlam o que e como ligá-los e desligá-los. Você também deve fornecer ao usuário final um arquivo .config que tenha a Ajuda apropriada nos comentários.

Para configurar opções de rastreamento

  1. Para usar opções de rastreamento, você deve primeiro criá-las e colocá-las em seu código, conforme descrito na seção Criando e inicializando uma opção de rastreamento.

  2. Se o seu projeto não contiver um arquivo de configuração (app.config ou Web.config), no menu Projeto , selecione Adicionar Novo Item.

    • Visual Basic: Na caixa de diálogo Adicionar Novo Item , escolha Arquivo de Configuração do Aplicativo.

      O arquivo de configuração do aplicativo é criado e aberto. Este é um documento XML cujo elemento raiz é <configuration>.

    • Visual C#: Na caixa de diálogo Adicionar Novo Item , escolha Arquivo XML. Nomeie esse arquivo como app.config. No editor XML, após a declaração XML, adicione o seguinte XML:

      <configuration>
</configuration>

      Quando o projeto é compilado, o arquivo app.config é copiado para a pasta de saída do projeto e é renomeado applicationname.exe.config.

  3. Depois da <configuration> tag , mas antes da </configuration> tag , adicione o XML apropriado para configurar seus switches. Os exemplos a seguir demonstram um BooleanSwitch com uma propriedade DisplayName de DataMessageSwitch e um TraceSwitch com uma propriedade DisplayName de TraceLevelSwitch.

    <system.diagnostics>
   <switches>
      <add name="DataMessagesSwitch" value="0" />
      <add name="TraceLevelSwitch" value="0" />
   </switches>
</system.diagnostics>

    Nesta configuração, ambos os interruptores estão desligados.

  4. Se você precisar ativar um BooleanSwitch, como DataMessagesSwitch mostrado no exemplo anterior, altere o Value para qualquer inteiro diferente de 0.

  5. Se você precisar ativar um TraceSwitch, como TraceLevelSwitch mostrado no exemplo anterior, altere o Valor para a configuração de nível apropriada (1 a 4).

  6. Adicione comentários ao arquivo .config para que o usuário final tenha uma compreensão clara de quais valores alterar para configurar os switches adequadamente.

    O exemplo a seguir mostra como o código final, incluindo comentários, pode parecer:

    <system.diagnostics>
   <switches>
      <!-- This switch controls data messages. In order to receive data
         trace messages, change value="0" to value="1" -->
      <add name="DataMessagesSwitch" value="0" />
      <!-- This switch controls general messages. In order to
         receive general trace messages change the value to the
         appropriate level. "1" gives error messages, "2" gives errors
         and warnings, "3" gives more detailed error information, and
         "4" gives verbose trace information -->
      <add name="TraceLevelSwitch" value="0" />
   </switches>
</system.diagnostics>

Consulte também