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.WriteEntry (String, EventLogEntryType, Int16, Int16)

Writes an entry of the specified type with the user-defined eventID and category to the event log. The category can be used by the event viewer to filter events in the log.

[Visual Basic]
Overloads Public Sub WriteEntry( _
   ByVal message As String, _
   ByVal type As EventLogEntryType, _
   ByVal eventID As Short, _
   ByVal category As Short _
)
[C#]
public void WriteEntry(
   string message,
   EventLogEntryType type,
   short eventID,
   short category
);
[C++]
public: void WriteEntry(
   String* message,
   EventLogEntryType type,
   short eventID,
   short category
);
[JScript]
public function WriteEntry(
   message : String,
   type : EventLogEntryType,
   eventID : Int16,
   category : Int16
);

Parameters

message
The string to write to the event log.
type
One of the EventLogEntryType values.
eventID
The source-specific identifier for the event, which identifies the current message.
category
A source-specific subcategory associated with the message.

Exceptions

Exception Type Condition
ArgumentException The Source property of the EventLog has not been set.

-or-

The method has attempted to create a new event Source, but the computer name is not valid.

-or-

The method has attempted to create a new event Source, but the source name was not specified.

-or-

The method has attempted to create a new event Source, but the source already exists on the computer.

-or-

The method has attempted to create a new Log, but the first eight characters of the log name are not unique on the computer.

-or-

The method has attempted to open the event log with read access, but the Log property was not specified.

-or-

The method has attempted to open the event log with write access, but the Source property was not specified.

-or-

The message string is too long. The size must be less than 16384 bytes.

-or-

The source is not registered to the given log.

Exception The registry entry for the Log could not be opened on a remote computer.
InvalidOperationException The method has attempted to open the event log with write access, but you do not have write access to the log.
Win32Exception The method attempted to release the event log's read or write handle but did not do so successfully.

-or-

The method attempted to open the event log with read access but was unable to do so.

-or-

The event could not be reported to the log.

SystemException The event log could not be notified to start listenting for events.

Remarks

WriteEntry lets you specify a string message to write to the log. This method writes the given string directly to the log; it does not use a localizable message file.

Use this overload if you want to write an entry with an application-defined category to the event log. Categories help you organize events so Event Viewer can filter them. Each application can define its own numbered categories and the text strings to which they are mapped. The categories must be numbered consecutively beginning with the number 1. The Event Viewer presents the category to the user in the Category column.

In addition to the event identifier, this overload of WriteEntry lets you specify an EventLogEntryType and an event identifier for the event being written to the event log. Event identifiers uniquely identify a particular event. Each application can define its own numbered events and the description strings to which they are mapped. Event viewers can present these strings to the user in the Event column. They should help the user understand what went wrong and suggest what actions to take. The type is indicated in the Event Viewer for a log by an icon and text in the Type column.

You must set the Source property on your EventLog component before you can write entries to the log. You can call CreateEventSource on a new Source to register it before writing to the event log, but this is not necessary. If a new Source has not been registered on the computer to which your component is writing, WriteEntry calls CreateEventSource automatically and registers the Source for you.

If you have not specified a MachineName for your EventLog instance before calling CreateEventSource or WriteEntry, the local computer (".") is assumed.

If the system needs to register the Source through a call to WriteEntry and the Log property has not been set on your EventLog instance, it defaults to the Application log.

Note   Many of the exceptions listed above are generated by errors raised during the process of registering the Source.

Example [Visual Basic]

The following example connects to a log with the source "myNewSource". It then writes an entry to the log. This example assumes there is an existing source named "myNewSource" on the local computer.

The procedure defines its own eventId and computerType values, which correspond to what appears in the Event and Category columns of the Event Viewer. The following table describes how the procedure's fileEventType strings correspond to locally-defined eventId values. The second table describes how computer names correspond to application-defined computer types. Note that this was randomly selected for this example; there is no inherent meaning in the eventId, computerType,or fileEventType values.

File Event String Value
OpenFile 0x01
FileAccessDenied 0x02
FileError 0x04
Computer Name Value
type1Computer 0x01
type2Computer 0x02

When the entry is written to the event log, the entry type (Information, Failure Audit), which this procedure associates with each file event, is specified as well. You can view the entry information in the Event Viewer to see the Type (type), Event (eventId), Category (category), and message text.

Import the System.Diagnostics namespace for this example.

[Visual Basic]

Private Sub WriteEntryWithId(ByVal fileEventType As String, ByVal computer As String)
    'Declare a new event log.
    Dim evtLog As EventLog
    'The eventId corresponds to the file event.
    Dim eventId As Int16
    'The EventLogEntryType we associate with the file event.
    Dim entryType As EventLogEntryType
    'The computer type: type1, type2, etc..
    Dim computerType As Int16

    'Instantiate a new event log.
    evtLog = New EventLog
    'Connect the event log to the source.
    evtLog.Source = "mySource"

    'Set the computer type. This was randomly-defined for the example.
    Select Case computer
        Case "type1Computer"
'Application-assigned computer type.
computerType = 1
        Case "type2Computer"
computerType = 2
    End Select

    'Set the eventId and entryType based on the file event passed in.
    Select Case fileEventType
        Case "OpenFile"
'This was randomly defined. The actual values are not crucial.
eventId = 1
entryType = EventLogEntryType.SuccessAudit
        Case "FileAccessDenied"
eventId = 2
entryType = EventLogEntryType.FailureAudit
        Case "FileError"
eventId = 4
entryType = EventLogEntryType.Error
    End Select

    'Write the entry information to the log.
    evtLog.WriteEntry("File access event occurred.", entryType, eventId, computerType)
End Sub

See Also

EventLog Class | EventLog Members | System.Diagnostics Namespace | EventLog.WriteEntry Overload List | EventLogEntryType | Source | CreateEventSource | DeleteEventSource | SourceExists