Поделиться через

TraceSource Класс

Определение

Пространство имен:
System.Diagnostics
Сборки:
netstandard.dll, System.Diagnostics.TraceSource.dll
Сборка:
System.Diagnostics.TraceSource.dll
Сборка:
System.dll
Сборка:
netstandard.dll
Исходный код:
TraceSource.cs
Исходный код:
TraceSource.cs
Исходный код:
TraceSource.cs
Исходный код:
TraceSource.cs
Исходный код:
TraceSource.cs

Предоставляет набор методов и свойств, позволяющих приложениям отслеживать выполнение кода и связывать сообщения трассировки с их источником.

public ref class TraceSource
public class TraceSource
type TraceSource = class
Public Class TraceSource
Наследование
Object
TraceSource

Примеры

В следующем примере кода показано использование класса для пересылки TraceSource трассировок прослушивателям. В примере также показано использование коммутаторов и фильтров.

// 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 показано, как отключить трассировку из источника трассировки и управлять уровнем, на котором происходит трассировка. Можно изменить значение исходного коммутатора без повторной компиляции приложения. Сведения об использовании файла конфигурации для задания коммутатора см. в разделе Switch"Практическое руководство. Создание, инициализация и настройка коммутаторов трассировки".

Замечание

При изменении файла конфигурации во время выполнения приложения приложение должно быть остановлено и перезапущено или Refresh метод должен вызываться до того, как новые параметры вступили в силу.

Перечисление TraceEventType используется для определения типа события сообщения трассировки. Фильтры трассировки используются TraceEventType для определения того, должен ли прослушиватель трассировки создавать сообщение трассировки.

Прослушиватели трассировки могут дополнительно использовать дополнительный слой фильтрации через фильтр трассировки. Если прослушиватель трассировки имеет связанный фильтр, прослушиватель вызывает ShouldTrace метод в этом фильтре, чтобы определить, следует ли создавать сведения трассировки.

Прослушиватели трассировки используют значения Trace свойств IndentIndentSizeкласса, а также AutoFlush для форматирования выходных данных трассировки. В приложениях .NET Framework можно использовать атрибуты файла конфигурации для задания IndentIndentSizeсвойств и AutoFlush свойств. В следующем примере свойству AutoFlushfalseIndentSize присваивается значение 3.

<configuration>
  <system.diagnostics>
    <trace autoflush="false" indentsize="3" />
  </system.diagnostics>
</configuration>

Конструкторы

Имя Описание
TraceSource(String, SourceLevels)

Инициализирует новый экземпляр TraceSource класса, используя указанное имя источника и уровень источника по умолчанию, на котором выполняется трассировка.
TraceSource(String)

Инициализирует новый экземпляр 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, String, Object[])

Записывает событие трассировки в прослушиватели трассировки в Listeners коллекции с помощью указанного типа события, идентификатора события и массива аргументов и формата.
TraceEvent(TraceEventType, Int32, String)

Записывает сообщение о событии трассировки в прослушиватели трассировки в Listeners коллекции с помощью указанного типа события, идентификатора события и сообщения.
TraceEvent(TraceEventType, Int32)

Записывает сообщение о событии трассировки в прослушиватели трассировки в Listeners коллекции с помощью указанного типа события и идентификатора события.
TraceInformation(String, Object[])

Записывает информационное сообщение в прослушиватели трассировки в Listeners коллекции с помощью указанного массива объектов и сведений о форматировании.
TraceInformation(String)

Записывает информационное сообщение в прослушиватели трассировки в Listeners коллекции с помощью указанного сообщения.
TraceTransfer(Int32, String, Guid)

Записывает сообщение о передаче трассировки в прослушиватели трассировки в Listeners коллекции с помощью указанного числового идентификатора, сообщения и связанного идентификатора действия.

События

Имя Описание
Initializing

Происходит при TraceSource инициализации.

Применяется к

Потокобезопасность

Этот тип является потокобезопасной.

См. также раздел