Managing an Event Source
Managing an Event Source The EventLog class is a component in the System.Diagnostics namespace. You can add an EventLog object to your application by using an Imports System.Diagnostics statement in your module (or the Imports view of the project's Properties Pages) and instantiating an instance of the EventLog class, or you can pick the EventLog component from the Components tab of the toolbox (see Figure 20.1). Figure 20.1. Selecting the EventLog component from the Components tab of the toolbox. When creating an EventLog object, you will need to register your application as an event source. Registering your application as the source allows you to manage entries using the source name as a key to identifying entries made by your application. By convention, the event source name is the name of your application. Creating an Event SourceYou only need to create an event source once. If you call EventLog.CreateEventSource, your event sourceyour application's name by conventionis listed in the registry in HKEY_LOCAL_MACHINE\ SYSTEM\ Services\ EventLog as an originator of logged messages. Note The significance of registered sources is probably one of hierarchical organization more than anything else. The EventLog is organized to key entries by a source name, much as a relational database might use a unique field value to identify rows in a table. If you try to create a source that already exists, you will get a System. ArgumentException. If you try to write to an unregistered source, WriteEntry will create the specified source for you. The following code fragment demonstrates how to create an EventLog source and to check for an existing source. Both CreateEventSource and SourceExists are shared methods , so you don't have to create an instance of EventLog to verify that your source is available. CreateEventSource is an overloaded shared method that has two forms: Overloads Public Shared Sub CreateEventSource(source As String, _ logName As String) Overloads Public Shared Sub CreateEventSource(source As String, _ logName As String, machineName As String) The source argument is the name of the originator of the log entries. Your application's name is a suitable value for the source argument. The logName argument can be one of the existing logs ("Application," "System," or "Security") or a custom log name. The second overloaded form of CreateEventSource takes a third argument, a string specifying the machine name. You can log events to a remote computer (see "Using a Remote Event Log"). The "." supplied for the MachineName argument represents the local machine. Tip You aren't required to create an event source. If you specify an event source that doesn't exist in the WriteEntry, the source is created automatically. If you don't specify a log name, the entry defaults to the Application log. The SourceExists method is an overloaded method that has two forms: Overloads Public Shared Function SourceExists(logName As String) As Boolean Overloads Public Shared Function SourceExists(logName As String, _ machineName As String) As Boolean The first version checks on the local machine and the second version checks on a remote machine. Calling SourceExists( logName , ".") is equivalent to calling the first version of the method. The following code procedure demonstrates checking for an existing source and creating the source if it doesn't exist. Private Const EventSourceName As String = "AAA" Private Sub CheckEventSource() If (Not EventLog.SourceExists(EventSourceName)) Then EventLog.CreateEventSource(EventSourceName, "Application") End If End Sub Try running the code and then checking the registry for the source entry, as shown in Figure 20.2. Figure 20.2. The AAA appli-cation EventSource registry entry. Deleting an Event SourceSuppose you create an event source for debugging purposes only. Your application has a self-test mode. When the application is in self-test mode, a custom log and an associated event source are defined. When you turn off self-test mode, you elect to clean up the event source. You can use the overloaded shared method DeleteEventSource to clean up event sources you have finished with. Private Sub DeleteEventSource() If (SourceExists()) Then EventLog.DeleteEventSource(EventSourceName) End If End Sub Note For our example thus far we have been creating an event source in the "Application" log. Windows 2000 won't create a new .evt event log file. We will only get a new event log file if we specify a custom log name when the event source is created. The Windows 2000 Registry Editor (regedt32.exe) contains menu options for backing up and restoring your registry. The preceding procedure performs the symmetric operation to the CreateEventSource procedure in the previous subsection. Two versions of DeleteEventSource exist to allow you to pass a remote machine name containing the event source. Retrieving an Array of Event LogsYou can get an array containing all of the event logs on a particular machine by calling the EventLog.GetEventLogs shared method. Using a loop or an enumerator, you can perform operations on each instance of an event log or on an individual log. The following fragment demonstrates getting an array of event logs and iterating over each log. Public Shared Sub IterateLogs() Dim Logs() As EventLog = EventLog.GetEventLogs() Dim Enumerator As IEnumerator = Logs.GetEnumerator While Enumerator.MoveNext Debug.WriteLine(CType(Enumerator.Current, _ EventLog).LogDisplayName) End While End Sub The listing calls the Event.GetEventLogs shared method, which returns an array of EventLog objects. The Logs array is derived from System.Array and implements the IEnumerator interface, allowing us to iterate through each of the logs in the array using an enumerator. The code displays the user -friendly display name of the log. Finding the Log Name from the Source NameIf you have the source name but not the log name, you can query the EventLog for the log name. The EventLog.LogNameFromSourceName shared method will return the log that the source argument is writing to. You can use the log name to remove the log. You should avoid deleting the default logs: Application, Security, and System. EventLog.LogNameFromSourceName("myApp", ".") returns the log name that myApp is writing to on the local machine. Deleting a LogYou can manage the system or custom logs. The Exists and Delete shared methods allow you to determine whether a log exists and delete the log. The following statement demonstrates this: If(EventLog.Exists( logname )) Then EventLog.Delete( logname ) End If Caution Avoid deleting the System, Security, or Application logs. Even if you re-create these logs at a later date, you may not be able to re-create the individual application keys. Without the source keys, applications won't be able to write information to the event log. In addition to passing the log name, you can indicate a machine name as the second parameter. Be careful when using the EventLog.Delete method; this method will allow you to delete the System, Security, and Application logs. Avoid deleting the default logs because the associated .evt files and the registry keys will be deleted too.  |
| | |
Team-Fly  |
| Top |
