Opções de rastreamento

As opções de rastreamento permitem habilitar, desabilitar e filtrar a saída de rastreamento. Elas são objetos que existem no código e podem ser configuradas externamente por meio do arquivo .config. Há três tipos de opções de rastreamento fornecidas no .NET Framework: a classe BooleanSwitch, a classe TraceSwitch e a classe SourceSwitch. A classe BooleanSwitch atua como uma opção de alternância, habilitando ou desabilitando uma variedade de instruções de rastreamento. As classes TraceSwitch e SourceSwitch permitem habilitar uma opção de rastreamento para um nível de rastreamento específico, de modo que as mensagens Trace ou TraceSource especificadas para o nível e todos os níveis inferiores a ele sejam exibidas. Se você desabilitar a opção, as mensagens de rastreamento não serão exibidas. Todas essas classes são derivadas da classe Switch abstrata (MustInherit), assim como todas as opções desenvolvidas pelo usuário.

As opções de rastreamento podem ser úteis para a filtragem de informações. Por exemplo, talvez você deseje ver todas as mensagens de rastreamento em um módulo de acesso a dados, mas somente as mensagens de erro no restante do aplicativo. Nesse caso, você usará uma opção de rastreamento para o módulo de acesso a dados e uma opção para o restante do aplicativo. Usando o arquivo .config para definir as opções com as configurações apropriadas, você pode controlar quais tipos de mensagem de rastreamento foram recebidas. Para obter mais informações, consulte Como criar, inicializar e configurar opções de rastreamento.

Normalmente, um aplicativo implantado é executado com suas opções desabilitadas, de modo que os usuários não precisem observar muitas mensagens de rastreamento irrelevantes exibidas em uma tela ou enchendo um arquivo de log conforme o aplicativo é executado. Se surgir um problema durante a execução do aplicativo, pare o aplicativo, habilite as opções e reinicie o aplicativo. Em seguida, as mensagens de rastreamento serão exibidas.

Para usar uma opção, primeiro você deve criar um objeto de opção com base em uma classe BooleanSwitch, uma classe TraceSwitch ou uma classe de opção definida pelo desenvolvedor. Para obter mais informações sobre como criar opções definidas pelo desenvolvedor, consulte a classe Switch na referência do .NET Framework. Em seguida, defina um valor de configuração que especifica quando o objeto de opção deve ser usado. Depois, teste a configuração do objeto de opção em vários métodos de rastreamento Trace (ou Debug).

Níveis de rastreamento

Ao usar TraceSwitch, há considerações adicionais. Um objeto TraceSwitch tem quatro propriedades que retornam valores boolianos, indicando se a opção é definida com, pelo menos, um nível específico:

• TraceSwitch.TraceError

• TraceSwitch.TraceWarning

• TraceSwitch.TraceInfo

• TraceSwitch.TraceVerbose

Os níveis permitem limitar a quantidade de informações de rastreamento recebidas apenas às informações necessárias para solucionar um problema. Especifique o nível de detalhe desejado na saída de rastreamento, definindo e configurando opções de rastreamento para o nível de rastreamento apropriado. Você pode receber mensagens de erro, mensagens de aviso, mensagens informativas, mensagens de rastreamento detalhado ou nenhuma mensagem.

Cabe inteiramente a você decidir que tipo de mensagem deve ser associada a cada nível. Normalmente, o conteúdo das mensagens de rastreamento depende do que você associa a cada nível, mas você determina as diferenças entre os níveis. Talvez você deseje fornecer descrições detalhadas de um problema no nível 3 (Informativo), por exemplo, mas fornecer somente um número de referência de erro no nível 1 (Erro). Cabe inteiramente a você decidir qual esquema funciona melhor em seu aplicativo.

Essas propriedades correspondem aos valores 1 a 4 da enumeração TraceLevel. A tabela a seguir lista os níveis da enumeração TraceLevel e seus valores.

As propriedades TraceSwitch indicam o nível máximo de rastreamento da opção. Ou seja, as informações de rastreamento são gravadas para o nível especificado, bem como para todos os níveis inferiores. Por exemplo, se TraceInfo for true, TraceError e TraceWarning também serão true, mas TraceVerbose poderá ser false.

Essas propriedades são somente leitura. O objeto TraceSwitch define-as automaticamente quando a propriedade TraceLevel é definida. Por exemplo:

Dim myTraceSwitch As New TraceSwitch("SwitchOne", "The first switch")
myTraceSwitch.Level = TraceLevel.Info
' This message box displays true, because setting the level to
' TraceLevel.Info sets all lower levels to true as well.
MessageBox.Show(myTraceSwitch.TraceWarning.ToString())
' This messagebox displays false.
MessageBox.Show(myTraceSwitch.TraceVerbose.ToString())

System.Diagnostics.TraceSwitch myTraceSwitch =
   new System.Diagnostics.TraceSwitch("SwitchOne", "The first switch");
myTraceSwitch.Level = System.Diagnostics.TraceLevel.Info;
// This message box displays true, because setting the level to
// TraceLevel.Info sets all lower levels to true as well.
MessageBox.Show(myTraceSwitch.TraceWarning.ToString());
// This message box displays false.
MessageBox.Show(myTraceSwitch.TraceVerbose.ToString());

Opções definidas pelo desenvolvedor

Além de fornecer BooleanSwitch e TraceSwitch, você pode definir suas próprias opções herdando da classe Switch e substituindo os métodos da classe base por métodos personalizados. Para obter mais informações sobre como criar opções definidas pelo desenvolvedor, consulte a classe Switch na referência do .NET Framework.

Confira também

• Ouvintes de rastreamento
• Como: adicionar instruções de rastreamento ao código de um aplicativo
• Como rastrear e instrumentar aplicativos