TraceSource Classe
Definição
Importante
Algumas informações se referem a produtos de pré-lançamento que podem ser substancialmente modificados antes do lançamento. A Microsoft não oferece garantias, expressas ou implícitas, das informações aqui fornecidas.
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 ref class TraceSourcepublic class TraceSourcetype TraceSource = classPublic 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.
/////////////////////////////////////////////////////////////////////////////////
//
// NAME TraceSource2.cpp : main project file
//
/////////////////////////////////////////////////////////////////////////////////
// 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.dll>
using namespace System;
using namespace System::Collections;
using namespace System::Diagnostics;
using namespace System::Reflection;
using namespace System::IO;
using namespace System::Security::Permissions;
void DisplayProperties(TraceSource^ ts); // Forward Declaration
int main()
{
TraceSource^ ts = gcnew TraceSource("TraceTest");
try
{
// Initialize trace switches.
#if(!ConfigFile)
SourceSwitch^ sourceSwitch = gcnew SourceSwitch("SourceSwitch", "Verbose");
ts->Switch = sourceSwitch;
int idxConsole = ts->Listeners->Add(gcnew 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 = gcnew SourceFilter("No match");
ts->TraceData(TraceEventType::Error, 5,
"SourceFilter should reject this message for the console trace listener.");
ts->Listeners["console"]->Filter = gcnew SourceFilter("TraceTest");
ts->TraceData(TraceEventType::Error, 6,
"SourceFilter should let this message through on the console trace listener.");
ts->Listeners["console"]->Filter = nullptr;
// Use the TraceData method.
ts->TraceData(TraceEventType::Warning, 7, gcnew array<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 enter key to exit.");
Console::Read();
}
catch (Exception ^e)
{
// Catch any unexpected exception.
Console::WriteLine("Unexpected exception: " + e->ToString());
Console::Read();
}
}
void DisplayProperties(TraceSource^ ts)
{
Console::WriteLine("TraceSource name = " + ts->Name);
// Console::WriteLine("TraceSource switch level = " + ts->Switch->Level); // error C3063: operator '+': all operands must have the same enumeration type
Console::WriteLine("TraceSource switch level = {0}", ts->Switch->Level); // SUCCESS: does compile. Weird
Console::WriteLine("TraceSource Attributes Count " + ts->Attributes->Count); // SUCCESS: also compiles. Really weird
Console::WriteLine("TraceSource Attributes Count = {0}", ts->Attributes->Count); // SUCCESS: okay, I give up. Somebody call me a cab.
Console::WriteLine("TraceSource switch = " + ts->Switch->DisplayName);
array<SwitchAttribute^>^ switches = SwitchAttribute::GetAll(TraceSource::typeid->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);
for each (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));
}
}
// 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));
}
}
}
}
' 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>
#Const TRACE = True
'#Const ConfigFile = True
Imports System.Collections
Imports System.Diagnostics
Imports System.Reflection
Imports System.IO
Imports System.Security.Permissions
Class TraceTest
' Initialize the trace source.
Private Shared ts As New TraceSource("TraceTest")
<SwitchAttribute("SourceSwitch", GetType(SourceSwitch))> _
Shared Sub Main()
Try
' Initialize trace switches.
#If (ConfigFile = False) Then
Dim sourceSwitch As New SourceSwitch("SourceSwitch", "Verbose")
ts.Switch = sourceSwitch
Dim idxConsole As New Integer()
idxConsole = ts.Listeners.Add(New System.Diagnostics.ConsoleTraceListener())
ts.Listeners(idxConsole).Name = "console"
#End If
DisplayProperties(ts)
ts.Listeners("console").TraceOutputOptions = ts.Listeners("console").TraceOutputOptions Or 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 = ts.Listeners("console").TraceOutputOptions Or 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 = Nothing
' 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 Or 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 e As Exception
' Catch any unexpected exception.
Console.WriteLine("Unexpected exception: " + e.ToString())
Console.Read()
End Try
End Sub
Public Shared Sub DisplayProperties(ByVal ts As TraceSource)
Console.WriteLine("TraceSource name = " + ts.Name)
Console.WriteLine("TraceSource switch level = " + ts.Switch.Level.ToString())
Console.WriteLine("TraceSource switch = " + ts.Switch.DisplayName.ToString())
Dim switches As SwitchAttribute() = SwitchAttribute.GetAll(GetType(TraceTest).Assembly)
Dim i As Integer
For i = 0 To switches.Length - 1
Console.WriteLine("Switch name = " + switches(i).SwitchName.ToString())
Console.WriteLine("Switch type = " + switches(i).SwitchType.ToString())
Next i
#If (ConfigFile) Then
' Get the custom attributes for the TraceSource.
Console.WriteLine("Number of custom trace source attributes = " + ts.Attributes.Count)
Dim de As DictionaryEntry
For Each de In ts.Attributes
Console.WriteLine("Custom trace source attribute = " + de.Key + " " + de.Value)
Next de
' Get the custom attributes for the trace source switch.
For Each de In ts.Switch.Attributes
Console.WriteLine("Custom switch attribute = " + de.Key + " " + de.Value)
Next de
#End If
Console.WriteLine("Number of listeners = " + ts.Listeners.Count.ToString())
Dim traceListener As TraceListener
For Each traceListener In ts.Listeners
Console.Write("TraceListener: " + traceListener.Name + vbTab)
' The following output can be used to update the configuration file.
Console.WriteLine("AssemblyQualifiedName = " + traceListener.GetType().AssemblyQualifiedName)
Next traceListener
End Sub
End Class
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.
