Como: Criar e inicializar fontes de rastreamento

Artigo
06/04/2024

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.

A TraceSource classe é usada por aplicativos para produzir rastreamentos que podem ser associados ao aplicativo. TraceSource Fornece métodos de rastreamento que permitem rastrear facilmente eventos, rastrear dados e emitir rastreamentos informativos. A saída de rastreamento pode TraceSource ser criada e inicializada com ou sem o uso de arquivos de configuração. Este tópico fornece instruções para ambas as opções. No entanto, recomendamos que você use arquivos de configuração para facilitar a reconfiguração dos rastreamentos produzidos por fontes de rastreamento em tempo de execução.

Para criar e inicializar uma fonte de rastreamento usando um arquivo de configuração

Crie um projeto de aplicativo de console do Visual Studio (.NET Framework) e substitua o código fornecido pelo código a seguir. Esse código registra erros e avisos e envia alguns deles para o console e alguns deles para o arquivo myListener que é criado pelas entradas no arquivo de configuração.

using System;
using System.Diagnostics;

class TraceTest
{

    private static TraceSource mySource =
            new TraceSource("TraceSourceApp");
        static void Main(string[] args)
        {
           // Issue an error and a warning message. Only the error message
            // should be logged.
            Activity1();

            // Save the original settings from the configuration file.
            EventTypeFilter configFilter =
                (EventTypeFilter)mySource.Listeners["console"].Filter;

            // Create a new event type filter that ensures
            // warning messages will be written.
            mySource.Listeners["console"].Filter =
                new EventTypeFilter(SourceLevels.Warning);

            // Allow the trace source to send messages to listeners
            // for all event types. This statement will override
            // any settings in the configuration file.
            // If you do not change the switch level, the event filter
            // changes have no effect.
            mySource.Switch.Level = SourceLevels.All;

            // Issue a warning and a critical message. Both should be logged.
            Activity2();

            // Restore the original filter settings.
            mySource.Listeners["console"].Filter = configFilter;
            Activity3();
            mySource.Close();
            return;
        }
        static void Activity1()
        {
            mySource.TraceEvent(TraceEventType.Error, 1,
                "Error message.");
            mySource.TraceEvent(TraceEventType.Warning, 2,
                "Warning message.");
        }
        static void Activity2()
        {
            mySource.TraceEvent(TraceEventType.Critical, 3,
                "Critical message.");
            mySource.TraceEvent(TraceEventType.Warning, 2,
                "Warning message.");
        }
        static void Activity3()
        {
            mySource.TraceEvent(TraceEventType.Error, 4,
                "Error message.");
            mySource.TraceInformation("Informational message.");
        }
    }

Imports System.Diagnostics

Class TraceTest

    Private Shared mySource As New TraceSource("TraceSourceApp")

    Shared Sub Main(ByVal args() As String)
        ' Issue an error and a warning message. Only the error message
        ' should be logged.
        Activity1()

        ' Save the original settings from the configuration file.
        Dim configFilter As EventTypeFilter = CType(mySource.Listeners("console").Filter, EventTypeFilter)

        ' Create a new event type filter that ensures 
        ' warning messages will be written.
        mySource.Listeners("console").Filter = New EventTypeFilter(SourceLevels.Warning)

        ' Allow the trace source to send messages to listeners 
        ' for all event types. This statement will override 
        ' any settings in the configuration file.
        ' If you do not change the switch level, the event filter
        ' changes have no effect.
        mySource.Switch.Level = SourceLevels.All

        ' Issue a warning and a critical message. Both should be logged.
        Activity2()

        ' Restore the original filter settings.
        mySource.Listeners("console").Filter = configFilter
        Activity3()
        mySource.Close()
        Return

    End Sub

    Shared Sub Activity1()
        mySource.TraceEvent(TraceEventType.Error, 1, "Error message.")
        mySource.TraceEvent(TraceEventType.Warning, 2, "Warning message.")

    End Sub

    Shared Sub Activity2()
        mySource.TraceEvent(TraceEventType.Critical, 3, "Critical message.")
        mySource.TraceEvent(TraceEventType.Warning, 2, "Warning message.")

    End Sub

    Shared Sub Activity3()
        mySource.TraceEvent(TraceEventType.Error, 4, "Error message.")
        mySource.TraceInformation("Informational message.")

    End Sub
End Class

Adicione um arquivo de configuração do aplicativo, se um não estiver presente, ao projeto para inicializar a fonte de rastreamento nomeada TraceSourceApp no exemplo de código na etapa 1.
Substitua o conteúdo do arquivo de configuração padrão pelas seguintes configurações para inicializar um ouvinte de rastreamento de console e um ouvinte de rastreamento de gravador de texto para a fonte de rastreamento criada na etapa 1.
```
<configuration>
  <system.diagnostics>
    <sources>
      <source name="TraceSourceApp"
        switchName="sourceSwitch"
        switchType="System.Diagnostics.SourceSwitch">
        <listeners>
          <add name="console"
            type="System.Diagnostics.ConsoleTraceListener">
            <filter type="System.Diagnostics.EventTypeFilter"
              initializeData="Error"/>
          </add>
          <add name="myListener"/>
          <remove name="Default"/>
        </listeners>
      </source>
    </sources>
    <switches>
      <add name="sourceSwitch" value="Error"/>
    </switches>
    <sharedListeners>
      <add name="myListener"
        type="System.Diagnostics.TextWriterTraceListener"
        initializeData="myListener.log">
        <filter type="System.Diagnostics.EventTypeFilter"
          initializeData="Error"/>
      </add>
    </sharedListeners>
  </system.diagnostics>
</configuration>
```
Além de configurar os ouvintes de rastreamento, o arquivo de configuração cria filtros para ambos os ouvintes e cria uma opção de origem para a fonte de rastreamento. Duas técnicas são mostradas para adicionar ouvintes de rastreamento: adicionar o ouvinte diretamente à fonte de rastreamento e adicionar um ouvinte à coleção de ouvintes compartilhados e, em seguida, adicioná-lo pelo nome à fonte de rastreamento. Os filtros identificados para os dois ouvintes são inicializados com diferentes níveis de origem. Isso faz com que algumas mensagens sejam escritas por apenas um dos dois ouvintes.

O arquivo de configuração inicializa as configurações para a fonte de rastreamento no momento em que o aplicativo é inicializado. O aplicativo pode alterar dinamicamente as propriedades definidas pelo arquivo de configuração para substituir quaisquer configurações especificadas pelo usuário. Por exemplo, talvez você queira garantir que as mensagens críticas sejam sempre enviadas para um arquivo de texto, independentemente das definições de configuração atuais. O código de exemplo demonstra como substituir as definições do arquivo de configuração para garantir que as mensagens críticas sejam enviadas para os ouvintes de rastreamento.

Alterar as definições do arquivo de configuração enquanto o aplicativo está em execução não altera as configurações iniciais. Para alterar as configurações, você deve reiniciar o aplicativo ou atualizar programaticamente o aplicativo usando o Trace.Refresh método.

Para inicializar fontes de rastreamento, ouvintes e filtros sem um arquivo de configuração

Use o código de exemplo a seguir para habilitar o rastreamento por meio de uma fonte de rastreamento sem usar um arquivo de configuração. Essa não é uma prática recomendada, mas pode haver circunstâncias em que você não queira depender de arquivos de configuração para garantir o rastreamento.

using System;
using System.Diagnostics;
using System.Threading;

namespace TraceSourceApp
{
    class Program
    {
        private static TraceSource mySource =
            new TraceSource("TraceSourceApp");
        static void Main(string[] args)
        {
            mySource.Switch = new SourceSwitch("sourceSwitch", "Error");
            mySource.Listeners.Remove("Default");
            TextWriterTraceListener textListener =
                new TextWriterTraceListener("myListener.log");
            ConsoleTraceListener console =
                new ConsoleTraceListener(false);
            console.Filter =
                new EventTypeFilter(SourceLevels.Information);
            console.Name = "console";
            textListener.Filter =
                new EventTypeFilter(SourceLevels.Error);
            mySource.Listeners.Add(console);
            mySource.Listeners.Add(textListener);
            Activity1();

            // Allow the trace source to send messages to
            // listeners for all event types. Currently only
            // error messages or higher go to the listeners.
            // Messages must get past the source switch to
            // get to the listeners, regardless of the settings
            // for the listeners.
            mySource.Switch.Level = SourceLevels.All;

            // Set the filter settings for the
            // console trace listener.
            mySource.Listeners["console"].Filter =
                new EventTypeFilter(SourceLevels.Critical);
            Activity2();

            // Change the filter settings for the console trace listener.
            mySource.Listeners["console"].Filter =
                new EventTypeFilter(SourceLevels.Information);
            Activity3();
            mySource.Close();
            return;
        }
        static void Activity1()
        {
            mySource.TraceEvent(TraceEventType.Error, 1,
                "Error message.");
            mySource.TraceEvent(TraceEventType.Warning, 2,
                "Warning message.");
        }
        static void Activity2()
        {
            mySource.TraceEvent(TraceEventType.Critical, 3,
                "Critical message.");
            mySource.TraceInformation("Informational message.");
        }
        static void Activity3()
        {
            mySource.TraceEvent(TraceEventType.Error, 4,
                "Error message.");
            mySource.TraceInformation("Informational message.");
        }
    }
}

Imports System.Diagnostics
Imports System.Threading



Class Program
    Private Shared mySource As New TraceSource("TraceSourceApp")

    Shared Sub Main(ByVal args() As String)
        mySource.Switch = New SourceSwitch("sourceSwitch", "Error")
        mySource.Listeners.Remove("Default")
        Dim textListener As New TextWriterTraceListener("myListener.log")
        Dim console As New ConsoleTraceListener(False)
        console.Filter = New EventTypeFilter(SourceLevels.Information)
        console.Name = "console"
        textListener.Filter = New EventTypeFilter(SourceLevels.Error)
        mySource.Listeners.Add(console)
        mySource.Listeners.Add(textListener)
        Activity1()

        ' Allow the trace source to send messages to 
        ' listeners for all event types. Currently only 
        ' error messages or higher go to the listeners.
        ' Messages must get past the source switch to 
        ' get to the listeners, regardless of the settings 
        ' for the listeners.
        mySource.Switch.Level = SourceLevels.All

        ' Set the filter settings for the 
        ' console trace listener.
        mySource.Listeners("console").Filter = New EventTypeFilter(SourceLevels.Critical)
        Activity2()

        ' Change the filter settings for the console trace listener.
        mySource.Listeners("console").Filter = New EventTypeFilter(SourceLevels.Information)
        Activity3()
        mySource.Close()
        Return

    End Sub

    Shared Sub Activity1()
        mySource.TraceEvent(TraceEventType.Error, 1, "Error message.")
        mySource.TraceEvent(TraceEventType.Warning, 2, "Warning message.")

    End Sub

    Shared Sub Activity2()
        mySource.TraceEvent(TraceEventType.Critical, 3, "Critical message.")
        mySource.TraceInformation("Informational message.")

    End Sub

    Shared Sub Activity3()
        mySource.TraceEvent(TraceEventType.Error, 4, "Error message.")
        mySource.TraceInformation("Informational message.")

    End Sub
End Class

Consulte também

TraceSource
TextWriterTraceListener
ConsoleTraceListener
EventTypeFilter
Tracing and Instrumenting Applications (Rastrear e Instrumentalizar Aplicações)

Partilhar via

Como: Criar e inicializar fontes de rastreamento

Para criar e inicializar uma fonte de rastreamento usando um arquivo de configuração

Para inicializar fontes de rastreamento, ouvintes e filtros sem um arquivo de configuração

Consulte também

Recursos adicionais