EventSource Class

.NET Framework (current version)
 

Provides the ability to create events for event tracing for Windows (ETW).

Namespace:   System.Diagnostics.Tracing
Assembly:  mscorlib (in mscorlib.dll)

System.Object
  System.Diagnostics.Tracing.EventSource

Public Class EventSource
	Implements IDisposable

NameDescription
System_CAPS_protmethodEventSource()

Creates a new instance of the EventSource class.

System_CAPS_protmethodEventSource(Boolean)

Creates a new instance of the EventSource class and specifies whether to throw an exception when an error occurs in the underlying Windows code.

System_CAPS_protmethodEventSource(EventSourceSettings)

Creates a new instance of the EventSource class with the specified configuration settings.

System_CAPS_protmethodEventSource(EventSourceSettings, String())

Initializes a new instance of the EventSource to be used with non-contract events that contains the specified settings and traits.

System_CAPS_pubmethodEventSource(String)

Creates a new instance of the EventSource class with the specified name.

System_CAPS_pubmethodEventSource(String, EventSourceSettings)

Creates a new instance of the EventSource class with the specified name and settings.

System_CAPS_pubmethodEventSource(String, EventSourceSettings, String())

Creates a new instance of the EventSource class with the specified configuration settings.

NameDescription
System_CAPS_pubpropertyConstructionException

[Supported in the .NET Framework 4.5.1 and later versions]

Gets any exception that was thrown during the construction of the event source.

System_CAPS_pubpropertySystem_CAPS_staticCurrentThreadActivityId

[Supported in the .NET Framework 4.5.1 and later versions]

Gets the activity ID of the current thread.

System_CAPS_pubpropertyGuid

The unique identifier for the event source.

System_CAPS_pubpropertyName

The friendly name of the class that is derived from the event source.

System_CAPS_pubpropertySettings

Gets the settings applied to this event source.

NameDescription
System_CAPS_pubmethodDispose()

Releases all resources used by the current instance of the EventSource class.

System_CAPS_protmethodDispose(Boolean)

Releases the unmanaged resources used by the EventSource class and optionally releases the managed resources.

System_CAPS_pubmethodEquals(Object)

Determines whether the specified object is equal to the current object.(Inherited from Object.)

System_CAPS_protmethodFinalize()

Allows the EventSource object to attempt to free resources and perform other cleanup operations before the object is reclaimed by garbage collection.(Overrides Object.Finalize().)

System_CAPS_pubmethodSystem_CAPS_staticGenerateManifest(Type, String)

Returns a string of the XML manifest that is associated with the current event source.

System_CAPS_pubmethodSystem_CAPS_staticGenerateManifest(Type, String, EventManifestOptions)

Returns a string of the XML manifest that is associated with the current event source.

System_CAPS_pubmethodSystem_CAPS_staticGetGuid(Type)

Gets the unique identifier for this implementation of the event source.

System_CAPS_pubmethodGetHashCode()

Serves as the default hash function. (Inherited from Object.)

System_CAPS_pubmethodSystem_CAPS_staticGetName(Type)

Gets the friendly name of the event source.

System_CAPS_pubmethodSystem_CAPS_staticGetSources()

Gets a snapshot of all the event sources for the application domain.

System_CAPS_pubmethodGetTrait(String)

Gets the trait value associated with the specified key.

System_CAPS_pubmethodGetType()

Gets the Type of the current instance.(Inherited from Object.)

System_CAPS_pubmethodIsEnabled()

Determines whether the current event source is enabled.

System_CAPS_pubmethodIsEnabled(EventLevel, EventKeywords)

Determines whether the current event source that has the specified level and keyword is enabled.

System_CAPS_pubmethodIsEnabled(EventLevel, EventKeywords, EventChannel)

Determines whether the current event source is enabled for events with the specified level, keywords and channel.

System_CAPS_protmethodMemberwiseClone()

Creates a shallow copy of the current Object.(Inherited from Object.)

System_CAPS_protmethodOnEventCommand(EventCommandEventArgs)

Called when the current event source is updated by the controller.

System_CAPS_pubmethodSystem_CAPS_staticSendCommand(EventSource, EventCommand, IDictionary(Of String, String))

Sends a command to a specified event source.

System_CAPS_pubmethodSystem_CAPS_staticSetCurrentThreadActivityId(Guid)

[Supported in the .NET Framework 4.5.1 and later versions]

Sets the activity ID on the current thread.

System_CAPS_pubmethodSystem_CAPS_staticSetCurrentThreadActivityId(Guid, Guid)

[Supported in the .NET Framework 4.5.1 and later versions]

Sets the activity ID on the current thread, and returns the previous activity ID.

System_CAPS_pubmethodToString()

Obtains a string representation of the current event source instance.(Overrides Object.ToString().)

System_CAPS_pubmethodWrite(String)

Writes an event without fields, but with the specified name and default options.

System_CAPS_pubmethodWrite(String, EventSourceOptions)

Writes an event without fields, but with the specified name and options.

System_CAPS_pubmethodWrite(Of T)(String, T)

Writes an event with the specified name and data.

System_CAPS_pubmethodWrite(Of T)(String, EventSourceOptions, T)

Writes an event with the specified name, event data and options.

System_CAPS_pubmethodWrite(Of T)(String, EventSourceOptions, T)

Writes an event with the specified name, options and event data.

System_CAPS_pubmethodWrite(Of T)(String, EventSourceOptions, Guid, Guid, T)

Writes an event with the specified name, options, related activity and event data.

System_CAPS_protmethodWriteEvent(Int32)

Writes an event by using the provided event identifier.

System_CAPS_protmethodWriteEvent(Int32, Byte())

Writes an event by using the provided event identifier and byte array argument.

System_CAPS_protmethodWriteEvent(Int32, Int32)

Writes an event by using the provided event identifier and 32-bit integer argument.

System_CAPS_protmethodWriteEvent(Int32, Int32, Int32)

Writes an event by using the provided event identifier and 32-bit integer arguments.

System_CAPS_protmethodWriteEvent(Int32, Int32, Int32, Int32)

Writes an event by using the provided event identifier and 32-bit integer arguments.

System_CAPS_protmethodWriteEvent(Int32, Int32, String)

Writes an event by using the provided event identifier and 32-bit integer and string arguments.

System_CAPS_protmethodWriteEvent(Int32, Int64)

Writes an event by using the provided event identifier and 64-bit integer argument.

System_CAPS_protmethodWriteEvent(Int32, Int64, Byte())

Writes the event data using the specified indentifier and 64-bit integer and byte array arguments.

System_CAPS_protmethodWriteEvent(Int32, Int64, Int64)

Writes an event by using the provided event identifier and 64-bit arguments.

System_CAPS_protmethodWriteEvent(Int32, Int64, Int64, Int64)

Writes an event by using the provided event identifier and 64-bit arguments.

System_CAPS_protmethodWriteEvent(Int32, Int64, String)

Writes an event by using the provided event identifier and 64-bit integer, and string arguments.

System_CAPS_protmethodWriteEvent(Int32, Object())

Writes an event by using the provided event identifier and array of arguments.

System_CAPS_protmethodWriteEvent(Int32, String)

Writes an event by using the provided event identifier and string argument.

System_CAPS_protmethodWriteEvent(Int32, String, Int32)

Writes an event by using the provided event identifier and arguments.

System_CAPS_protmethodWriteEvent(Int32, String, Int32, Int32)

Writes an event by using the provided event identifier and arguments.

System_CAPS_protmethodWriteEvent(Int32, String, Int64)

Writes an event by using the provided event identifier and arguments.

System_CAPS_protmethodWriteEvent(Int32, String, String)

Writes an event by using the provided event identifier and string arguments.

System_CAPS_protmethodWriteEvent(Int32, String, String, String)

Writes an event by using the provided event identifier and string arguments.

System_CAPS_protmethodWriteEventCore(Int32, Int32, EventSource.EventData*)

Creates a new WriteEvent overload by using the provided event identifier and event data.

System_CAPS_protmethodWriteEventWithRelatedActivityId(Int32, Guid, Object())

[Supported in the .NET Framework 4.5.1 and later versions]

Writes an event that indicates that the current activity is related to another activity.

System_CAPS_protmethodWriteEventWithRelatedActivityIdCore(Int32, Guid*, Int32, EventSource.EventData*)

[Supported in the .NET Framework 4.5.1 and later versions]

Writes an event that indicates that the current activity is related to another activity.

NameDescription
System_CAPS_pubeventEventCommandExecuted

Occurs when a command comes from an event listener.

This class is intended to be inherited by a user class that provides specific events to be used for ETW. The EventSource.WriteEvent methods are called to log the events.

System_CAPS_importantImportant

This type implements the IDisposable interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its Dispose method in a try/catch block. To dispose of it indirectly, use a language construct such as using (in C#) or Using (in Visual Basic). For more information, see the “Using an Object that Implements IDisposable” section in the IDisposable interface topic.

The basic functionality of EventSource is sufficient for most applications. If you want more control over the ETW manifest that is created, you can apply the EventAttribute attribute to the methods. 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. 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. The EventListener class provides additional functionality.

Starting with .NET Framework 4.6, EventSource provides channel support and some of the event source validation rules have been relaxed. This means:

  • 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. This feature enables sharing code across multiple event source types in a project to enable scenarios such as optimized WriteEvent overloads.

For a version of the EventSource class that provides features such as channel support you are targeting .NET Framework 4.5.1 or earlier, see Microsoft EventSource Library 1.0.16.

The following example shows a simple implementation of the EventSource class.

Imports System.Diagnostics.Tracing

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

    Public Sub Startup()
        WriteEvent(1)
    End Sub 'Startup

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

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

Class Program

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

    End Sub 'Main
End Class 'Program

The following example shows a more complex implementation of the EventSource class.

Imports System
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 'Keywords

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

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

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

    <[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 'PageStart

    <[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 'PageStop

    <[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 'DBQueryStart

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

    <[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 'Mark

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


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 'Main
End Class 'Program

Universal Windows Platform
Available since 8
.NET Framework
Available since 4.5
Portable Class Library
Supported in: portable .NET platforms
Windows Phone
Available since 8.1

This type is thread safe.

Return to top
Show: