Enhanced EventLog writing for .NET Applications

• Download source files - 65 Kb

Introduction

The EventLog class provided with the .NET framework allows easy access to the NT event log subsystem but has some implementation "features" that restrict it's usefulness (in fact, it is probably best described as a leaky abstraction).

A good description of the issues (summarised below) is in section 2.5.1 of "Developing Applications with VisualStudio .NET" by Richard Grimes (ISBN 0-201-70852-3).

The EventLogEx class presented here works around these issues and enables applications to write to the event log in a manner similar to the current direct API calls (For reading, the existing framework class works fine).

Whilst the code is fairly generic, it was created to support a project I am working on and, as such, it may have some design features that seem strange or just plain wrong in the "real world" -- please feel free pull the code apart and let me know of any issues/comments/solutions!

Also included is a simple C# command-line utility that can be used to convert the .h file created by the Microsoft Message Compiler (MC) into a C# class (see The MCConvert Utility) that can be included into solutions using this code.

Event logging pre-.NET

Writing to the log

When you access the event log using the standard NT API calls, the system stores a structure that contains (amongst other things) the message ID and any replacement strings ("inserts") for the message -- but it does not store the message text itself.

Reading from the log

When you read an entry from an event log, the system reads the stored message ID and replacement strings, gets the text of the message for the current locale from a MESSAGETABLE resource contained within the file specified in the EventMessageFile key in the registry, inserts the replacement strings, and returns you the formatted string.

As well as keeping the log file small (which improves performance when accessing the event log on a remote machine), just storing the message ID and replacement strings also means that the same message can be viewed in different languages as long as the client:

• Has the file installed that contains that locales MESSAGETABLE
• The local registry has been configured to tell NT where to find it

The file containing the messages only has to be installed on the machine that is doing the reading and does not have to exist on the one that is doing the writing or the one that holds the log (they can all be different machines).

Event logging with .NET

Under .NET, message sources are registered with the EventMessageFile value always set to EventLogMessages.dll, which is installed in the GAC. This file has 65,535 entries, each of which contain a single string: %1

In other words, for every possible event ID the entire format string is a placeholder that takes a single replacement string -- which is always the message that you pass to EventLog.WriteEntry()

The main drawbacks with this approach are:

• You have the responsibility of choosing the locale that should be used to format the message before writing it to the log and so all clients have to view the message in the same language
• The log file is larger than necessary as it has to hold the full formatted string rather than just the message ID and replacement strings
• If you want to view the entries written to a remote log on that machine, it must have the .NET runtime installed and the EventLogMessages.dll file registered in the remote computer's GAC.

Event logging with EventLogEx

The EventLogEx class overcomes these issues and allows you to log messages from managed code with read-time formatting of the messages based on the client locale (i.e. it exposes the native API calls as a managed class).

Class Overview

For full API information, please refer to the NDoc generated documentation included in the .ZIP file (EventLogEx.chm)

The EventLogEx class

The event-logging service uses the information stored in the EventLog registry key (HKLM\System\CurrentControlSet\Services\EventLog)

The EventLog subkeys are called logfiles and are used to locate resources that the event logging service needs when an application writes to or reads from an event log. The default logfiles are Application, Security, and System and you can also create custom logfiles.

Each subkey has configuration values specific to that logfile which can be read or set using the relevant EventLogEx properties.

The EventSource class

Each logfile entry contains one or more subkeys called event sources which are the names of the software components that log events to that logfile (normally this is the name of the application or the name of a subcomponent of the application, if the application is large).

Event sources are stored under the HKLM\System\CurrentControlSet\Services\EventLog\LogName\AppName key and contain information specific to the software that will be logging the events, and which can be read or written using the relevant EventSource properties.

NOTE: You cannot construct an instance of the EventSource class directly - instead use the Source property of an existing instance of the EventLogEx class.

The MessageFile properties

The EventSource object exposes the *MessageFile properties in two versions -- Local and Remote (e.g. LocalEventMessageFile and RemoteEventMessageFile).

This is necessary because, to be able to view the text of events stored in a log on a remote machine, the local registry must have an event source entry that specifies the location of file that contains the MESSAGETABLE resources.

The remote machine must also have a similar one if the event is being written to a custom log file, otherwise the NT event service defaults to writing the messages to the Application log (if it is being written to the Application log the entry is optional but recommended).

The remote entry will also allow the events to be viewed in its Event Viewer if it also has the MESSAGETABLE resource files installed -- but these are likely to be in a different directory than on the local machine and so the

Remote*

properties allow you to provide different paths for the local and remote paths (if the source is local, calling the Remote* versions has no effect).

Using the code

The EventLogEx class should be used as a replacement for the standard EventLog only when writing events - when reading events, the existing EventLog class should be used.

The main difference with the class is that, instead of using the WriteEntry() method and passing it a string message, you use ReportEvent() and pass it a message ID.

//
// Open a source on the local machine and then associate 
// it with a custom log called "MyCustomLog"
//
EventLogEx log = new EventLogEx( 
    "MyCustomLog", ".", "EventLogExTest" );

// Write a test message with some extra data
byte[] errorInfo = Encoding.ASCII.GetBytes( 
    new string("Some useful additional data") );

log.ReportEvent( EventLogEntryType.Warning, 0,
    (uint )EventLogExTestMessages.MSG_WITH_THREE_PARAM,
    new string[] { "The data", "below is", "the error" }, 
    errorInfo );

Points of Interest

.NET Registry issue

According to the documentation, any registered paths (e.g. to the log file and message files) should be of type REG_SZ_EXPAND but you cannot create an entry of this type using the standard .NET Registry classes (you can only create REG_SZ or REG_MULTI_SZ types).

This most notably affects the path to the actual log file as it should be under the system directory which, on a remote machine, may not be the same as the local one (so you can't use just use the Environment.SystemDirectory value).

Using "%SystemRoot%" in the path without setting the type to REG_SZ_EXPAND does not work correctly as it will not be resolved when read.

The solution that I have used is to read the "SystemRoot" value from the (possibly remote) registry and then use that to build the path up.

The MCConvert Utility

VisualStudio.NET does not contain an editor for MESSAGETABLE resources (although I am working on one) so you currently need to create the message files in the same way as pre-.NET (i.e. using the Microsoft message compiler mc.exe).

You can create one message file that contains descriptions for the event identifiers, categories, and parameters, or create three separate message files and several applications can share the same message file.

You should typically create message files as resource-only DLLs as they are smaller and faster to load than ordinary DLLs:

1. Create an .MC file to define the message resource table (See MSDN for more information)
2. Use the message compiler to create the .RC and .BIN files from the .MC file:

   mc filename.mc
   

3. Use the resource compiler to create the .RES file:

   rc -r -fo filename.res
       filename.rc

4. Use the linker to create the .DLL file:

   link -dll -noentry -out:filename.dll
       filename.res

To simplify the use of the MC generated .h file from within C# projects, a message converter tool is included in the .zip file. This can be used to convert the .h file into a C# file that contains a single public class called MessageIds that contains the message IDs as a set of public const uint values.

This utility is simple to use: mcconvert filename.h

This will generate a file called filenameMessages.cs that consists of a namespace called filenameMessages which contains a single MessageIds class, which in turn exposes the

public 
const uint

message IDs which are named the same as the #define entries in .h file and also the message text.

This file can then be included in an existing solution and the IDs used in the calls to the ReportEvent method of the EventLogEx class.

Note: The messages IDs are declared as public const uint values rather than a (to some people) more natural enumeration so that they can be passed directly to the ReportEvent method without the need to add a (uint) cast each time (and ReportEvent can't be easily modified to take an enumeration as it will have a different type for each .h file).

The EventLogExTest Program

The .zip file includes a simple test program for the EventLogEx class.

To build it, you should first run the "BuildMcDll.cmd" batch file in the EventLogExTest subdirectory which generates the .h/.cs files used by the program and also compiles the Test.Messages.dll file and copies it to the bin\debug directory so that the test application can locate it.

History

• November 12, 2002 - Initial posting