.NET Security : Programming the Event Log Service (part 1) - Querying the Event Log System, Using Event Sources

The .NET Framework exposes ELS functionality through the System.Diagnotics.EventLog class; Table 1 summarizes the public members of the EventLog class.

Table 1. Public members of the EventLog class

Member	Description
Properties
EnableRaisingEvents	Gets or sets a value indicating whether the EventLog instance receives EventWritten event notifications. See Section 20.2.6 for details.
Entries	Returns the contents of the event log.
Log	Gets or sets the name of the event log to read from and write to.
LogDisplayName	Gets the user-friendly name of the event log.
MachineName	Gets or sets the name of the computer on which to read or write events.
Source	Gets or sets the name of the event source used to write events to the log.
Methods
Clear	Removes all of the event entries from an event log.
CreateEventSource	Registers a new event source.
Delete	Deletes a specified event log from the ELS.
DeleteEventSource	Removes the registration for an event source.
Exists	Determines if a specified event log exists.
GetEventLogs	Obtains an EventLog array representing all of the event logs on the local or a remote computer. See Section 20.2.1 for details.
LogNameFromSourceName	Returns the name of the event log with which a specific event source is associated.
SourceExists	Determines if a specific event source has been registered with the ELS.
WriteEntry	Writes an event to the log. See Section 20.2.4 for details.
EntryWritten	An event that occurs when an event is written to an event log. See Section 20.2.6 for details.

In the following sections, we demonstrate how to use the EventLog class to program the ELS. The EventLog class does not expose all of the ELS functionality, and some advanced features are not available. You must use the unmanaged Windows API to gain access to the complete ELS feature set; see the Windows API documentation for details.

Many of the examples that follow demonstrate how to program the ELS of a remote computer. This functionality requires that a trust relationship is established; consult the Windows documentation for details of how to perform this task.

1. Querying the Event Log System

The EventLog class defines members that query the ELS for information about event logs. The static GetEventLogs method returns all of the event logs on a specified computer, represented as an array of EventLog instances. The following statements demonstrate how to use this method to obtain a list of event log names on the local computer:

# C#

// get the event logs installed on the local machine
EventLog[] x_logs = EventLog.GetEventLogs(  );

// run through the array of event logs and print out the names
foreach (EventLog x_log in x_logs) {
    Console.WriteLine("Log Name: {0}", x_log.Log);
}

# Visual Basic .NET

' get the event logs installed on the local machine
Dim x_logs(  ) As EventLog = EventLog.GetEventLogs(  )

' run through the array of event logs and print out the names
Dim x_log As EventLog
For Each x_log In x_logs
    Console.WriteLine("Log Name: {0}", x_log.Log)
Next

The output these statements produce depends on the configuration of your computer; our results are below, showing that our computer has only the three default logs:

Log Name: Application
Log Name: Security
Log Name: System

We can enumerate the event logs on another computer by using the overloaded version of the GetEventLog method, which accepts the computer name as an argument, as shown below for the computer called FILESERVER:

# C#

// get the event logs installed on another computer
EventLog[] x_logs = EventLog.GetEventLogs("FILESERVER");

# Visual Basic .NET

' get the event logs installed on another computer
Dim x_logs(  ) As EventLog = EventLog.GetEventLogs("FILESERVER")

We can determine if a specific log exists by using the static Exists method; the following statements demonstrate how to test for the existence of a log called MyEventLog—see the Section 20.2.5 for details of how to create and delete event logs:

# C#

bool x_log_exists = EventLog.Exists("MyEventLog");
Console.WriteLine("Log Exists: {0}", x_log_exists);

# Visual Basic .NET

Dim x_log_exists As Boolean = EventLog.Exists("MyEventLog")
Console.WriteLine("Log Exists: {0}", x_log_exists)

The following statements determine the existence of MyEventLog on the computer called FILESERVER, using the overloaded form of the Exists method:

# C#

bool x_log_exists = EventLog.Exists("MyEventLog", "FILESERVER");
Console.WriteLine("Log Exists: {0}", x_log_exists);

# Visual Basic .NET

Dim x_log_exists As Boolean = EventLog.Exists("MyEventLog", "FILESERVER")
Console.WriteLine("Log Exists: {0}", x_log_exists)

2. Using Event Sources

We register an event source with the static CreateEventSource method; this is an overloaded method with forms that register an event source locally or on another computer. The following statements demonstrate how to register an event source named MyEventSource, associated with the Application event log on the local computer and a second event source named MyOtherEventSource associated with the System event log on the FILESERVER computer:

# C#

// create "MyEventSource" on the local computer
EventLog.CreateEventSource("MyEventSource", "Application");

// create "MyOtherEventSource" on the FILESERVER computer
EventLog.CreateEventSource("MyOtherEventSource", "System", " FILESERVER ");

# Visual Basic .NET

' create "MyEventSource" on the local computer
EventLog.CreateEventSource("MyEventSource", "Application")

' create "MyOtherEventSource" on the FILESERVER computer
EventLog.CreateEventSource("MyOtherEventSource", "System", "FILESERVER")

If you do not specify an event log name as an argument to the CreateEventSource method (by using the empty string ""), the event source will be associated with the Application log. Event sources are persistent attempting to register an event source that already exists throws an instance of the System.ArgumentException exception class. We can check to see if an event source has been registered using the static SourceExists method; the following statements demonstrate how to use this method to ensure that our two example event sources are registered and will create them if they are not:

# C#
        
// check to see if we need to create the local event source
if (!EventLog.SourceExists("MyEventSource")) {
    // create "MyEventSource" on the local computer
    EventLog.CreateEventSource("MyEventSource", "Application");
}

// check to see if we need to create the remote event source
if (!EventLog.SourceExists("MyOtherEventSource", "FILESERVER")) {
    // create "MyOtherEventSource" on the FILESERVER computer
    EventLog.CreateEventSource("MyOtherEventSource", "System", "FILESERVER");
}

# Visual Basic .NET

' check to see if we need to create the local event source
If Not EventLog.SourceExists("MyEventSource") Then
    ' create "MyEventSource" on the local computer
    EventLog.CreateEventSource("MyEventSource", "Application")
End If


' check to see if we need to create the remote event source
If Not EventLog.SourceExists("MyOtherEventSource", "FILESERVER") Then
    ' create "MyOtherEventSource" on the FILESERVER computer
    EventLog.CreateEventSource("MyOtherEventSource", "System", "FILESERVER")
End If

					  

The static LogNameFromSourceName method determines the log with which an event source is associated, as shown by the following statements:

# C#

// obtain the name of the log associated with the local event source
string x_log_name = EventLog.LogNameFromSourceName("MyEventSource", ".");
// write out the log name
Console.WriteLine(x_log_name);

// obtain the name of the log associated with the remote event source
x_log_name = EventLog.LogNameFromSourceName("MyOtherEventSource", "FILESERVER");
// write out the log name
Console.WriteLine(x_log_name);

# Visual Basic .NET

' obtain the name of the log associated with the local event source
Dim x_log_name As String = EventLog.LogNameFromSourceName("MyEventSource", ".")
' write out the log name
Console.WriteLine(x_log_name)

' obtain the name of the log associated with the remote event source
x_log_name = EventLog.LogNameFromSourceName("MyOtherEventSource", "FILESERVER")
' write out the log name
Console.WriteLine(x_log_name)

					  

Notice that unlike the other methods covered in this section, the LogNameFromSourceName method does not have separate overridden forms for dealing with local and remote computers; the local machine is specified by a period.

We can remove an event source registration by using the overloaded DeleteEventSource method. The following statements demonstrate how to remove the event sources we created earlier:

# C#

// delete the local event source
EventLog.DeleteEventSource("MyEventSource");

// delete the remote event source
EventLog.DeleteEventSource("MyOtherEventSource", "FILESERVER");

# Visual Basic .NET

' delete the local event source
EventLog.DeleteEventSource("MyEventSource")

' delete the remote event source
EventLog.DeleteEventSource("MyOtherEventSource", "FILESERVER")

Attempting to delete an event source that is not registered (or whose registration has already been removed) will throw an instance of System.ArgumentException.