.NET 1.1+

Tracing to Event Logs

by Richard Carr, published at http://www.blackwasp.co.uk/EventLogTraceListener.aspx

Using tracing within an application allows its activities to be logged and reviewed later to assist with identifying and resolving bugs. Messages can be sent to various locations, including Windows event logs that can be examined using the Event Viewer.

EventLogTraceListener

When you are developing applications it is useful to include logging functionality. If you encounter bugs, or when test users report issues, the logs can be reviewed and may help you to track down those problems. A simple way of providing logging is via the Debug and Trace classes. These classes allow you to output messages to trace listeners, which control how those messages are outputted. For example, information can easily be sent to the Visual Studio output window or to a text file.

In this article I will describe the use of the EventLogTraceListener class. As the name suggests, this is a trace listener that sends messages to the Windows event logs. These logs can be viewed using the Event Viewer tool that is provided with all versions of Microsoft Windows.

Constructors

When you instantiate an EventLogTraceListener you need to link it to an existing event source. You should register an event source for your application before you log messages to event logs, rather than using existing event sources. This makes it easier to filter the logs in order to find messages that relate to your software. In the sample code we will work with an event source named, "My Sample Event Source".

The class includes three constructors. The first accepts an EventLog object via its single parameter. This is useful if you have already instantiated an EventLog that is linked to your event source. You can see it used in the sample code below:

EventLog log = new EventLog();
log.Log = "Application";
log.Source = "My Sample Event Source";

EventLogTraceListener listener = new EventLogTraceListener(log);

If you do not have an EventLog instance you can create a new trace listener using the event source name, provided as a string argument.

EventLogTraceListener listener = new EventLogTraceListener("My Sample Event Source");

Finally, you can use the default constructor. This initialises a new EventLogTraceListener that is not yet linked to an event log. If you use this option, you must set the event log using the EventLog property before you can log messages.

EventLog log = new EventLog();
log.Log = "Application";
log.Source = "My Sample Event Source";

EventLogTraceListener listener = new EventLogTraceListener();
listener.EventLog = log;

Setting up the Trace Listener

Event log trace listeners are registered with the Debug or Trace classes in the same manner as other trace listeners; you simply add them to the static Listeners collection with the Add method. Below we register the new listener for tracing:

Trace.Listeners.Add(listener);

Logging Messages

Some of the functionality of tracing is ignored or limited when writing messages to events log due to their limitations. When storing information in text files you can indent information using the Indent and Unindent methods. These are ignored as indentation is meaningless in an event log. Also, where you might use the Write method to output part of a message to a log file and add to the same line with further Writes, for an EventLogTraceListener these calls generate separate log entries.

The following line of code sends writes a message to the active trace listeners. This includes the listener we registered so creates an event log entry.

Trace.WriteLine("Hello, world!");

The resultant log entry appears as shown below. The image is from a Windows 7 event log. Other versions of the operating system have slightly different event viewers so the screen layout may vary.