.NET Security : Programming the Event Log Service (part 2) - Reading Event Logs, Writing Events

3. Reading Event Logs

The first step towards reading the contents of an event log is to create a new instance of the EventLog class, specifying the name of the log we want to read from as a constructor argument. The following statements demonstrate how to create new instances of the EventLog that refer to the local Application log and the System log on the FILESERVER computer:

# C#

// create a new instance that refers to the local Application log
EventLog x_local_log = new EventLog("Application");

// create a new instance which refers to the System log on FILESERVER
EventLog x_remote_log = new EventLog("System", "FILESERVER");

# Visual Basic .NET

' create a new instance that refers to the local Application log
Dim x_local_log As EventLog = New EventLog("Application")

' create a new instance which refers to the System log on FILESERVER
Dim x_remote_log As EventLog = New EventLog("System", "FILESERVER")

Once we have created an instance of the EventLog class, we can call the Entries property, which returns an instance of the EventLogEntryCollection class, containing the events in the log. Table 2 summarizes the public methods of the EventLogEntryCollection class, which implements the System.Collections.ICollection and System.Collections.IEnumerable interfaces.

Table 2. Public members of the EventLogEntryCollection class

Member	Description
Properties
Count	Returns the number of events in the log.
Item	Returns a specific event in the log, represented by the EventLogEntry class. For C#, this is the class indexer.
Methods
CopyTo	Copies the events in the event log into an EventLogEntry array.

The EventLogEntryCollection class represents the collection of events stored in a log, each of which is represented by an instance of the EventLogEntry class. Table 3 summarizes the public members of the EventLogEntry class; not all of the properties relate to ELS functionality supported by the .NET EventLog class. Consult the Windows API documentation for details of advanced ELS functionality.

Table 3. Public members of the EventLogEntry class

Property	Description
Category	Gets the category description associated with the event. Consult the Windows API documentation for details.
CategoryNumber	Gets the application-specific category value for the event.
Data	Gets the binary data associated with the event.
EntryType	Gets the event type, expressed as a value from the EventLogEntryType enumeration.
EventID	Gets the application-specific identifier for the event.
Index	Gets the position of this event in the event log.
MachineName	Gets the name of the computer on which the event was generated.
Message	Gets the human-readable message associated with this event.
ReplacementStrings	Gets the replacement strings associated with the event. Consult the Windows API documentation for details.
Source	Gets the name of the event source used to write the event.
TimeGenerated	Gets the time at which the event was created.
TimeWritten	Gets the time at which the event was written to the event log.
UserName	Gets the name of the user responsible for generating the event.

The following statements demonstrate how to use the EventLog.Entries property to obtain an EventLogEntryCollection for the Application log and print out details of the events using the EventLogEntry class:

# C#

// create a new instance that refers to the local Application log
EventLog x_local_log = new EventLog("Application");

// obtain a collection of the events through the Entries property
EventLogEntryCollection x_collection = x_local_log.Entries;

// write out the number of events in the log
Console.WriteLine("There are {0} entries in the event log", x_collection.Count);

// iterate through the entry collection and write out information
// about each event in turn
foreach (EventLogEntry x_entry in x_collection) {
    Console.WriteLine("Event Source: {0}, Event ID {1}, Event Message {2}",
    x_entry.Source, x_entry.EventID, x_entry.Message);
}

# Visual Basic .NET

' create a new instance that refers to the local Application log
Dim x_local_log As EventLog = New EventLog("Application")

' obtain a collection of the events through the Entries property
Dim x_collection As EventLogEntryCollection = x_local_log.Entries

' write out the number of events in the log
Console.WriteLine("There are {0} entries in the event log", x_collection.Count)

' iterate through the entry collection and write out information
' about each event in turn
Dim x_entry As EventLogEntry
For Each x_entry In x_collection
    Console.WriteLine("Event Source: {0}, Event ID {1}, Event Message {2}", _
    x_entry.Source, x_entry.EventID, x_entry.Message)
Next

					  

4. Writing Events

The first step towards writing events is to create an instance of the EventLog class configured for the log and the computer that you wish to receive your event data; the following statements demonstrate how to use the overloaded EventLog constructor to create instances that refer to the Application log on the local and FILESERVER computers:

# C#

// create a new instance that refers to the local Application log
EventLog x_local_log = new EventLog("Application");

// create a new instance that refers to the remote Application Log
EventLog x_remote_log = new EventLog("Application", "FILESEVER");

# Visual Basic .NET

' create a new instance that refers to the local Application log
Dim x_local_log As EventLog = New EventLog("Application")

' create a new instance that refers to the remote Application Log
Dim x_remote_log As EventLog = New EventLog("Application", "FILESEVER")

We can achieve the same affect by using the default EventLog constructor in conjunction with the MachineName and Log properties, as illustrated by the following statements (had we wanted to refer to the local machine we would have set the MachineName property to be a period):

# C#

// create a new instance that refers to the local Application log
EventLog x_local_log = new EventLog(  );
x_local_log.MachineName = "FILESERVER";
x_local_log.Log = "Application";

# Visual Basic .NET

' create a new instance that refers to the local Application log
Dim x_local_log As EventLog = New EventLog(  )
x_local_log.MachineName = "FILESERVER"
x_local_log.Log = "Application"

Having created the EventLog instance, we must specify the event source that we want to use when writing an event; we do this with the Source property, as the following statements show:

# C#

// create a new instance that refers to the local Application log
EventLog x_local_log = new EventLog("Application");

// specify the event source that we'll use to record events
x_local_log.Source = "MyEventSource";

# Visual Basic .NET

' create a new instance that refers to the local Application log
Dim x_local_log As EventLog = New EventLog("Application")

' specify the event source that we'll use to record events
x_local_log.Source = "MyEventSource"

Once we have specified the computer, the event log, and the event source to use, we can use the WriteEntry method to write an event to the log; this method is overloaded with 10 different versions, which allows you to log an event with increasing levels of detail. The simplest version of the WriteEntry method accepts only the human-readable message element, whereas the most complex version accepts values for all of the event structure elements . In the following statements, we write an error message to log an unexpected process-termination event to the Application log on the local computer:

# C#

// create a new instance that refers to the local Application log
EventLog x_local_log = new EventLog(  );
x_local_log.MachineName = ".";
x_local_log.Log = "Application";

// specify the event source that we'll use to record events
x_local_log.Source = "MyEventSource";

// define the binary data that will assist in debugging the problem
byte[] x_debugging_data = new byte[] {0xCA, 0xFE};

// write the event
x_local_log.WriteEntry(
    "MyApplication exited unexpectedly",  // this is the event message
    EventLogEntryType.Error,        // specify an error message
    100,    // this is the application-specific ID
    200,    // this is the application-specific category
    x_debugging_data // this is the binary data
);

# Visual Basic .NET

' create a new instance that refers to the local Application log
Dim x_local_log As EventLog = New EventLog(  )
x_local_log.MachineName = "."
x_local_log.Log = "Application"

' specify the event source that we'll use to record events
x_local_log.Source = "MyEventSource"

' define the binary data that will assist in debugging the problem
Dim x_debugging_data(  ) As Byte = New Byte(  ) {&HCA, &HFE}

' write the event
x_local_log.WriteEntry( _
"MyApplication exited unexpectedly", _
EventLogEntryType.Error, _
100, _
200, _
x_debugging_data _
)

					  

We specify the type of event we want to write by using a value from the System.Diagnostics.EventLogEntryType enumeration; Table 4 lists the defined values.

Table 4. EventLogEntryType enumeration values

Value	Description
Error	Represents an error event
Warning	Represents a warning event
Information	Represents an informational event
SuccessAudit	Represents a successful attempt to access an audited resource
FailureAudit	Represents an unsuccessful attempt to access an audited resource