TraceSource Clase
Definición
Importante
Parte de la información hace referencia a la versión preliminar del producto, que puede haberse modificado sustancialmente antes de lanzar la versión definitiva. Microsoft no otorga ninguna garantía, explícita o implícita, con respecto a la información proporcionada aquí.
Proporciona un conjunto de métodos y propiedades que permiten que las aplicaciones realicen un seguimiento de la ejecución de código y asocien mensajes de seguimiento con su origen.
public ref class TraceSourcepublic class TraceSourcetype TraceSource = classPublic Class TraceSource- Herencia
-
TraceSource
Ejemplos
En el ejemplo de código siguiente se muestra el uso de la TraceSource clase para reenviar seguimientos a los agentes de escucha. En el ejemplo también se muestra el uso de conmutadores y filtros.
/////////////////////////////////////////////////////////////////////////////////
//
// 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
Comentarios
Las aplicaciones utilizan la clase TraceSource para generar seguimientos que pueden asociarse con la aplicación. TraceSource proporciona métodos de traza que permiten rastrear fácilmente eventos y datos, así como emitir seguimientos de información.
En las aplicaciones de .NET Framework, la salida de seguimiento de TraceSource se puede controlar mediante la configuración del archivo de configuración. El archivo de configuración se encuentra en la carpeta con el ejecutable de la aplicación y tiene el nombre de la aplicación con la extensión .config agregada. Por ejemplo, el nombre del archivo de configuración de TraceSourceSample.exe es TraceSourceSample.exe.config. El archivo de configuración se puede usar para especificar dónde se enviará la información de seguimiento y qué niveles de actividad se van a realizar. En el ejemplo siguiente se muestra el contenido de un archivo de configuración de aplicación de .NET Framework de ejemplo.
<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>
La TraceSource clase se identifica por el nombre de un origen, normalmente el nombre de la aplicación. Los mensajes de seguimiento procedentes de un componente determinado se pueden iniciar mediante un origen de seguimiento determinado, lo que permite identificar fácilmente todos los mensajes procedentes de ese componente.
TraceSource define métodos de seguimiento, pero no proporciona realmente ningún mecanismo específico para generar y almacenar datos de seguimiento. Los datos de seguimiento se generan mediante agentes de escucha de seguimiento, que son complementos que los orígenes de seguimiento pueden cargar.
Nota
No debe llamar a los métodos de seguimiento durante la finalización. Si lo hace, se puede producir una ObjectDisposedException excepción .
Puede personalizar el destino de la salida de seguimiento agregando o quitando TraceListener instancias a o desde la colección almacenada en la TraceSource.Listeners propiedad . De forma predeterminada, la salida de seguimiento se genera mediante una instancia de la DefaultTraceListener clase .
En el ejemplo anterior del archivo de configuración de aplicaciones de .NET Framework se muestra cómo quitar DefaultTraceListener y agregar un ConsoleTraceListener para generar la salida de seguimiento para el origen de seguimiento. Para obtener más información, consulte <agentes> de escucha y <sharedListeners>.
Nota
Agregar un agente de escucha de seguimiento a la Listeners colección puede provocar una excepción durante el seguimiento, si un recurso usado por el agente de escucha de seguimiento no está disponible. Las condiciones y la excepción iniciada dependen del agente de escucha de seguimiento y no se pueden enumerar en este tema. Puede ser útil realizar llamadas a los TraceSource métodos en try/catch bloques para detectar y controlar las excepciones de los agentes de escucha de seguimiento.
La SourceSwitch clase proporciona los medios para controlar dinámicamente la salida de seguimiento. En el caso de las aplicaciones de .NET Framework, el ejemplo de archivo de configuración anterior muestra cómo puede desactivar el seguimiento desde un origen de seguimiento y controlar el nivel en el que se produce el seguimiento. Puede modificar el valor del modificador de origen sin volver a compilar la aplicación. Para obtener información sobre cómo usar el archivo de configuración para establecer un conmutador, vea Switch y Cómo: Create, Inicializar y configurar modificadores de seguimiento.
Nota
Si modifica un archivo de configuración mientras se ejecuta una aplicación, la aplicación debe detenerse y reiniciarse o se debe llamar al Refresh método antes de que la nueva configuración surta efecto.
La TraceEventType enumeración se usa para definir el tipo de evento del mensaje de seguimiento. Los filtros de seguimiento usan TraceEventType para determinar si un agente de escucha de seguimiento debe generar el mensaje de seguimiento.
Opcionalmente, los agentes de escucha de seguimiento pueden tener una capa adicional de filtrado a través de un filtro de seguimiento. Si un agente de escucha de seguimiento tiene un filtro asociado, el agente de escucha llama al ShouldTrace método en ese filtro para determinar si se va a generar o no la información de seguimiento.
Los agentes de escucha de seguimiento usan los valores de las propiedades de la Trace clase , IndentSizey AutoFlush para dar formato a la salida de Indentseguimiento. En las aplicaciones de .NET Framework, puede usar atributos de archivo de configuración para establecer las Indentpropiedades , IndentSizey AutoFlush . En el ejemplo siguiente se establece la AutoFlush propiedad false en y la IndentSize propiedad en 3.
<configuration>
<system.diagnostics>
<trace autoflush="false" indentsize="3" />
</system.diagnostics>
</configuration>
Constructores
| TraceSource(String) |
Inicializa una instancia nueva de la clase TraceSource usando el nombre especificado para el origen. |
| TraceSource(String, SourceLevels) |
Inicializa una nueva instancia de la clase TraceSource con el nombre especificado para el origen y el nivel de origen predeterminado en el que se producirá el seguimiento. |
Propiedades
| Attributes |
Obtiene los atributos de modificador personalizados definidos en el archivo de configuración de la aplicación. |
| DefaultLevel |
Obtiene el nivel predeterminado asignado en el constructor. |
| Listeners |
Obtiene la colección de agentes de escucha de seguimiento para el origen de seguimiento. |
| Name |
Obtiene el nombre del origen de seguimiento. |
| Switch |
Obtiene o establece el valor del modificador de origen. |
Métodos
| Close() |
Cierra todos los agentes de escucha de seguimiento en la colección de agentes de escucha de seguimiento. |
| Equals(Object) |
Determina si el objeto especificado es igual que el objeto actual. (Heredado de Object) |
| Flush() |
Vacía todos los agentes de escucha de seguimiento en la colección de agentes de escucha de seguimiento. |
| GetHashCode() |
Sirve como la función hash predeterminada. (Heredado de Object) |
| GetSupportedAttributes() |
Obtiene los atributos personalizados admitidos por el origen de seguimiento. |
| GetType() |
Obtiene el Type de la instancia actual. (Heredado de Object) |
| MemberwiseClone() |
Crea una copia superficial del Object actual. (Heredado de Object) |
| ToString() |
Devuelve una cadena que representa el objeto actual. (Heredado de Object) |
| TraceData(TraceEventType, Int32, Object) |
Escribe datos de seguimiento en los agentes de escucha de seguimiento de la colección Listeners con el tipo de evento, el identificador de evento y los datos de seguimiento especificados. |
| TraceData(TraceEventType, Int32, Object[]) |
Escribe datos de seguimiento en los agentes de escucha de seguimiento de la colección Listeners con el tipo de evento, el identificador de evento y la matriz de datos de seguimiento especificados. |
| TraceEvent(TraceEventType, Int32) |
Escribe un mensaje de evento de seguimiento en los agentes de escucha de seguimiento de la colección Listeners con el tipo de evento y el identificador de evento especificados. |
| TraceEvent(TraceEventType, Int32, String) |
Escribe un mensaje de evento de seguimiento en los agentes de escucha de seguimiento de la colección Listeners con el tipo de evento, el identificador de evento y el mensaje especificados. |
| TraceEvent(TraceEventType, Int32, String, Object[]) |
Escribe un evento de seguimiento en los agentes de escucha de seguimiento de la colección Listeners con el tipo de evento, el identificador de evento y el formato y la matriz de argumentos especificados. |
| TraceInformation(String) |
Escribe un mensaje informativo en los agentes de escucha de seguimiento de la colección Listeners con el mensaje especificado. |
| TraceInformation(String, Object[]) |
Escribe un mensaje informativo en los agentes de escucha de seguimiento de la colección Listeners con la matriz de objetos y la información de formato especificadas. |
| TraceTransfer(Int32, String, Guid) |
Escribe un mensaje de transferencia de seguimiento en los agentes de escucha de seguimiento de la colección Listeners con el identificador numérico, el mensaje y el identificador de actividad relacionado especificados. |
Eventos
| Initializing |
Se produce cuando es necesario inicializar .TraceSource |
Se aplica a
Seguridad para subprocesos
Este tipo es seguro para la ejecución de subprocesos.
