EventSource 类

定义

提供为 Windows 事件跟踪 (ETW) 创建事件的功能。Provides the ability to create events for event tracing for Windows (ETW).

public ref class EventSource : IDisposable
public class EventSource : IDisposable
type EventSource = class
    interface IDisposable
Public Class EventSource
Implements IDisposable
继承
EventSource
派生
实现

示例

下面的示例演示EventSource类的简单实现。The following example shows a simple implementation of the EventSource class.

using System.Diagnostics.Tracing;
using System.Collections.Generic;

namespace Demo1
{
    class MyCompanyEventSource : EventSource
    {
        public static MyCompanyEventSource Log = new MyCompanyEventSource();

        public void Startup() { WriteEvent(1); }
        public void OpenFileStart(string fileName) { WriteEvent(2, fileName); }
        public void OpenFileStop() { WriteEvent(3); }
    }

    class Program
    {
        static void Main(string[] args)
        {
            string name = MyCompanyEventSource.GetName(typeof(MyCompanyEventSource));
            IEnumerable<EventSource> eventSources = MyCompanyEventSource.GetSources();
            MyCompanyEventSource.Log.Startup();
            // ...
            MyCompanyEventSource.Log.OpenFileStart("SomeFile");
            // ...
            MyCompanyEventSource.Log.OpenFileStop();
        }
    }
}
Imports System.Diagnostics.Tracing

Class MyCompanyEventSource
    Inherits EventSource
    Public Shared Log As New MyCompanyEventSource()

    Public Sub Startup()
        WriteEvent(1)
    End Sub

    Public Sub OpenFileStart(ByVal fileName As String)
        WriteEvent(2, fileName)
    End Sub

    Public Sub OpenFileStop()
        WriteEvent(3)
    End Sub
End Class

Class Program

    Shared Sub Main(ByVal args() As String)
        MyCompanyEventSource.Log.Startup()
        ' ...
        MyCompanyEventSource.Log.OpenFileStart("SomeFile")
        ' ...
        MyCompanyEventSource.Log.OpenFileStop()

    End Sub
End Class

下面的示例演示了EventSource类的更复杂实现。The following example shows a more complex implementation of the EventSource class.

using System;
using System.Diagnostics.Tracing;

namespace Demo2
{
    enum MyColor { Red, Yellow, Blue };

    [EventSource(Name = "MyCompany")]
    class MyCompanyEventSource : EventSource
    {
        public class Keywords
        {
            public const EventKeywords Page = (EventKeywords)1;
            public const EventKeywords DataBase = (EventKeywords)2;
            public const EventKeywords Diagnostic = (EventKeywords)4;
            public const EventKeywords Perf = (EventKeywords)8;
        }

        public class Tasks
        {
            public const EventTask Page = (EventTask)1;
            public const EventTask DBQuery = (EventTask)2;
        }

        [Event(1, Message = "Application Failure: {0}", Level = EventLevel.Error, Keywords = Keywords.Diagnostic)]
        public void Failure(string message) { WriteEvent(1, message); }

        [Event(2, Message = "Starting up.", Keywords = Keywords.Perf, Level = EventLevel.Informational)]
        public void Startup() { WriteEvent(2); }

        [Event(3, Message = "loading page {1} activityID={0}", Opcode = EventOpcode.Start, 
            Task = Tasks.Page, Keywords = Keywords.Page, Level = EventLevel.Informational)]
        public void PageStart(int ID, string url) { if (IsEnabled()) WriteEvent(3, ID, url); }

        [Event(4, Opcode = EventOpcode.Stop, Task = Tasks.Page, Keywords = Keywords.Page, Level = EventLevel.Informational)]
        public void PageStop(int ID) { if (IsEnabled()) WriteEvent(4, ID); }

        [Event(5, Opcode = EventOpcode.Start, Task = Tasks.DBQuery, Keywords = Keywords.DataBase, Level = EventLevel.Informational)]
        public void DBQueryStart(string sqlQuery) { WriteEvent(5, sqlQuery); }

        [Event(6, Opcode = EventOpcode.Stop, Task = Tasks.DBQuery, Keywords = Keywords.DataBase, Level = EventLevel.Informational)]
        public void DBQueryStop() { WriteEvent(6); }

        [Event(7, Level = EventLevel.Verbose, Keywords = Keywords.DataBase)]
        public void Mark(int ID) { if (IsEnabled()) WriteEvent(7, ID); }

        [Event(8)]
        public void LogColor(MyColor color) { WriteEvent(8, (int) color); }

        public static MyCompanyEventSource Log = new MyCompanyEventSource();
    }

    class Program
    {
        static void Main(string[] args)
        {
            MyCompanyEventSource.Log.Startup();
            Console.WriteLine("Starting up");

            MyCompanyEventSource.Log.DBQueryStart("Select * from MYTable");
            var url = "http://localhost";
            for (int i = 0; i < 10; i++)
            {
                MyCompanyEventSource.Log.PageStart(i, url);
                MyCompanyEventSource.Log.Mark(i);
                MyCompanyEventSource.Log.PageStop(i);
            }
            MyCompanyEventSource.Log.DBQueryStop();
            MyCompanyEventSource.Log.LogColor(MyColor.Blue);

            MyCompanyEventSource.Log.Failure("This is a failure 1");
            MyCompanyEventSource.Log.Failure("This is a failure 2");
            MyCompanyEventSource.Log.Failure("This is a failure 3");
        }
    }
}
Imports System.Diagnostics.Tracing


Enum MyColor
    Red
    Yellow
    Blue
End Enum 'MyColor 
<EventSource(Name:="MyCompany")> _
Class MyCompanyEventSource
    Inherits EventSource

    Public Class Keywords
        Public Const Page As EventKeywords = CType(1, EventKeywords)
        Public Const DataBase As EventKeywords = CType(2, EventKeywords)
        Public Const Diagnostic As EventKeywords = CType(4, EventKeywords)
        Public Const Perf As EventKeywords = CType(8, EventKeywords)
    End Class

    Public Class Tasks
        Public Const Page As EventTask = CType(1, EventTask)
        Public Const DBQuery As EventTask = CType(1, EventTask)
    End Class

    <[Event](1, Message:="Application Failure: {0}", Level:=EventLevel.Error, Keywords:=Keywords.Diagnostic)> _
    Public Sub Failure(ByVal message As String)
        WriteEvent(1, message)
    End Sub

    <[Event](2, Message:="Starting up.", Keywords:=Keywords.Perf, Level:=EventLevel.Informational)> _
    Public Sub Startup()
        WriteEvent(2)
    End Sub

    <[Event](3, Message:="loading page {1} activityID={0}", Opcode:=EventOpcode.Start, Task:=Tasks.Page, Keywords:=Keywords.Page, Level:=EventLevel.Informational)> _
    Public Sub PageStart(ByVal ID As Integer, ByVal url As String)
        If IsEnabled() Then
            WriteEvent(3, ID, url)
        End If
    End Sub

    <[Event](4, Opcode:=EventOpcode.Stop, Task:=Tasks.Page, Keywords:=Keywords.Page, Level:=EventLevel.Informational)> _
    Public Sub PageStop(ByVal ID As Integer)
        If IsEnabled() Then
            WriteEvent(4, ID)
        End If
    End Sub

    <[Event](5, Opcode:=EventOpcode.Start, Task:=Tasks.DBQuery, Keywords:=Keywords.DataBase, Level:=EventLevel.Informational)> _
    Public Sub DBQueryStart(ByVal sqlQuery As String)
        WriteEvent(5, sqlQuery)
    End Sub

    <[Event](6, Opcode:=EventOpcode.Stop, Task:=Tasks.DBQuery, Keywords:=Keywords.DataBase, Level:=EventLevel.Informational)> _
    Public Sub DBQueryStop()
        WriteEvent(6)
    End Sub

    <[Event](7, Level:=EventLevel.Verbose, Keywords:=Keywords.DataBase)> _
    Public Sub Mark(ByVal ID As Integer)
        If IsEnabled() Then
            WriteEvent(7, ID)
        End If
    End Sub

    <[Event](8)> _
    Public Sub LogColor(ByVal color As MyColor)
        WriteEvent(8, Fix(color))
    End Sub
    Public Shared Log As New MyCompanyEventSource()
End Class


Class Program

    Shared Sub Main(ByVal args() As String)
        MyCompanyEventSource.Log.Startup()
        Console.WriteLine("Starting up")
        MyCompanyEventSource.Log.DBQueryStart("Select * from MYTable")
        Dim url As String = "http:'localhost"
        Dim i As Integer
        For i = 0 To 9
            MyCompanyEventSource.Log.PageStart(i, url)
            MyCompanyEventSource.Log.Mark(i)
            MyCompanyEventSource.Log.PageStop(i)
        Next i
        MyCompanyEventSource.Log.DBQueryStop()
        MyCompanyEventSource.Log.LogColor(MyColor.Blue)

        MyCompanyEventSource.Log.Failure("This is a failure 1")
        MyCompanyEventSource.Log.Failure("This is a failure 2")
        MyCompanyEventSource.Log.Failure("This is a failure 3")
    End Sub
End Class

注解

此类应由提供要用于 ETW 的特定事件的用户类进行继承。This class is intended to be inherited by a user class that provides specific events to be used for ETW. 调用EventSource.WriteEvent方法来记录事件。The EventSource.WriteEvent methods are called to log the events.

重要

此类型实现 IDisposable 接口。This type implements the IDisposable interface. 在使用完类型后,您应直接或间接释放类型。When you have finished using the type, you should dispose of it either directly or indirectly. 若要直接释放类型,请在 try/catch 块中调用其 Dispose 方法。To dispose of the type directly, call its Dispose method in a try/catch block. 若要间接释放类型,请使用 using(在 C# 中)或 Using(在 Visual Basic 中)等语言构造。To dispose of it indirectly, use a language construct such as using (in C#) or Using (in Visual Basic). 有关详细信息,请参阅 IDisposable 接口主题中的“使用实现 IDisposable 的对象”一节。For more information, see the "Using an Object that Implements IDisposable" section in the IDisposable interface topic.

的基本功能EventSource足以满足大多数应用程序的需求。The basic functionality of EventSource is sufficient for most applications. 如果要对创建的 ETW 清单进行更多的控制,可将EventAttribute属性应用于方法。If you want more control over the ETW manifest that is created, you can apply the EventAttribute attribute to the methods. 对于高级事件源应用程序,可以截获发送到派生事件源的命令并更改筛选,或使 inheritor 执行操作(如转储数据结构)。For advanced event source applications, it is possible to intercept the commands being sent to the derived event source and change the filtering, or to cause actions (such as dumping a data structure) to be performed by the inheritor. 事件源可以通过 Windows ETW 控制器(如 Logman 工具)立即激活。An event source can be activated with Windows ETW controllers, such as the Logman tool, immediately. 还可以通过编程方式控制和截获数据调度程序。It is also possible to programmatically control and intercept the data dispatcher. EventListener类提供附加功能。The EventListener class provides additional functionality.

从开始EventSource ,提供通道支持,某些事件源验证规则已被宽松。 .NET Framework 4.6.NET Framework 4.6Starting with .NET Framework 4.6.NET Framework 4.6, EventSource provides channel support and some of the event source validation rules have been relaxed. 这意味着:This means:

  • EventSource类型现在可以实现接口。EventSource types may now implement interfaces. 这样就可以在使用接口定义常见日志记录目标的高级日志记录系统中使用事件源类型。This enables the use of event source types in advanced logging systems that use interfaces to define a common logging target.

  • 引入了实用工具事件源类型的概念。The concept of a utility event source type has been introduced. 此功能可让你在项目中跨多个事件源类型共享代码,以实现WriteEvent优化的重载等方案。This feature enables sharing code across multiple event source types in a project to enable scenarios such as optimized WriteEvent overloads.

对于提供面向.NET Framework 4.5.1.NET Framework 4.5.1或更EventSource早版本的频道支持等功能的类版本,请参阅Microsoft EventSource Library 1.0.16For a version of the EventSource class that provides features such as channel support you are targeting .NET Framework 4.5.1.NET Framework 4.5.1 or earlier, see Microsoft EventSource Library 1.0.16.

构造函数

EventSource()

创建 EventSource 类的新实例。Creates a new instance of the EventSource class.

EventSource(Boolean)

创建 EventSource 类的新实例,并指定在 Windows 基础代码发生错误时是否引发异常。Creates a new instance of the EventSource class and specifies whether to throw an exception when an error occurs in the underlying Windows code.

EventSource(EventSourceSettings)

使用指定的配置设置创建 EventSource 类的新实例。Creates a new instance of the EventSource class with the specified configuration settings.

EventSource(EventSourceSettings, String[])

初始化 EventSource 的新实例,以用于其中包含指定设置和特性的非约定事件。Initializes a new instance of the EventSource to be used with non-contract events that contains the specified settings and traits.

EventSource(String)

使用指定的名称创建 EventSource 类的新实例。Creates a new instance of the EventSource class with the specified name.

EventSource(String, EventSourceSettings)

使用指定的名称和设置创建 EventSource 类的新实例。Creates a new instance of the EventSource class with the specified name and settings.

EventSource(String, EventSourceSettings, String[])

使用指定的配置设置创建 EventSource 类的新实例。Creates a new instance of the EventSource class with the specified configuration settings.

属性

ConstructionException

获取在事件源的构造过程中引发的任何异常。Gets any exception that was thrown during the construction of the event source.

CurrentThreadActivityId

获取当前线程的活动 ID。Gets the activity ID of the current thread.

Guid

此事件源的唯一标识符。The unique identifier for the event source.

Name

从事件源中派生出来的类的友好名称。The friendly name of the class that is derived from the event source.

Settings

获取应用于此事件源的设置。Gets the settings applied to this event source.

方法

Dispose()

释放 EventSource 类的当前实例所使用的所有资源。Releases all resources used by the current instance of the EventSource class.

Dispose(Boolean)

释放 EventSource 类使用的非托管资源,并可以选择释放托管资源。Releases the unmanaged resources used by the EventSource class and optionally releases the managed resources.

Equals(Object)

确定指定的对象是否等于当前对象。Determines whether the specified object is equal to the current object.

(继承自 Object)
Finalize()

允许 EventSource 对象在被垃圾回收之前尝试释放资源并执行其他清理操作。Allows the EventSource object to attempt to free resources and perform other cleanup operations before the object is reclaimed by garbage collection.

GenerateManifest(Type, String)

返回与当前事件源关联的 XML 清单的字符串。Returns a string of the XML manifest that is associated with the current event source.

GenerateManifest(Type, String, EventManifestOptions)

返回与当前事件源关联的 XML 清单的字符串。Returns a string of the XML manifest that is associated with the current event source.

GetGuid(Type)

获取事件源的实现的唯一标识符。Gets the unique identifier for this implementation of the event source.

GetHashCode()

用作默认哈希函数。Serves as the default hash function.

(继承自 Object)
GetName(Type)

获取事件源的好友名称。Gets the friendly name of the event source.

GetSources()

获取应用程序域的所有事件源的快照。Gets a snapshot of all the event sources for the application domain.

GetTrait(String)

获取与指定键关联的特性值。Gets the trait value associated with the specified key.

GetType()

获取当前实例的 TypeGets the Type of the current instance.

(继承自 Object)
IsEnabled()

确定是否已启用当前事件源。Determines whether the current event source is enabled.

IsEnabled(EventLevel, EventKeywords)

确定是否已启用具有指定级别和关键字的当前事件源。Determines whether the current event source that has the specified level and keyword is enabled.

IsEnabled(EventLevel, EventKeywords, EventChannel)

确定是否对带有指定级别、关键字和通道的事件启用了当前事件源。Determines whether the current event source is enabled for events with the specified level, keywords and channel.

MemberwiseClone()

创建当前 Object 的浅表副本。Creates a shallow copy of the current Object.

(继承自 Object)
OnEventCommand(EventCommandEventArgs)

当该控制器更新当前事件源时调用。Called when the current event source is updated by the controller.

SendCommand(EventSource, EventCommand, IDictionary<String,String>)

发送命令到指定的事件源。Sends a command to a specified event source.

SetCurrentThreadActivityId(Guid)

在当前线程上设置活动 ID。Sets the activity ID on the current thread.

SetCurrentThreadActivityId(Guid, Guid)

在当前线程上设置活动 ID 并返回以前的活动 ID。Sets the activity ID on the current thread, and returns the previous activity ID.

ToString()

获得当前事件源实例的字符串表示形式。Obtains a string representation of the current event source instance.

Write(String)

使用指定的名称和默认选项而非字段来写入事件。Writes an event without fields, but with the specified name and default options.

Write(String, EventSourceOptions)

使用指定的名称和选项而非字段来写入事件。Writes an event without fields, but with the specified name and options.

Write<T>(String, EventSourceOptions, Guid, Guid, T)

使用指定的名称、选项、相关活动和事件数据写入事件。Writes an event with the specified name, options, related activity and event data.

Write<T>(String, EventSourceOptions, T)

使用指定的名称、事件数据和选项写入事件。Writes an event with the specified name, event data and options.

Write<T>(String, EventSourceOptions, T)

使用指定的名称、选项和事件数据写入事件。Writes an event with the specified name, options and event data.

Write<T>(String, T)

使用指定的名称和数据写入事件。Writes an event with the specified name and data.

WriteEvent(Int32)

通过使用提供的事件标识符写入事件。Writes an event by using the provided event identifier.

WriteEvent(Int32, Byte[])

通过使用提供的事件标识符和字节数组自变量写入事件。Writes an event by using the provided event identifier and byte array argument.

WriteEvent(Int32, Int32)

通过使用提供的事件标识符和 32 位整数自变量写入事件。Writes an event by using the provided event identifier and 32-bit integer argument.

WriteEvent(Int32, Int32, Int32)

通过使用提供的事件标识符和 32 位整数自变量写入事件。Writes an event by using the provided event identifier and 32-bit integer arguments.

WriteEvent(Int32, Int32, Int32, Int32)

通过使用提供的事件标识符和 32 位整数自变量写入事件。Writes an event by using the provided event identifier and 32-bit integer arguments.

WriteEvent(Int32, Int32, String)

使用提供的事件标识符、32 位整数和字符串参数写入事件。Writes an event by using the provided event identifier and 32-bit integer and string arguments.

WriteEvent(Int32, Int64)

通过使用提供的事件标识符和 64 位整数参数写入事件。Writes an event by using the provided event identifier and 64-bit integer argument.

WriteEvent(Int32, Int64, Byte[])

使用指定的标识符、64 位整数和字节数组参数写入事件数据。Writes the event data using the specified identifier and 64-bit integer and byte array arguments.

WriteEvent(Int32, Int64, Int64)

通过使用提供的事件标识符和 64 位自变量写入事件。Writes an event by using the provided event identifier and 64-bit arguments.

WriteEvent(Int32, Int64, Int64, Int64)

通过使用提供的事件标识符和 64 位自变量写入事件。Writes an event by using the provided event identifier and 64-bit arguments.

WriteEvent(Int32, Int64, String)

使用提供的事件标识符、64 位整数和字符串参数写入事件。Writes an event by using the provided event identifier and 64-bit integer, and string arguments.

WriteEvent(Int32, Object[])

通过使用提供的事件标识符和参数数组写入事件。Writes an event by using the provided event identifier and array of arguments.

WriteEvent(Int32, String)

通过使用提供的事件标识符和字符串自变量写入事件。Writes an event by using the provided event identifier and string argument.

WriteEvent(Int32, String, Int32)

通过使用提供的事件标识符和自变量写入事件。Writes an event by using the provided event identifier and arguments.

WriteEvent(Int32, String, Int32, Int32)

通过使用提供的事件标识符和自变量写入事件。Writes an event by using the provided event identifier and arguments.

WriteEvent(Int32, String, Int64)

通过使用提供的事件标识符和自变量写入事件。Writes an event by using the provided event identifier and arguments.

WriteEvent(Int32, String, String)

通过使用提供的事件标识符和字符串自变量写入事件。Writes an event by using the provided event identifier and string arguments.

WriteEvent(Int32, String, String, String)

通过使用提供的事件标识符和字符串自变量写入事件。Writes an event by using the provided event identifier and string arguments.

WriteEventCore(Int32, Int32, EventSource+EventData*)

通过使用提供的事件标识符和事件数据,创建新的 WriteEvent 重载。Creates a new WriteEvent overload by using the provided event identifier and event data.

WriteEventWithRelatedActivityId(Int32, Guid, Object[])

写入一个指示当前活动与其他活动相关的事件。Writes an event that indicates that the current activity is related to another activity.

WriteEventWithRelatedActivityIdCore(Int32, Guid*, Int32, EventSource+EventData*)

写入一个指示当前活动与其他活动相关的事件。Writes an event that indicates that the current activity is related to another activity.

事件

EventCommandExecuted

当命令来自事件侦听器时出现。Occurs when a command comes from an event listener.

适用于

线程安全性

此类型是线程安全的。This type is thread safe.