.NET 1.1+

Logging Messages in Event Logs

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

Microsoft Windows provides a built-in event logging system where informational messages, warnings, errors and audit details can be stored and viewed with the Event Viewer utility. This system is ideal for logging messages generated by a .NET application.

Logging Events

In the remainder of this article we will demonstrate some of the methods available for logging events in an event log. If you wish to follow the examples, create a new console application and use the Main method to try the sample code. As the classes used in the examples are within the System.Diagnostics namespace, you should add the following line at the top of the class containing the Main method:

using System.Diagnostics;

Registering an Event Source

As we have seen, when an event is logged it is associated with an event source. The source appears in the list of events in a log, making it easier to filter and sort events based upon their source. For a source to be used correctly, it must first be registered with the operating system and associated with a specific event log. This is achieved using the CreateEventSource method of the EventLog class. This static method requires two parameters that specify the names of the event source and the associated log respectively.

We can create a sample event source named "My Sample Event Source" and link it to the Application log by adding the following commands to the Main method:

string eventSource = "My Sample Event Source";
EventLog.CreateEventSource(eventSource, "Application");

If you execute the program in its current form, the event source will be created. However, if you run the program a second time you will receive an ArgumentException. This exception occurs because you may not create the same event source twice. Luckily, you can check for the existence of an event log before trying to create it to avoid this error. To do so, you use the SourceExists method, passing the name of the event source to check for.

Change the contents of the Main method to that shown below to avoid the exception:

string eventSource = "My Sample Event Source";

if (!EventLog.SourceExists(eventSource))
    EventLog.CreateEventSource(eventSource, "Application");

Security Concerns

If you executed the above code using Microsoft Vista or a newer operating system, you are likely to have seen an exception similar to the following:

The source was not found, but some or all event logs could not be searched.
Inaccessible logs: Security.

This problem occurs due to new code access security restrictions introduced in Microsoft Vista. To prevent unauthorised code from viewing or making changes to the operating system configuration, the SourceExists and CreateEventSource methods cannot be executed by a standard user. In order to try the samples, you must compile the code and run it by right-clicking the resultant executable file and selecting "Run as administrator".

In a production environment this causes the problem of ensuring the availability of an event log source before trying to log messages. Unless you can guarantee that your application will only run on platforms without this security restriction, you should not create event log sources from within the main program. You should certainly not require that your program has administrative privileges as this raises other serious security concerns.

If your program is for a limited audience and you will be manually configuring the software, you should create a second program that simply creates the required event sources. This program can be executed once using the "Run as administrator" option. Once the event sources have been generated, the main application can be executed without administrative rights.

If you are distributing your application using a setup package and have no control over the target machine, you should add a custom action to your installation routine. As setup packages generally require administrative privileges to complete successfully, your custom action can use the EventLog methods described above to create the event source during installation. The main application can then use the event source without being executed by an administrator.

Logging an Event

Now that we have an event source to work with, we can log an event. To do so you use the WriteEntry method of the EventLog class. This method includes ten overloaded variations including static implementations and versions that require an object instance. In this article we will use two of the static overloads. The first requires two string parameters specifying the event source and the message to store.

Add the following code to the end of the Main method and execute it:

EventLog.WriteEntry(eventSource, "This is my first event!");

To view the results, open the Event Viewer program or, if it is already open, refresh the Application log. You should see a new entry in the list with a source of "My Sample Event Source". Double-click the message to see the contents.

When using this simple method signature, the type of the logged message is always "Information". If you wish to change the type to one of the other four options, you can add a third parameter to the WriteEntry method. This parameter accepts a value of the EventLogEntryType enumeration, which has a constant value to represent each of the five available message types.

Remove the previous WriteEntry line from the Main method and replace it with the following code. Execute the program to see message of other types in the application log.

EventLog.WriteEntry(eventSource, "Information!", EventLogEntryType.Information);
EventLog.WriteEntry(eventSource, "Warning!", EventLogEntryType.Warning);
EventLog.WriteEntry(eventSource, "Error!", EventLogEntryType.Error);