Writing to the Windows Event Log

for RuBoard

It's common for server software to persistently record information about what it's doing. This activity is called logging. It's common for programmers to spend time creating logging features in the applications they write ”both as a debugging tool and as a way for users and system administrators to see what's going on with the software. However, Windows programmers typically don't create their own logging facilities in the applications they create, because the operating system provides one for them: the Windows event log.

The Windows event log is a central, system-managed place where any application, service, or device can log information. It is available on Windows NT and Windows 2000. Logged events usually contain status information or failure messages. You are free to use the event log from any of your applications, including ASP.NET applications, as a way of persistently storing information pertaining to your application's behavior in a way that's easy for system administrators to access.

NOTE

Logging serves a similar function to performance monitoring (discussed earlier in this chapter). But it differs in the area of how the data is stored. Monitoring is a real-time view of what your application is doing at any given moment. Monitoring information is stored in memory and does not normally survive a system reboot. Logging, on the other hand, is persisted to disk and provides a historical record of your server application's behavior over a long period of time.

In Windows 2000 Server, you can access the event log through the Event Viewer application found in the Administrative Tools group under the Start menu. Events are divided into three categories: application, security, and system. Your application can read from any log and write information to the application log, as described in the next section.

Using the EventLog Class

Any application, including ASP.NET applications, can access the event log. Your applications will write information to the application log (rather than to the security or system logs).

The .NET framework provides a class for handling the event log. This is the EventLog class, found in System.Diagnostics.

NOTE

The properties, methods , and events of the EventLog class are summarized in the reference section at the end of this chapter.

To send information to the application log, you use the EventLog class. This class is created for you automatically, so you do not need to instantiate it (although you can if you need to).

To perform logging, you first use the EventLog object to create an event source. An event source is a way of identifying where a log entry came from. Many data sources can write to the same log; for example, many applications typically write error messages to the application log, and a variety of server processes create entries in the system log.

Event sources must be registered before you write information to the log. You do this by calling the CreateEventSource method of the EventLog object.

NOTE

For applications you create, unless you have a really good reason to create your own log, it's probably best to toss your own logs into the application log with everything else. That's where system administrators will look for it.

Only the first eight characters of a log name are significant. This means you can't create a log named, for instance, Application Data, because Application is a built-in log created by Windows.

Listing 3.10 shows an example of how to write information to the Windows event log. This code first checks to see if an event source called MyApp exists; if not, the code creates it. The code then sends information to the event log by calling the WriteEntry method of the EventLog object.

Listing 3.10 Writing an Event to the Windows Event Log

 void  Button1_Click(Object Sender, EventArgs e) {   if(!EventLog.SourceExists("MyApp"))   {     EventLog.CreateEventSource("MyApp", "Application");   }   EventLog.WriteEntry("MyApp", "This is just a test.",             EventLogEntryType.Information); } 

The WriteEntry method is overloaded; the code example shows the most commonly used form. The first parameter is a string representing the event source. The second parameter is the message to insert in the log. The third parameter is an event type; this is a member of the enumeration System.Diagnostics.EventLogEntryType.

You can view the output of this code by launching the Event Viewer (found in Programs, Administrative Tools). After running the code, click Application Log. You should be able to see an Information entry for the MyApp event source. Double-clicking the event displays a property sheet that shows you the detail for the event (the description "This is just a test").

for RuBoard