TraceSource Třída
Definice
Důležité
Některé informace platí pro předběžně vydaný produkt, který se může zásadně změnit, než ho výrobce nebo autor vydá. Microsoft neposkytuje žádné záruky, výslovné ani předpokládané, týkající se zde uváděných informací.
Poskytuje sadu metod a vlastností, které umožňují aplikacím trasovat provádění kódu a přidružit trasovací zprávy k jejich zdroji.
public ref class TraceSource
public class TraceSource
type TraceSource = class
Public Class TraceSource
- Dědičnost
-
TraceSource
Příklady
Následující příklad kódu ukazuje použití TraceSource třídy k předávání trasování naslouchacím procesům. Příklad také ukazuje použití přepínače a filtru.
/////////////////////////////////////////////////////////////////////////////////
//
// 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
Poznámky
Třída TraceSource je používána aplikacemi k vytváření trasování, která mohou být přidružena k aplikaci. TraceSource poskytuje metody trasování, které umožňují snadné trasování událostí, trasování dat a vydávání informačních trasování.
V aplikacích .NET Framework je možné výstup trasování z TraceSource řídit nastavením konfiguračního souboru. Konfigurační soubor se nachází ve složce se spustitelným souborem aplikace a má název aplikace s přidanou příponou .config. Například název konfiguračního souboru pro TraceSourceSample.exe je TraceSourceSample.exe.config. Konfigurační soubor lze použít k určení, kam se mají informace o trasování odesílat a jaké úrovně aktivity se mají sledovat. Následující příklad ukazuje obsah ukázkového konfiguračního souboru aplikace rozhraní .NET Framework.
<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>
Třída TraceSource je identifikována názvem zdroje, obvykle názvem aplikace. Zprávy trasování pocházející z konkrétní komponenty mohou být inicializovány konkrétním zdrojem trasování, což umožňuje snadno identifikovat všechny zprávy pocházející z této komponenty.
TraceSource definuje metody trasování, ale ve skutečnosti neposkytuje žádný konkrétní mechanismus pro generování a ukládání dat trasování. Data trasování jsou vytvářena naslouchacími procesy trasování, což jsou moduly plug-in, které lze načíst pomocí zdrojů trasování.
Poznámka
Během finalizace byste neměli volat metody trasování. To může vést k ObjectDisposedException vyvolání.
Cíl výstupu trasování můžete přizpůsobit přidáním nebo odebráním TraceListener instancí do nebo z kolekce uložené ve TraceSource.Listeners vlastnosti . Ve výchozím nastavení se výstup trasování vytváří pomocí instance DefaultTraceListener třídy .
Předchozí příklad konfiguračního souboru aplikace rozhraní .NET Framework ukazuje odebrání DefaultTraceListener a přidání ConsoleTraceListener a k vytvoření výstupu trasování pro zdroj trasování. Další informace najdete v tématu <o naslouchacích> procesů a <sharedListeners>.
Poznámka
Přidání naslouchacího Listeners procesu trasování do kolekce může způsobit výjimku při trasování, pokud prostředek používaný naslouchacím procesem trasování není k dispozici. Podmínky a vyvolaná výjimka závisí na naslouchacím procesu trasování a nelze je v tomto tématu vyčíslit. Může být užitečné umístit volání TraceSource metod do try
/catch
bloků, aby se zjistily a zpracovály případné výjimky z naslouchacích procesů trasování.
Třída SourceSwitch poskytuje prostředky pro dynamické řízení výstupu trasování. U aplikací .NET Framework předchozí příklad konfiguračního souboru ukazuje, jak můžete vypnout trasování ze zdroje trasování a řídit úroveň, na které k trasování dochází. Hodnotu zdrojového přepínače můžete upravit bez opětovného zkompilování aplikace. Informace o použití konfiguračního souboru k nastavení přepínače najdete v tématech Switch a Postupy: Create, Inicializace a konfigurace přepínačů trasování.
Poznámka
Pokud upravíte konfigurační soubor během provádění aplikace, musí být aplikace zastavena a restartována nebo Refresh musí být volána metoda, aby se nové nastavení projevilo.
Výčet TraceEventType slouží k definování typu události zprávy trasování. Filtry trasování používají TraceEventType k určení, jestli má trasovací naslouchací proces vytvořit trasovací zprávu.
Naslouchací procesy trasování mohou mít volitelně další vrstvu filtrování prostřednictvím filtru trasování. Pokud má naslouchací proces trasování přidružený filtr, naslouchací proces zavolá metodu ShouldTrace pro tento filtr, aby určil, zda se mají vytvořit informace o trasování.
Naslouchací Trace procesy trasování používají hodnoty vlastností Indenttřídy , IndentSizea AutoFlush k formátování výstupu trasování. V aplikacích .NET Framework můžete pomocí atributů konfiguračního Indentsouboru nastavit vlastnosti , IndentSizea AutoFlush . Následující příklad nastaví AutoFlush vlastnost na false
a vlastnost IndentSize na hodnotu 3.
<configuration>
<system.diagnostics>
<trace autoflush="false" indentsize="3" />
</system.diagnostics>
</configuration>
Konstruktory
TraceSource(String) |
Inicializuje novou instanci TraceSource třídy pomocí zadaného názvu zdroje. |
TraceSource(String, SourceLevels) |
Inicializuje novou instanci TraceSource třídy pomocí zadaného názvu pro zdroj a výchozí úroveň zdroje, na které má dojít k trasování. |
Vlastnosti
Attributes |
Získá vlastní atributy přepínače definované v konfiguračním souboru aplikace. |
DefaultLevel |
Získá výchozí úroveň přiřazenou v konstruktoru. |
Listeners |
Získá kolekci trasovacích naslouchacích procesů pro zdroj trasování. |
Name |
Získá název zdroje trasování. |
Switch |
Získá nebo nastaví hodnotu zdrojového přepínače. |
Metody
Close() |
Zavře všechny naslouchací procesy trasování v kolekci naslouchacího procesu trasování. |
Equals(Object) |
Určí, zda se zadaný objekt rovná aktuálnímu objektu. (Zděděno od Object) |
Flush() |
Vyprázdní všechny naslouchací procesy trasování v kolekci naslouchacího procesu trasování. |
GetHashCode() |
Slouží jako výchozí hashovací funkce. (Zděděno od Object) |
GetSupportedAttributes() |
Získá vlastní atributy podporované zdrojem trasování. |
GetType() |
Type Získá z aktuální instance. (Zděděno od Object) |
MemberwiseClone() |
Vytvoří mělkou kopii aktuálního Objectsouboru . (Zděděno od Object) |
ToString() |
Vrátí řetězec, který představuje aktuální objekt. (Zděděno od Object) |
TraceData(TraceEventType, Int32, Object) |
Zapisuje data trasování do naslouchacích procesů trasování v kolekci Listeners pomocí zadaného typu události, identifikátoru události a dat trasování. |
TraceData(TraceEventType, Int32, Object[]) |
Zapisuje data trasování do naslouchacích procesů trasování v kolekci Listeners pomocí zadaného typu události, identifikátoru události a pole dat trasování. |
TraceEvent(TraceEventType, Int32) |
Zapíše zprávu události trasování do naslouchacích procesů trasování v kolekci Listeners pomocí zadaného typu události a identifikátoru události. |
TraceEvent(TraceEventType, Int32, String) |
Zapíše zprávu události trasování do naslouchacích procesů trasování v kolekci Listeners pomocí zadaného typu události, identifikátoru události a zprávy. |
TraceEvent(TraceEventType, Int32, String, Object[]) |
Zapíše událost trasování do naslouchacích procesů trasování v kolekci Listeners pomocí zadaného typu události, identifikátoru události a pole a formátu argumentů. |
TraceInformation(String) |
Zapíše informační zprávu do naslouchacích procesů trasování v kolekci Listeners pomocí zadané zprávy. |
TraceInformation(String, Object[]) |
Zapíše informační zprávu naslouchacím procesům trasování v kolekci Listeners pomocí zadaného pole objektu a informací o formátování. |
TraceTransfer(Int32, String, Guid) |
Zapíše zprávu o přenosu trasování do naslouchacích procesů trasování v kolekci Listeners pomocí zadaného číselného identifikátoru, zprávy a identifikátoru související aktivity. |
Událost
Initializing |
Vyvolá se, TraceSource když je potřeba inicializovat. |
Platí pro
Bezpečný přístup z více vláken
Tento typ je bezpečný pro přístup z více vláken.