Ouvintes de rastreamento

  • Artigo

Observação

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

Ao usar Trace, Debug e TraceSource, você deve ter um mecanismo para coletar e registrar as mensagens que são enviadas. As mensagens de rastreamento são recebidas por ouvintes. A finalidade de um ouvinte é coletar, armazenar e rotear mensagens de rastreamento. Os ouvintes direcionam a saída de rastreamento para um destino apropriado, como um log, uma janela ou um arquivo de texto.

Os ouvintes estão disponíveis para as classes Debug, Trace e TraceSource, cada uma das quais pode enviar sua saída para a uma variedade de objetos de ouvinte. Veja a seguir os ouvintes predefinidos mais usados:

  • Um TextWriterTraceListener redireciona a saída para uma instância da classe TextWriter ou para qualquer coisa que seja uma classe Stream. Ele também pode gravar no console ou em um arquivo, pois eles são classes Stream.

  • Um EventLogTraceListener redireciona a saída para um log de eventos.

  • Um DefaultTraceListener emite mensagens Write e WriteLine para os métodos OutputDebugString e Debugger.Log. No Visual Studio, isso faz com que as mensagens de depuração sejam exibidas na janela de Saída. Mensagens Fail e Assert com falha também são emitidas para a API do Windows OutputDebugString e o método Debugger.Log, e também fazem com que uma caixa de mensagem seja exibida. Esse comportamento é o comportamento padrão de mensagens Debug e Trace, pois DefaultTraceListener é incluído automaticamente em cada coleção Listeners e é o único ouvinte incluído automaticamente.

  • Um ConsoleTraceListener direciona a saída do rastreamento ou da depuração para a saída padrão ou para o fluxo de erro padrão.

  • Um DelimitedListTraceListener direciona a saída de rastreamento ou de depuração para um text writer, como um gravador de fluxo ou para um fluxo, como um fluxo de arquivos. A saída de rastreamento está em um formato de texto delimitado que usa o delimitador especificado pela propriedade Delimiter.

  • Um XmlWriterTraceListener direciona a saída de rastreamento ou de depuração como dados codificados em XML para um TextWriter ou Stream, como um FileStream.

Se você deseja que qualquer ouvinte além do DefaultTraceListener receba a saída Debug, Trace e TraceSource, adicione-o à coleção Listeners. Para obter mais informações, consulte Como criar e inicializar ouvintes de rastreamento e Como usar TraceSource e filtros com ouvintes de rastreamento. Qualquer ouvinte da coleção Listeners obtém as mesmas mensagens dos métodos de saída de rastreamento. Por exemplo, suponha que você configure dois ouvintes: um TextWriterTraceListener e um EventLogTraceListener. Cada ouvinte recebe a mesma mensagem. O TextWriterTraceListener direcionará sua saída para um fluxo e o EventLogTraceListener direcionará sua saída para um log de eventos.

O exemplo a seguir mostra como enviar a saída para a coleção Listeners.

' Use this example when debugging.
Debug.WriteLine("Error in Widget 42")
' Use this example when tracing.
Trace.WriteLine("Error in Widget 42")

// Use this example when debugging.
System.Diagnostics.Debug.WriteLine("Error in Widget 42");
// Use this example when tracing.
System.Diagnostics.Trace.WriteLine("Error in Widget 42");

A depuração e o rastreamento compartilham a mesma coleção Listeners. Portanto, se você adicionar um objeto de ouvinte a uma coleção Debug.Listeners no aplicativo, ele será adicionado à coleção Trace.Listeners também.

O exemplo a seguir mostra como usar um ouvinte para enviar informações de rastreamento para um console:

Trace.Listeners.Clear()
Trace.Listeners.Add(New TextWriterTraceListener(Console.Out))

System.Diagnostics.Trace.Listeners.Clear();
System.Diagnostics.Trace.Listeners.Add(
   new System.Diagnostics.TextWriterTraceListener(Console.Out));

Ouvintes definidos pelo desenvolvedor

Você pode definir seus próprios ouvintes herdando a classe base TraceListener e substituindo seus métodos por métodos personalizados. Para obter mais informações sobre como criar ouvintes definidos pelo desenvolvedor, consulte TraceListener na referência do .NET Framework.

Confira também