TraceSource Classe
Definizione
Importante
Alcune informazioni sono relative alla release non definitiva del prodotto, che potrebbe subire modifiche significative prima della release definitiva. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.
Fornisce un set di metodi e proprietà che consentono alle applicazioni di tracciare l'esecuzione del codice e associare messaggi di traccia alla relativa origine.
public ref class TraceSourcepublic class TraceSourcetype TraceSource = classPublic Class TraceSource- Ereditarietà
-
TraceSource
Esempio
Nell'esempio di codice seguente viene illustrato l'uso della TraceSource classe per inoltrare le tracce ai listener. L'esempio illustra anche l'utilizzo del commutatore e del 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));
}
}
}
}
' 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
Commenti
La TraceSource classe viene usata dalle applicazioni per produrre tracce che possono essere associate all'applicazione. TraceSource fornisce metodi di tracciamento che consentono di tracciare facilmente eventi, dati di tracciamento e generare tracce informative.
Nelle app .NET Framework l'output di traccia da TraceSource può essere controllato dalle impostazioni del file di configurazione. Il file di configurazione si trova nella cartella con l'eseguibile dell'applicazione e ha il nome dell'applicazione con l'estensione .config aggiunta. Ad esempio, il nome del file di configurazione per TraceSourceSample.exe è TraceSourceSample.exe.config. Il file di configurazione può essere usato per specificare dove inviare le informazioni di traccia e quali livelli di attività devono essere tracciati. L'esempio seguente illustra il contenuto di un file di configurazione dell'applicazione .NET Framework di esempio.
<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 classe è identificata dal nome di un'origine, in genere il nome dell'applicazione. I messaggi di traccia provenienti da un determinato componente possono essere avviati da una determinata origine di traccia, consentendo di identificare facilmente tutti i messaggi provenienti da tale componente.
TraceSource definisce i metodi di traccia, ma non fornisce effettivamente alcun meccanismo specifico per la generazione e l'archiviazione dei dati di traccia. I dati di traccia vengono generati dai listener di traccia, che sono plug-in che possono essere caricati dalle origini di traccia.
Annotazioni
Non è consigliabile chiamare i metodi di traccia durante la finalizzazione. In questo modo può verificarsi un'eccezione ObjectDisposedException generata.
È possibile personalizzare la destinazione dell'output di traccia aggiungendo o rimuovendo TraceListener istanze da o verso la raccolta archiviata nella TraceSource.Listeners proprietà . Per impostazione predefinita, l'output di traccia viene generato usando un'istanza della DefaultTraceListener classe .
L'esempio di file di configurazione dell'app .NET Framework precedente illustra la rimozione di e l'aggiunta DefaultTraceListener di un ConsoleTraceListener oggetto per produrre l'output di traccia per l'origine di traccia. Per altre informazioni, vedere <Listener> e <sharedListeners>.
Annotazioni
L'aggiunta di un listener di traccia alla raccolta può causare la generazione di un'eccezione durante la Listeners traccia, se non è disponibile una risorsa usata dal listener di traccia. Le condizioni e l'eccezione generata dipendono dal listener di traccia e non possono essere enumerate in questo argomento. Può essere utile inserire chiamate ai TraceSource metodi in try/catch blocchi per rilevare e gestire eventuali eccezioni dai listener di traccia.
La SourceSwitch classe fornisce i mezzi per controllare dinamicamente l'output di traccia. Per le app .NET Framework, l'esempio di file di configurazione precedente mostra come disattivare la traccia da un'origine di traccia e controllare il livello in cui si verifica la traccia. È possibile modificare il valore dell'opzione di origine senza ricompilare l'applicazione. Per informazioni sull'uso del file di configurazione per impostare un'opzione, vedere SwitchProcedura: Creare, inizializzare e configurare opzioni di traccia.
Annotazioni
Se si modifica un file di configurazione durante l'esecuzione di un'applicazione, l'applicazione deve essere arrestata e riavviata oppure è necessario chiamare il Refresh metodo prima che le nuove impostazioni siano effettive.
L'enumerazione TraceEventType viene utilizzata per definire il tipo di evento del messaggio di traccia. I filtri di traccia usano per TraceEventType determinare se un listener di traccia deve produrre il messaggio di traccia.
I listener di traccia possono facoltativamente avere un ulteriore livello di filtro tramite un filtro di traccia. Se un listener di traccia dispone di un filtro associato, il listener chiama il ShouldTrace metodo su tale filtro per determinare se produrre o meno le informazioni di traccia.
I listener di traccia usano i valori delle proprietà Indentdella Trace classe , IndentSizee AutoFlush per formattare l'output di traccia. Nelle app .NET Framework è possibile usare gli attributi del file di configurazione per impostare le Indentproprietà , IndentSizee AutoFlush . Nell'esempio seguente la AutoFlush proprietà viene impostata su false e la IndentSize proprietà su 3.
<configuration>
<system.diagnostics>
<trace autoflush="false" indentsize="3" />
</system.diagnostics>
</configuration>
Costruttori
| Nome | Descrizione |
|---|---|
| TraceSource(String, SourceLevels) |
Inizializza una nuova istanza della TraceSource classe utilizzando il nome specificato per l'origine e il livello di origine predefinito in cui deve verificarsi la traccia. |
| TraceSource(String) |
Inizializza una nuova istanza della TraceSource classe utilizzando il nome specificato per l'origine. |
Proprietà
| Nome | Descrizione |
|---|---|
| Attributes |
Ottiene gli attributi del commutatore personalizzato definiti nel file di configurazione dell'applicazione. |
| DefaultLevel |
Ottiene il livello predefinito assegnato nel costruttore. |
| Listeners |
Ottiene la raccolta di listener di traccia per l'origine di traccia. |
| Name |
Ottiene il nome dell'origine di traccia. |
| Switch |
Ottiene o imposta il valore dell'opzione di origine. |
Metodi
| Nome | Descrizione |
|---|---|
| Close() |
Chiude tutti i listener di traccia nella raccolta di listener di traccia. |
| Equals(Object) |
Determina se l'oggetto specificato è uguale all'oggetto corrente. (Ereditato da Object) |
| Flush() |
Scarica tutti i listener di traccia nella raccolta di listener di traccia. |
| GetHashCode() |
Funge da funzione hash predefinita. (Ereditato da Object) |
| GetSupportedAttributes() |
Ottiene gli attributi personalizzati supportati dall'origine di traccia. |
| GetType() |
Ottiene il Type dell'istanza corrente. (Ereditato da Object) |
| MemberwiseClone() |
Crea una copia superficiale del Objectcorrente. (Ereditato da Object) |
| ToString() |
Restituisce una stringa che rappresenta l'oggetto corrente. (Ereditato da Object) |
| TraceData(TraceEventType, Int32, Object) |
Scrive i dati di traccia nei listener di traccia nella Listeners raccolta usando il tipo di evento, l'identificatore dell'evento e i dati di traccia specificati. |
| TraceData(TraceEventType, Int32, Object[]) |
Scrive i dati di traccia nei listener di traccia nella Listeners raccolta usando il tipo di evento, l'identificatore dell'evento e la matrice di dati di traccia specificati. |
| TraceEvent(TraceEventType, Int32, String, Object[]) |
Scrive un evento di traccia nei listener di traccia nella Listeners raccolta utilizzando il tipo di evento, l'identificatore dell'evento e la matrice di argomenti e il formato specificati. |
| TraceEvent(TraceEventType, Int32, String) |
Scrive un messaggio di evento di traccia nei listener di traccia nella Listeners raccolta utilizzando il tipo di evento, l'identificatore di evento e il messaggio specificati. |
| TraceEvent(TraceEventType, Int32) |
Scrive un messaggio di evento di traccia nei listener di traccia nella Listeners raccolta utilizzando il tipo di evento e l'identificatore di evento specificati. |
| TraceInformation(String, Object[]) |
Scrive un messaggio informativo nei listener di traccia nella Listeners raccolta utilizzando la matrice di oggetti e le informazioni di formattazione specificate. |
| TraceInformation(String) |
Scrive un messaggio informativo nei listener di traccia nella Listeners raccolta utilizzando il messaggio specificato. |
| TraceTransfer(Int32, String, Guid) |
Scrive un messaggio di trasferimento di traccia nei listener di traccia nella Listeners raccolta usando l'identificatore numerico, il messaggio e l'identificatore di attività correlato specificati. |
Eventi
| Nome | Descrizione |
|---|---|
| Initializing |
Si verifica quando un oggetto TraceSource deve essere inizializzato. |
Si applica a
Thread safety
Questo tipo è thread-safe.
