20.2 Programming the Event Log Service

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

Table 20-3. 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.

Your code must be granted the EventLog permission in order to access the Event Log Service; see Chapter 7 for details of how to use permissions.

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.

20.2.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)

20.2.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, as we explained in Section 20.1.2 of this chapter; 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.

20.2.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 20-4 summarizes the public methods of the EventLogEntryCollection class, which implements the System.Collections.ICollection and System.Collections.IEnumerable interfaces.

Table 20-4. 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 20-5 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 20-5. 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

20.2.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 we described in Section 20.1.3. 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 20-6 lists the defined values, which correspond to the event types detailed in Table 20-2.

Table 20-6. 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

20.2.5 Using Custom Event Logs

You can create custom event logs by specifying the name you wish to use with the Log property of the EventLog class. When you write the first event to the log with the WriteEntry method, the ELS will create the custom log automatically. The event source specified by the Source property will be registered and associated with the new custom log. The following statements demonstrate how to create the custom log MyCustomEventLog; ELS does not create the custom log until the WriteEntry statement is executed:

# C# // create a new instance that refers to the custom log EventLog x_local_log = new EventLog(  ); x_local_log.MachineName = "."; x_local_log.Log = "MyCustomEventLog"; // specify the event source that we'll use to record events x_local_log.Source = "MyCustomEventSource"; // write a log entry - the custom log will not be created until this point x_local_log.WriteEntry("MyApplication exited unexpectedly"); # Visual Basic .NET ' create a new instance that refers to the custom log Dim x_local_log As EventLog = New EventLog(  ) x_local_log.MachineName = "." x_local_log.Log = "MyCustomEventLog" ' specify the event source that we'll use to record events x_local_log.Source = "MyCustomEventSource" ' write a log entry - the custom log will not be created until this point x_local_log.WriteEntry("MyApplication exited unexpectedly")

Custom logs can be deleted with the Delete method defined by the EventLog class, as demonstrated by the following statements:

# C#  // delete the custom event log EventLog.Delete("MyCustomEventLog"); # Visual Basic .NET ' delete the custom event log EventLog.Delete("MyCustomEventLog")

Use the Delete method with caution; the event log will be removed and all of the entries and event sources will be lost permanently. An instance of the System.InvalidOperationException exception is thrown by the Delete method if you attempt to delete a log that does not exist.

The EventLog.Delete method will delete the Application and System default event logs without warning. Deleting these logs can cause applications to behave erratically.

20.2.6 Monitoring Event Logs

The EventLog class provides an event mechanism that allows us to monitor an event log. In this section, we demonstrate how to use this feature, which relies on the .NET event delegate mechanism; consult the .NET documentation if you are unfamiliar with .NET delegates.

We can register for event notification by adding an instance of the EntryWrittenEventHandler delegate to the EntryWritten event defined by the EventLog class, as demonstrated by the statements below. The delegate method signature defines the EntryWrittenEventArgs class, which makes the event that has been written available as an instance of EventLogEntry accessible through the Entry property:

# C# using System; using System.Diagnostics; public class EventLogMonitor {     public static void Main(  ) {         // create a new instance of the EventLog class         EventLog x_local_log = new EventLog("MyCustomEventLog");         // create a delegate to process events from the ELS         EntryWrittenEventHandler x_handler              = new EntryWrittenEventHandler(MyOnEntryWrittenMethod);         // add the delegate to the EventLog event         x_local_log.EntryWritten += x_handler;         // enable event processing         x_local_log.EnableRaisingEvents = true;         // wait to read a lone from the console - just to stop         // the application from exiting         Console.ReadLine(  );     }     public static void MyOnEntryWrittenMethod(object p_source,          EntryWrittenEventArgs p_args) {         // extract the event object from the event arguments         EventLogEntry x_entry = p_args.Entry;         // write out the event details         Console.WriteLine("Event Source: {0}, Event ID {1}, Event Message {2}",             x_entry.Source, x_entry.EventID, x_entry.Message);     } } # Visual Basic .NET Imports System.Diagnostics Class EventLogMonitor     Shared Sub Main(  )         ' create a new instance of the EventLog class         Dim x_local_log As EventLog = New EventLog("MyCustomEventLog")         ' create a delegate to process events from the ELS         AddHandler x_local_log.EntryWritten, AddressOf MyOnEntryWrittenMethod         ' enable event processing         x_local_log.EnableRaisingEvents = True         ' wait to read a lone from the console - just to stop         ' the application from exiting         Console.ReadLine(  )     End Sub     Public Shared Sub MyOnEntryWrittenMethod(ByVal p_source As Object, _     ByVal p_args As EntryWrittenEventArgs)         ' extract the event object from the event arguments         Dim x_entry As EventLogEntry = p_args.Entry         ' write out the event details         Console.WriteLine("Event Source: {0}, Event ID {1}, Event Message {2}", _             x_entry.Source, x_entry.EventID, x_entry.Message)     End Sub End Class

Events will not be raised until the value of the EnableRaisingEvents property is set to true (C#) or True (Visual Basic .NET). The EventWritten event is raised five seconds after an entry has been added to the monitored event log; if several events have been written during the five-second period, only the last event will be signaled via the delegate.

The EventLog class does not support monitoring event logs managed by other computers only local logs can be monitored.



Programming. NET Security
Programming .Net Security
ISBN: 0596004427
EAN: 2147483647
Year: 2005
Pages: 346

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net