TraceSource Classe

Definição

Fornece um conjunto de métodos e propriedades que permitem que os aplicativos rastreiem a execução do código e associe mensagens de rastreamento à sua origem.

public class TraceSource
Herança
TraceSource

Exemplos

O exemplo de código a seguir mostra o uso da TraceSource classe para encaminhar rastreamentos aos ouvintes. O exemplo também demonstra o uso de comutador e filtro.

// The following configuration file can be used with this sample.
// When using a configuration file #define ConfigFile.
//            <source name="TraceTest" switchName="SourceSwitch" switchType="System.Diagnostics.SourceSwitch" >
//                    <add name="console" type="System.Diagnostics.ConsoleTraceListener" initializeData="false" />
//                    <remove name ="Default" />
//            <!-- You can set the level at which tracing is to occur -->
//            <add name="SourceSwitch" value="Warning" />
//            <!-- You can turn tracing off -->
//            <!--add name="SourceSwitch" value="Off" -->
//        <trace autoflush="true" indentsize="4"></trace>
#define TRACE
//#define ConfigFile

using System;
using System.Collections;
using System.Diagnostics;
using System.Reflection;
using System.IO;
using System.Security.Permissions;

namespace Testing
{
    class TraceTest
    {
        // Initialize the trace source.
        static TraceSource ts = new TraceSource("TraceTest");
        [SwitchAttribute("SourceSwitch", typeof(SourceSwitch))]
        static void Main()
        {
            try
            {
                // Initialize trace switches.
#if(!ConfigFile)
                SourceSwitch sourceSwitch = new SourceSwitch("SourceSwitch", "Verbose");
                ts.Switch = sourceSwitch;
                int idxConsole = ts.Listeners.Add(new System.Diagnostics.ConsoleTraceListener());
                ts.Listeners[idxConsole].Name = "console";
#endif
                DisplayProperties(ts);
                ts.Listeners["console"].TraceOutputOptions |= TraceOptions.Callstack;
                ts.TraceEvent(TraceEventType.Warning, 1);
                ts.Listeners["console"].TraceOutputOptions = TraceOptions.DateTime;
                // Issue file not found message as a warning.
                ts.TraceEvent(TraceEventType.Warning, 2, "File Test not found");
                // Issue file not found message as a verbose event using a formatted string.
                ts.TraceEvent(TraceEventType.Verbose, 3, "File {0} not found.", "test");
                // Issue file not found message as information.
                ts.TraceInformation("File {0} not found.", "test");
                ts.Listeners["console"].TraceOutputOptions |= TraceOptions.LogicalOperationStack;
                // Issue file not found message as an error event.
                ts.TraceEvent(TraceEventType.Error, 4, "File {0} not found.", "test");
                // Test the filter on the ConsoleTraceListener.
                ts.Listeners["console"].Filter = new SourceFilter("No match");
                ts.TraceData(TraceEventType.Error, 5,
                    "SourceFilter should reject this message for the console trace listener.");
                ts.Listeners["console"].Filter = new SourceFilter("TraceTest");
                ts.TraceData(TraceEventType.Error, 6,
                    "SourceFilter should let this message through on the console trace listener.");
                ts.Listeners["console"].Filter = null;
                // Use the TraceData method.
                ts.TraceData(TraceEventType.Warning, 7, new object());
                ts.TraceData(TraceEventType.Warning, 8, new object[] { "Message 1", "Message 2" });
                // Activity tests.
                ts.TraceEvent(TraceEventType.Start, 9, "Will not appear until the switch is changed.");
                ts.Switch.Level = SourceLevels.ActivityTracing | SourceLevels.Critical;
                ts.TraceEvent(TraceEventType.Suspend, 10, "Switch includes ActivityTracing, this should appear");
                ts.TraceEvent(TraceEventType.Critical, 11, "Switch includes Critical, this should appear");
                ts.Flush();
                ts.Close();
                Console.WriteLine("Press any key to exit.");
                Console.Read();
            }
            catch (Exception e)
            {
                // Catch any unexpected exception.
                Console.WriteLine("Unexpected exception: " + e.ToString());
                Console.Read();
            }
        }
        public static void DisplayProperties(TraceSource ts)
        {
            Console.WriteLine("TraceSource name = " + ts.Name);
            Console.WriteLine("TraceSource switch level = " + ts.Switch.Level);
            Console.WriteLine("TraceSource switch = " + ts.Switch.DisplayName);
            SwitchAttribute[] switches = SwitchAttribute.GetAll(typeof(TraceTest).Assembly);
            for (int i = 0; i < switches.Length; i++)
            {
                Console.WriteLine("Switch name = " + switches[i].SwitchName);
                Console.WriteLine("Switch type = " + switches[i].SwitchType);
            }
#if(ConfigFile)
            // Get the custom attributes for the TraceSource.
            Console.WriteLine("Number of custom trace source attributes = "
                + ts.Attributes.Count);
            foreach (DictionaryEntry de in ts.Attributes)
                Console.WriteLine("Custom trace source attribute = "
                    + de.Key + "  " + de.Value);
            // Get the custom attributes for the trace source switch.
            foreach (DictionaryEntry de in ts.Switch.Attributes)
                Console.WriteLine("Custom switch attribute = "
                    + de.Key + "  " + de.Value);
#endif
            Console.WriteLine("Number of listeners = " + ts.Listeners.Count);
            foreach (TraceListener traceListener in ts.Listeners)
            {
                Console.Write("TraceListener: " + traceListener.Name + "\t");
                // The following output can be used to update the configuration file.
                Console.WriteLine("AssemblyQualifiedName = " +
                    (traceListener.GetType().AssemblyQualifiedName));
            }
        }
    }
}

Comentários

A classe TraceSource é usada por aplicativos para produzir rastreamentos que podem ser associados ao aplicativo. TraceSource fornece métodos de rastreamento que permitem rastrear eventos com facilidade, rastrear dados e emitir rastreamentos informativos.

Em aplicativos .NET Framework, a saída de rastreamento de TraceSource pode ser controlada pelas configurações do arquivo. O arquivo de configuração está localizado na pasta com o executável do aplicativo e tem o nome do aplicativo com a extensão .config adicionada. Por exemplo, o nome do arquivo de configuração para TraceSourceSample.exe é TraceSourceSample.exe.config. O arquivo de configuração pode ser usado para especificar para onde as informações de rastreamento devem ser enviadas e quais níveis de atividade devem ser rastreados. O exemplo a seguir mostra o conteúdo de um exemplo .NET Framework arquivo de configuração de aplicativo.

<configuration>  
  <system.diagnostics>  
    <sources>  
      <source name="TraceTest" switchName="SourceSwitch"   
        switchType="System.Diagnostics.SourceSwitch" >  
        <listeners>  
          <add name="console" />  
          <remove name ="Default" />  
        </listeners>  
      </source>  
    </sources>  
    <switches>  
      <!-- You can set the level at which tracing is to occur -->  
      <add name="SourceSwitch" value="Warning" />  
        <!-- You can turn tracing off -->  
        <!--add name="SourceSwitch" value="Off" -->  
    </switches>  
    <sharedListeners>  
      <add name="console"   
        type="System.Diagnostics.ConsoleTraceListener"   
        initializeData="false"/>  
    </sharedListeners>  
    <trace autoflush="true" indentsize="4">  
      <listeners>  
        <add name="console" />  
      </listeners>  
    </trace>  
  </system.diagnostics>  
</configuration>  

A TraceSource classe é identificada pelo nome de uma origem, normalmente o nome do aplicativo. As mensagens de rastreamento provenientes de um componente específico podem ser iniciadas por uma fonte de rastreamento específica, permitindo que todas as mensagens provenientes desse componente sejam facilmente identificadas.

TraceSource define métodos de rastreamento, mas não fornece nenhum mecanismo específico para gerar e armazenar dados de rastreamento. Os dados de rastreamento são produzidos por ouvintes de rastreamento, que são plug-ins que podem ser carregados por fontes de rastreamento.

Observação

Você não deve chamar os métodos de rastreamento durante a finalização. Fazer isso pode resultar em um ObjectDisposedException ser lançado.

Você pode personalizar o destino da saída de rastreamento adicionando ou removendo TraceListener instâncias de ou para a coleção armazenada na TraceSource.Listeners propriedade . Por padrão, a saída de rastreamento é produzida usando uma instância da DefaultTraceListener classe .

O exemplo anterior .NET Framework arquivo de configuração de aplicativo demonstra a remoção do e a DefaultTraceListener adição de um ConsoleTraceListener para produzir a saída de rastreamento para a origem do rastreamento. Para obter mais informações, confira <ouvintes> e <sharedListeners>.

Observação

Adicionar um ouvinte de rastreamento à Listeners coleção pode fazer com que uma exceção seja gerada durante o rastreamento, se um recurso usado pelo ouvinte de rastreamento não estiver disponível. As condições e a exceção geradas dependem do ouvinte de rastreamento e não podem ser enumeradas neste tópico. Pode ser útil fazer chamadas aos TraceSource métodos em try/catch blocos para detectar e manipular quaisquer exceções de ouvintes de rastreamento.

A SourceSwitch classe fornece os meios para controlar dinamicamente a saída de rastreamento. Para aplicativos .NET Framework, o exemplo de arquivo de configuração anterior mostra como você pode desativar o rastreamento de uma fonte de rastreamento e controlar o nível no qual o rastreamento ocorre. Você pode modificar o valor da opção de origem sem recompilar seu aplicativo. Para obter informações sobre como usar o arquivo de configuração para definir uma opção, consulte Switch e Como: Create, Inicializar e configurar comutadores de rastreamento.

Observação

Se você modificar um arquivo de configuração enquanto um aplicativo estiver em execução, o aplicativo deverá ser interrompido e reiniciado ou o Refresh método deverá ser chamado antes que as novas configurações entrem em vigor.

A TraceEventType enumeração é usada para definir o tipo de evento da mensagem de rastreamento. Os filtros de rastreamento usam o TraceEventType para determinar se um ouvinte de rastreamento deve produzir a mensagem de rastreamento.

Opcionalmente, os ouvintes de rastreamento podem ter uma camada adicional de filtragem por meio de um filtro de rastreamento. Se um ouvinte de rastreamento tiver um filtro associado, o ouvinte chamará o ShouldTrace método nesse filtro para determinar se deve ou não produzir as informações de rastreamento.

Os ouvintes de rastreamento usam os valores das propriedades Indentda Trace classe , IndentSizee AutoFlush para formatar a saída de rastreamento. Em .NET Framework aplicativos, você pode usar atributos de arquivo de configuração para definir as Indentpropriedades , IndentSizee AutoFlush . O exemplo a seguir define a AutoFlush propriedade como false e a IndentSize propriedade como 3.

<configuration>  
  <system.diagnostics>  
    <trace autoflush="false" indentsize="3" />  
  </system.diagnostics>  
</configuration>  

Construtores

TraceSource(String)

Inicializa uma nova instância da classe TraceSource, usando o nome especificado para a fonte.

TraceSource(String, SourceLevels)

Inicializa uma nova instância da classe TraceSource usando o nome especificado para a fonte e o nível da fonte padrão no qual o rastreamento deve ocorrer.

Propriedades

Attributes

Obtém os atributos de opção personalizados definidos no arquivo de configuração de aplicativo.

DefaultLevel

Obtém o nível padrão atribuído no construtor.

Listeners

Obtém a coleção de ouvintes de rastreamento para a origem de rastreamento.

Name

Obtém o nome da origem de rastreamento.

Switch

Obtém ou define o valor da opção de fonte.

Métodos

Close()

Fecha todos os ouvintes de rastreamento na coleção de ouvintes de rastreamento.

Equals(Object)

Determina se o objeto especificado é igual ao objeto atual.

(Herdado de Object)
Flush()

Libera todos os ouvintes de rastreamento na coleção de ouvintes de rastreamento.

GetHashCode()

Serve como a função de hash padrão.

(Herdado de Object)
GetSupportedAttributes()

Obtém os atributos personalizados com suporte da origem de rastreamento.

GetType()

Obtém o Type da instância atual.

(Herdado de Object)
MemberwiseClone()

Cria uma cópia superficial do Object atual.

(Herdado de Object)
ToString()

Retorna uma cadeia de caracteres que representa o objeto atual.

(Herdado de Object)
TraceData(TraceEventType, Int32, Object)

Grava dados de rastreamento para os ouvintes de rastreamento na coleção Listeners usando o tipo de evento, o identificador de evento e os dados de rastreamento especificados.

TraceData(TraceEventType, Int32, Object[])

Grava dados de rastreamento nos ouvintes de rastreamento na coleção Listeners usando o tipo de evento, o identificador de evento e a matriz de dados de rastreamento especificados.

TraceEvent(TraceEventType, Int32)

Grava uma mensagem de evento de rastreamento para os ouvintes de rastreamento na coleção Listeners usando o tipo de evento e o identificador de evento especificados.

TraceEvent(TraceEventType, Int32, String)

Grava uma mensagem de evento de rastreamento para os ouvintes de rastreamento na coleção Listeners usando o tipo de evento, o identificador de evento e a mensagem especificados.

TraceEvent(TraceEventType, Int32, String, Object[])

Grava um evento de rastreamento para os ouvintes de rastreamento na coleção Listeners usando o tipo de evento, o identificador de evento, a matriz de argumentos e o formato especificados.

TraceInformation(String)

Grava uma mensagem informativa para os ouvintes de rastreamento na coleção Listeners usando a mensagem especificada.

TraceInformation(String, Object[])

Grava uma mensagem informativa nos ouvintes de rastreamento na coleção Listeners usando a matriz de objetos e as informações de formatação especificadas.

TraceTransfer(Int32, String, Guid)

Grava uma mensagem de transferência de rastreamento nos ouvintes de rastreamento na coleção Listeners usando o identificador numérico especificado, a mensagem e o identificador de atividade relacionada.

Eventos

Initializing

Ocorre quando um TraceSource precisa ser inicializado.

Aplica-se a

Acesso thread-safe

Este tipo é thread-safe.

Confira também