Managed C++: Working with Windows Event Logs, Page 2

Creating Custom Event Logs

As mentioned earlier, you also have the ability to programmatically create your own custom event logs. (Figure 1 shows a screen shot of my Event Viewer where I've created a custom event log called "My Application Log".) You typically use event logs in situations where you wish to keep your application's events separate from other event sources.

Figure 1: You can use the Windows Event Viewer to work with both system-supplied as well as custom event logs.

What's the advantage to defining a custom event log for your application? The main reason is support. As the Event Viewer allows a user to export a log's events, the user is able to export only the events related to your application rather than an entire log containing events from other event sources. (The Event Viewer's filter function affects only what can be viewed; all events are exported when saving a log, regardless of the user-applied filter.)

Custom event logs are associated with specific event sources in a one-to-one relationship and are created via the static EventLog::CreateEventSource method. As creating a custom event log entails also verifying if the event log already exists and deleting the event source if it's associated with another event log (event sources can be associated only with a single log), I list here a generic method for doing everything you need to create a custom event log:

// Method assumes caller will catch exceptions 
// thrown by EventLog class
void CreateCustomEventLog(String* eventSource, String* logName)
{
#pragma push_macro("new")
#undef new

  // Does the Log already exist?
  if (!EventLog::Exists(logName))
  {
    // Does the event source already exist?
    if (EventLog::SourceExists(eventSource))
    {
      // Delete the event source as it can 
      // only be associated with one log
      EventLog::DeleteEventSource(eventSource);
    }
    // Create the event source and associate it 
    // with the new custom log.
    EventLog::CreateEventSource(eventSource, logName);
  }
#pragma pop_macro("new")
}

Only the first eight (8) characters of a custom log are significant. Therefore, when programmatically creating custom logs, you need to ensure that the log names are unique within the first eight characters or a System::ArgumentException will be thrown.

Using the CreateCustomEventMethod method, you can create your custom event logs like this:

// Create a custom event log called "My Application Log" for the
// event source "My Application"
CreateCustomEventLog(S"My Application", S"My Application Log");

Deleting Event Logs

Logs are programmatically deleted via the static EventLog::Delete method, where you pass the name of the log (and optionally, the machine name). As you can delete the system-supplied logs, be cautious when you use this method:

// Delete my custom event log
EventLog::Delete(S"My Application Log");

Who Has Access to My Event Log?

Each application that is defined as an event source capable of recording events to an event log is listed in the Windows registry. You can see this by viewing the HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\<LogName> registry (where LogName is either one of the system-supplied event logs (Application, System, or Security) or the name of a custom event log. Figure 2 is a screen capture where I've selected the custom event log "My Application Log".

Figure 2: All event logs and event log sources are stored in the registry in the HKLM hive.

Note that the event log subkey has a value called Sources. This value is a space-delimited string defining every event source that can write to that particular log. In addition, you can expand the event log subkey to see that each event source is also defined in its own subkey (below the event log subkey), where values such as EventMessageFile and TypesSupported are stored.

Looking Forward

As I mentioned at the outset of this article, I've divided this topic among several articles that each focus on a logically ordered task dealing with the Event Log. This article dealt with the event log tasks: enumerating local and remote event logs, instantiating an EventLog object for a specific local or remote event log, creating a custom event log, and deleting an event log. Upcoming articles will explore how to programmatically record and read events from an event log (using both 1.1 and 2.0 .NET functionality) and code an event log monitoring application.

About the Author

Tom Archer owns his own training company, Archer Consulting Group, which specializes in educating and mentoring .NET programmers and providing project management consulting. If you would like to find out how the Archer Consulting Group can help you reduce development costs, get your software to market faster, and increase product revenue, contact Tom through his Web site.