TraceSource Класс
Определение
Важно!
Некоторые сведения относятся к предварительной версии продукта, в которую до выпуска могут быть внесены существенные изменения. Майкрософт не предоставляет никаких гарантий, явных или подразумеваемых, относительно приведенных здесь сведений.
Предоставляет набор методов и свойств, которые позволяют приложениям делать трассировку выполнения кода и связывать сообщения трассировки с их источником.
public ref class TraceSource
public class TraceSource
type TraceSource = class
Public Class TraceSource
- Наследование
-
TraceSource
Примеры
В следующем примере кода показано использование класса для TraceSource пересылки трассировок в прослушиватели. В этом примере также демонстрируется использование переключения и фильтрации.
/////////////////////////////////////////////////////////////////////////////////
//
// 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
Комментарии
Класс TraceSource используется приложениями для создания трассировок, которые могут быть связаны с приложением. TraceSource предоставляет методы трассировки, позволяющие легко трассировать события, трассировать данные и выпускать информационные трассировки.
В платформа .NET Framework приложениях выходные данные трассировки из TraceSource можно контролировать с помощью параметров файла конфигурации. Файл конфигурации находится в папке с исполняемым файлом приложения и имеет имя приложения с добавленным расширением .config. Например, имя файла конфигурации для TraceSourceSample.exe — TraceSourceSample.exe.config. Файл конфигурации можно использовать для указания места отправки сведений трассировки и уровней активности для трассировки. В следующем примере показано содержимое примера платформа .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>
Класс TraceSource идентифицируется по имени источника, как правило, по имени приложения. Сообщения трассировки, поступающие от определенного компонента, могут быть инициированы определенным источником трассировки, что позволяет легко идентифицировать все сообщения, поступающие от этого компонента.
TraceSource определяет методы трассировки, но фактически не предоставляет какого-либо конкретного механизма для создания и хранения данных трассировки. Данные трассировки создаются прослушивателями трассировки, которые являются подключаемыми модулями, которые могут быть загружены источниками трассировки.
Примечание
Не следует вызывать методы трассировки во время завершения. Это может привести к возникновению ObjectDisposedException ошибки.
Вы можете настроить целевой объект выходных данных трассировки, добавив или удалив TraceListener экземпляры коллекции, хранящейся в свойстве TraceSource.Listeners . По умолчанию выходные данные трассировки создаются с помощью экземпляра DefaultTraceListener класса .
В приведенном выше платформа .NET Framework примере файла конфигурации приложения показано удаление DefaultTraceListener и добавление для ConsoleTraceListener создания выходных данных трассировки для источника трассировки. Дополнительные сведения см. в статье <Прослушиватели> и <sharedListeners>.
Примечание
Добавление прослушивателя трассировки в коллекцию Listeners может привести к возникновению исключения при трассировке, если ресурс, используемый прослушивателем трассировки, недоступен. Условия и исключение зависят от прослушивателя трассировки и не могут быть перечислены в этом разделе. Может быть полезно разместить вызовы TraceSource методов в try
/catch
блоках для обнаружения и обработки исключений из прослушивателей трассировки.
Класс SourceSwitch предоставляет средства для динамического управления выходными данными трассировки. Для платформа .NET Framework приложений в предыдущем примере файла конфигурации показано, как отключить трассировку из источника трассировки и управлять уровнем, на котором выполняется трассировка. Значение параметра источника можно изменить без перекомпиляции приложения. Сведения об использовании файла конфигурации для установки коммутатора см. в разделах и Практическое руководство. Create, Инициализация и настройка коммутаторов трассировки.Switch
Примечание
При изменении файла конфигурации во время выполнения приложения приложение должно быть остановлено и перезапущено либо Refresh метод должен быть вызван до того, как новые параметры вступают в силу.
Перечисление TraceEventType используется для определения типа события сообщения трассировки. Фильтры трассировки используют , TraceEventType чтобы определить, должен ли прослушиватель трассировки создавать сообщение трассировки.
Прослушиватели трассировки при необходимости могут иметь дополнительный уровень фильтрации с помощью фильтра трассировки. Если прослушиватель трассировки имеет связанный фильтр, прослушиватель вызывает ShouldTrace метод для этого фильтра, чтобы определить, следует ли создавать данные трассировки.
Прослушиватели трассировки используют значения Trace свойств Indentкласса , IndentSizeи AutoFlush для форматирования выходных данных трассировки. В платформа .NET Framework приложениях можно использовать атрибуты файла конфигурации для задания Indentсвойств , IndentSizeи AutoFlush . В следующем примере свойству AutoFlush присваивается значение , false
а свойству IndentSize — значение 3.
<configuration>
<system.diagnostics>
<trace autoflush="false" indentsize="3" />
</system.diagnostics>
</configuration>
Конструкторы
TraceSource(String) |
Инициализирует новый экземпляр класса TraceSource, используя указанное имя источника. |
TraceSource(String, SourceLevels) |
Инициализирует новый экземпляр класса TraceSource, используя заданное для источника имя и уровень источника по умолчанию, при котором происходит трассировка. |
Свойства
Attributes |
Получает настраиваемые атрибуты переключателя, определенные в файле конфигурации приложения. |
DefaultLevel |
Возвращает уровень по умолчанию, назначенный в конструкторе. |
Listeners |
Получает коллекцию прослушивателей трассировки для ее источника. |
Name |
Получает имя источника трассировки. |
Switch |
Получает или задает значение переключателя источника. |
Методы
Close() |
Закрывает все прослушиватели трассировки в коллекции таких прослушивателей. |
Equals(Object) |
Определяет, равен ли указанный объект текущему объекту. (Унаследовано от Object) |
Flush() |
Записывает все прослушиватели трассировки в коллекции таких прослушивателей. |
GetHashCode() |
Служит хэш-функцией по умолчанию. (Унаследовано от Object) |
GetSupportedAttributes() |
Получает настраиваемые атрибуты, поддерживаемые источником трассировки. |
GetType() |
Возвращает объект Type для текущего экземпляра. (Унаследовано от Object) |
MemberwiseClone() |
Создает неполную копию текущего объекта Object. (Унаследовано от Object) |
ToString() |
Возвращает строку, представляющую текущий объект. (Унаследовано от Object) |
TraceData(TraceEventType, Int32, Object) |
Записывает данные трассировки в прослушиватели трассировки коллекции Listeners, используя для этого указанный тип и идентификатор события, а также данные трассировки. |
TraceData(TraceEventType, Int32, Object[]) |
Записывает данные трассировки в прослушиватели трассировки коллекции Listeners, используя для этого указанный тип и идентификатор события, а также данные трассировки. |
TraceEvent(TraceEventType, Int32) |
Записывает сообщение о событии трассировки в прослушиватели трассировки коллекции Listeners, используя для этого указанный тип и идентификатор события. |
TraceEvent(TraceEventType, Int32, String) |
Записывает сообщение о событии трассировки в прослушиватели трассировки коллекции Listeners, используя для этого указанный тип и идентификатор события, а также сообщение. |
TraceEvent(TraceEventType, Int32, String, Object[]) |
Записывает сообщение о событии трассировки в прослушиватели трассировки коллекции Listeners, используя для этого указанный тип и идентификатор события, а также массив аргументов и формат. |
TraceInformation(String) |
Записывает информационное сообщение в прослушиватели трассировки коллекции Listeners, используя для этого указанное сообщение. |
TraceInformation(String, Object[]) |
Записывает информационное сообщение в прослушиватели трассировки коллекции Listeners, используя для этого указанный массив объектов и сведения о форматировании. |
TraceTransfer(Int32, String, Guid) |
Записывает сообщение о перемещении трассировки в прослушиватели трассировки коллекции Listeners, используя для этого указанный числовой идентификатор, сообщение, а также идентификатор сопутствующего действия. |
События
Initializing |
Возникает, когда необходимо инициализировать TraceSource объект . |
Применяется к
Потокобезопасность
Данный тип потокобезопасен.