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. 這可讓您在使用介面來定義一般記錄目標的 advanced 記錄系統中使用事件來源類型。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.

如需提供功能的EventSource類別版本,例如您的目標.NET Framework 4.5.1.NET Framework 4.5.1或更早版本的通道支援,請參閱Microsoft EventSource 程式庫 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

取得目前執行緒的活動識別碼。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 類別所使用的 Unmanaged 資源,並選擇性地釋放 Managed 資源。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 的淺層複本 (Shallow Copy)。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)

設定目前執行緒的活動識別碼。Sets the activity ID on the current thread.

SetCurrentThreadActivityId(Guid, Guid)

設定目前執行緒的活動識別碼,並傳回上一個活動識別碼。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.