Opções de rastreamentoTrace Switches

As opções de rastreamento permitem habilitar, desabilitar e filtrar a saída de rastreamento.Trace switches enable you to enable, disable, and filter tracing output. Elas são objetos que existem no código e podem ser configuradas externamente por meio do arquivo .config.They are objects that exist in your code and can be configured externally through the .config file. Há três tipos de opções de rastreamento fornecidas no .NET Framework: a classe BooleanSwitch, a classe TraceSwitch e a classe SourceSwitch.There are three types of trace switches provided in the .NET Framework: the BooleanSwitch class, the TraceSwitch class, and the SourceSwitch class. A classe BooleanSwitch atua como uma opção de alternância, habilitando ou desabilitando uma variedade de instruções de rastreamento.The BooleanSwitch class acts as a toggle switch, either enabling or disabling a variety of trace statements. 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.The TraceSwitch and SourceSwitch classes allow you to enable a trace switch for a particular tracing level so that the Trace or TraceSource messages specified for that level and all levels below it appear. Se você desabilitar a opção, as mensagens de rastreamento não serão exibidas.If you disable the switch, the trace messages will not appear. Todas essas classes são derivadas da classe Switch abstrata (MustInherit), assim como todas as opções desenvolvidas pelo usuário.All these classes derive from the abstract (MustInherit) class Switch, as should any user-developed switches.

As opções de rastreamento podem ser úteis para a filtragem de informações.Trace switches can be useful for filtering information. 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.For example, you might want to see every tracing message in a data access module, but only error messages in the rest of the application. 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.In that case, you would use one trace switch for the data access module and one switch for the rest of the application. 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.By using the .config file to configure the switches to the appropriate settings, you could control what types of trace message you received. Para obter mais informações, confira Como: Criar, inicializar e configurar opçõesde rastreamento.For more information, see How to: Create, Initialize and Configure Trace Switches.

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.Typically, a deployed application is executed with its switches disabled, so that users need not observe a lot of irrelevant trace messages appearing on a screen or filling up a log file as the application runs. Se surgir um problema durante a execução do aplicativo, pare o aplicativo, habilite as opções e reinicie o aplicativo.If a problem arises during application execution, you can stop the application, enable the switches, and restart the application. Em seguida, as mensagens de rastreamento serão exibidas.Then the tracing messages will be displayed.

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.To use a switch you must first create a switch object from a BooleanSwitch class, a TraceSwitch class, or a developer-defined switch class. Para obter mais informações sobre como criar opções definidas pelo desenvolvedor, consulte a classe Switch na referência do .NET Framework.For more information about creating developer-defined switches, see the Switch class in the .NET Framework reference. Em seguida, defina um valor de configuração que especifica quando o objeto de opção deve ser usado.Then you set a configuration value that specifies when the switch object is to be used. Depois, teste a configuração do objeto de opção em vários métodos de rastreamento Trace (ou Debug).You then test the setting of the switch object in various Trace (or Debug) tracing methods.

Níveis de rastreamentoTrace Levels

Ao usar TraceSwitch, há considerações adicionais.When you use TraceSwitch, there are additional considerations. Um objeto TraceSwitch tem quatro propriedades que retornam valores boolianos, indicando se a opção é definida com, pelo menos, um nível específico:A TraceSwitch object has four properties that return Boolean values indicating whether the switch is set to at least a particular level:

Os níveis permitem limitar a quantidade de informações de rastreamento recebidas apenas às informações necessárias para solucionar um problema.Levels allow you to limit the amount of tracing information you receive to only that information needed to solve a problem. 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.You specify the level of detail you want in your tracing output by setting and configuring trace switches to the appropriate trace level. Você pode receber mensagens de erro, mensagens de aviso, mensagens informativas, mensagens de rastreamento detalhado ou nenhuma mensagem.You can receive error messages, warning messages, informational messages, verbose tracing messages, or no message at all.

Cabe inteiramente a você decidir que tipo de mensagem deve ser associada a cada nível.It is entirely up to you to decide what kind of message to associate with each level. 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.Typically, the content of tracing messages depends on what you associate with each level, but you determine the differences between levels. 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).You might want to provide detailed descriptions of a problem at level 3 (Info), for example, but provide only an error reference number at level 1 (Error). Cabe inteiramente a você decidir qual esquema funciona melhor em seu aplicativo.It is entirely up to you to decide what scheme works best in your application.

Essas propriedades correspondem aos valores 1 a 4 da enumeração TraceLevel.These properties correspond to the values 1 through 4 of the TraceLevel enumeration. A tabela a seguir lista os níveis da enumeração TraceLevel e seus valores.The following table lists the levels of the TraceLevel enumeration and their values.

Valor enumeradoEnumerated value Valor inteiroInteger value Tipo de mensagem exibido (ou gravado em um destino de saída especificado)Type of message displayed (or written to a specified output target)
OffOff 00 NenhumNone
ErroError 11 Somente mensagens de erroOnly error messages
AvisoWarning 22 Mensagens de aviso e mensagens de erroWarning messages and error messages
InfoInfo 33 Mensagens informativas, mensagens de aviso e mensagens de erroInformational messages, warning messages, and error messages
DetalhadoVerbose 44 Mensagens detalhadas, mensagens informativas, mensagens de aviso e mensagens de erroVerbose messages, informational messages, warning messages, and error messages

As propriedades TraceSwitch indicam o nível máximo de rastreamento da opção.The TraceSwitch properties indicate the maximum trace level for the switch. Ou seja, as informações de rastreamento são gravadas para o nível especificado, bem como para todos os níveis inferiores.That is, tracing information is written for the level specified as well as for all lower levels. Por exemplo, se TraceInfo for true, TraceError e TraceWarning também serão true, mas TraceVerbose poderá ser false.For example, if TraceInfo is true, then TraceError and TraceWarning are also true but TraceVerbose might well be false.

Essas propriedades são somente leitura.These properties are read-only. O objeto TraceSwitch define-as automaticamente quando a propriedade TraceLevel é definida.The TraceSwitch object automatically sets them when the TraceLevel property is set. Por exemplo:For example:

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 desenvolvedorDeveloper-Defined Switches

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.In addition to providing BooleanSwitch and TraceSwitch, you can define your own switches by inheriting from the Switch class and overriding the base class methods with customized methods. Para obter mais informações sobre como criar opções definidas pelo desenvolvedor, consulte a classe Switch na referência do .NET Framework.For more information about creating developer-defined switches, see the Switch class in the .NET Framework reference.

Consulte tambémSee also