NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

EventLog Class

Provides interaction with Windows 2000 event logs.

Object
   Component
      EventLog

[Visual Basic]
Public Class EventLog
   Inherits Component
   Implements ISupportInitialize
[C#]
public class EventLog : Component, ISupportInitialize
[C++]
public __gc class EventLog : public Component, ISupportInitialize
[JScript]
public class EventLog extends Component, ISupportInitialize

Remarks

EventLog lets you manipulate the logs which record information about important software or hardware events that occur. Using EventLog, you can read from existing logs, write entries to logs, create or delete event sources, delete logs, and react to entries your log receives. You can create new logs as well when creating an event source. If the log specified in a call to CreateEventSource does not exist on the computer, the system creates a custom log and registers your application as a source for that log. Use the EventLog class to read and write entries to any event log to which you have the appropriate access.

Note   The Security log is read-only.

If you write to an event log, you must specify or create an event Source. The Source registers your application with the event log as a valid source of entries. The Source can only be used to write to a single log at a time. The Source can be any random string, but the name must be distinct from that of other sources on the computer. An attempt to create a duplicated Source value throws an exception. However, a single event log can have multiple sources associated with it.

To read from a log, you can specify only the Log name and MachineName (server computer name) for the EventLog instance. It is not necessary to specify the Source. In either case, the Entries member is automatically populated with the event log's list of entries. Select the appropriate index for an item in the list to read individual entries.

Note   You are not explicitly required to specify the MachineName if you are connecting to a log by specifying a Log/ MachineName pair. If you do not specify the MachineName, the local computer, ".", is assumed.

When writing to an event log, you can specify the type of information sent with the entry message. In addition to sending the message, you can send an EventLogEntryType to indicate, for example, whether the message is an Error, Warning, or Information. You can also specify an eventId and category that you have defined in your application and that will display in the Type and Category columns of the event viewer. Finally, you can also attach binary data to your event entry if you need additional information to be associated with a given event.

In addition to manipulating specific event logs and their entries, EventLog provides access to the event log collection itself. You can use the static (in Visual Basic Shared) members of EventLog to delete logs, get log lists, determine if a Source already exists on a given computer, and create or delete a Source.

Windows 2000 has three default logs: Application, System, and Security. Other installed applications and services, such as Active Directory, can have additional event logs. You can use EventLog to create custom event logs that can be viewed through the server's Event Viewer.

Event logging consumes resources such as disk space and processor time. It is important to log only essential information. It is also best to place event log calls in an error path in the code rather than in the main code path, so as not to reduce performance.

When an instance of EventLog is created, the read/write properties are set to initial values. For a list of these values, see the EventLog constructor.

Requirements

Namespace: System.Diagnostics

Assembly: System.Diagnostics.dll

Example [Visual Basic]

The following example connects to an event log, "myNewLog", on the local computer. If the source "myNewSource" does not already exist on the computer, it is created. Then, an entry is written to the Log.

Note that the way to create a new event log is through the static (Shared) member CreateEventSource, which creates a Source and registers it to the Log at the time the log is created. Because this is a static (Shared) member of EventLog, it should be called on the class itself rather than on an instance of the class.

Import the System.Diagnostics namespace for this example.

[Visual Basic]

Private Sub ConnectToEventLog()
    'Declare a new event log and event log entry.
    Dim evtLog As EventLog

    'Instantiate a new event log.
    evtLog = New EventLog

    'Otherwise, create a new source and log.
    If Not EventLog.SourceExists("myNewSource") Then
        'If MyNewLog does not exist, it will be created
        EventLog.CreateEventSource("myNewSource", "myNewLog")
    End If
    
    'Connect the source to the event instance.
    evtLog.Source = "myNewSource"
    
    'Write an entry to the event log.
    evtLog.WriteEntry("My entry.")
End Sub

See Also

EventLog Members | System.Diagnostics Namespace | EventLogEntry | EventLogEvent