2 out of 8 rated this helpful - Rate this topic

EventSource Class

.NET Framework 4.5

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

System.Object
  System.Diagnostics.Tracing.EventSource

Namespace:  System.Diagnostics.Tracing
Assembly:  mscorlib (in mscorlib.dll)
public class EventSource : IDisposable

The EventSource type exposes the following members.

  NameDescription
Protected methodSupported in .NET for Windows Store appsEventSource()Creates a new instance of the EventSource class.
Protected methodSupported in .NET for Windows Store appsEventSource(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.
Top
  NameDescription
Public propertyConstructionException[Supported in the .NET Framework 4.5.1 and later versions] Gets any exception that was thrown during the construction of the event source.
Public propertyStatic memberCurrentThreadActivityId[Supported in the .NET Framework 4.5.1 and later versions] Gets the activity ID of the current thread.
Public propertySupported in .NET for Windows Store appsGuidThe unique identifier for the event source.
Public propertySupported in .NET for Windows Store appsNameThe friendly name of the class that is derived from the event source.
Top
  NameDescription
Public methodSupported in .NET for Windows Store appsDispose()Releases all resources used by the current instance of the EventSource class.
Protected methodSupported in .NET for Windows Store appsDispose(Boolean)Releases the unmanaged resources used by the EventSource class and optionally releases the managed resources.
Public methodSupported in .NET for Windows Store appsEquals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Protected methodSupported in .NET for Windows Store appsFinalizeAllows the EventSource object to attempt to free resources and perform other cleanup operations before the object is reclaimed by garbage collection. (Overrides Object.Finalize().)
Public methodStatic memberSupported in .NET for Windows Store appsGenerateManifestReturns a string of the XML manifest that is associated with the current event source.
Public methodStatic memberSupported in .NET for Windows Store appsGetGuidGets the unique identifier for this implementation of the event source.
Public methodSupported in .NET for Windows Store appsGetHashCodeServes as the default hash function. (Inherited from Object.)
Public methodStatic memberSupported in .NET for Windows Store appsGetNameGets the friendly name of the event source.
Public methodStatic memberSupported in .NET for Windows Store appsGetSourcesGets a snapshot of all the event sources for the application domain.
Public methodSupported in .NET for Windows Store appsGetTypeGets the Type of the current instance. (Inherited from Object.)
Public methodSupported in .NET for Windows Store appsIsEnabled()Determines whether the current event source is enabled.
Public methodSupported in .NET for Windows Store appsIsEnabled(EventLevel, EventKeywords)Determines whether the current event source that has the specified level and keyword is enabled.
Protected methodSupported in .NET for Windows Store appsMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Protected methodSupported in .NET for Windows Store appsOnEventCommandCalled when the current event source is updated by the controller.
Public methodStatic memberSupported in .NET for Windows Store appsSendCommandSends a command to a specified event source.
Public methodStatic memberSetCurrentThreadActivityId(Guid)[Supported in the .NET Framework 4.5.1 and later versions] Sets the activity ID on the current thread.
Public methodStatic memberSetCurrentThreadActivityId(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.
Public methodSupported in .NET for Windows Store appsToStringObtains a string representation of the current event source instance. (Overrides Object.ToString().)
Protected methodSupported in .NET for Windows Store appsWriteEvent(Int32)Writes an event by using the provided event identifier.
Protected methodSupported in .NET for Windows Store appsWriteEvent(Int32, Int32)Writes an event by using the provided event identifier and 32-bit integer argument.
Protected methodSupported in .NET for Windows Store appsWriteEvent(Int32, Int64)Writes an event by using the provided event identifier and 64-bit integer argument.
Protected methodSupported in .NET for Windows Store appsWriteEvent(Int32, Object[])Writes an event by using the provided event identifier and array of arguments.
Protected methodSupported in .NET for Windows Store appsWriteEvent(Int32, String)Writes an event by using the provided event identifier and string argument.
Protected methodSupported in .NET for Windows Store appsWriteEvent(Int32, Int32, Int32)Writes an event by using the provided event identifier and 32-bit integer arguments.
Protected methodSupported in .NET for Windows Store appsWriteEvent(Int32, Int64, Int64)Writes an event by using the provided event identifier and 64-bit arguments.
Protected methodSupported in .NET for Windows Store appsWriteEvent(Int32, String, Int32)Writes an event by using the provided event identifier and arguments.
Protected methodSupported in .NET for Windows Store appsWriteEvent(Int32, String, Int64)Writes an event by using the provided event identifier and arguments.
Protected methodSupported in .NET for Windows Store appsWriteEvent(Int32, String, String)Writes an event by using the provided event identifier and string arguments.
Protected methodSupported in .NET for Windows Store appsWriteEvent(Int32, Int32, Int32, Int32)Writes an event by using the provided event identifier and 32-bit integer arguments.
Protected methodSupported in .NET for Windows Store appsWriteEvent(Int32, Int64, Int64, Int64)Writes an event by using the provided event identifier and 64-bit arguments.
Protected methodSupported in .NET for Windows Store appsWriteEvent(Int32, String, Int32, Int32)Writes an event by using the provided event identifier and arguments.
Protected methodSupported in .NET for Windows Store appsWriteEvent(Int32, String, String, String)Writes an event by using the provided event identifier and string arguments.
Protected methodSupported in .NET for Windows Store appsWriteEventCoreCreates a new WriteEvent overload by using the provided event identifier and event data.
Protected methodWriteEventWithRelatedActivityId[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.
Protected methodWriteEventWithRelatedActivityIdCore[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.
Top

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.

Important noteImportant

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.

Caution noteCaution

There is a NuGet version of the EventSource class that provides more features. For more information, see Microsoft EventSource Library 1.0.16.

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();
        }
    }
}

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");
        }
    }
}

.NET Framework

Supported in: 4.5.1, 4.5

.NET for Windows Store apps

Supported in: Windows 8

.NET for Windows Phone apps

Supported in: Windows Phone 8.1

Windows Phone 8.1, Windows Phone 8, Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.