Export (0) Print
Expand All
1 out of 1 rated this helpful - Rate this topic

EventLog.WriteEvent Method (EventInstance, Object[])

Note: This method is new in the .NET Framework version 2.0.

Writes a localized entry to the event log.

Namespace: System.Diagnostics
Assembly: System (in system.dll)

[ComVisibleAttribute(false)] 
public void WriteEvent (
	EventInstance instance,
	params Object[] values
)
/** @attribute ComVisibleAttribute(false) */ 
public void WriteEvent (
	EventInstance instance, 
	Object[] values
)
ComVisibleAttribute(false) 
public function WriteEvent (
	instance : EventInstance, 
	... values : Object[]
)

Parameters

instance

An EventInstance instance that represents a localized event log entry.

values

An array of strings to merge into the message text of the event log entry.

Exception typeCondition

ArgumentException

The Source property of the EventLog has not been set.

-or-

The method attempted to register a new event source, but the computer name in MachineName is not valid.

- or -

The source is already registered for a different event log.

- or -

instance.InstanceId is less than zero or greater than UInt16.MaxValue.

- or -

values has more than 256 elements.

- or -

One of the values elements is longer than 32766 bytes.

- or -

The source name results in a registry key path longer than 254 characters.

ArgumentNullException

instance is a null reference (Nothing in Visual Basic) (Nothing in Visual Basic).

InvalidOperationException

The registry key for the event log could not be opened.

Win32Exception

The operating system reported an error when writing the event entry to the event log. A Windows error code is not available.

Use this method to write a localized entry to the event log. You specify the event properties with resource identifiers rather than string values. The Event Viewer uses the resource identifiers to display the corresponding strings from the localized resource file for the Source. You must register the source with the corresponding resource file before you write events using resource identifiers.

The input instance instance specifies the event message and properties. Set the InstanceId of the instance input for the defined message in the source message resource file. You can optionally set the CategoryId and EntryType of the instance input to define the category and event type of your event entry. You can also specify an array of language-independent strings to insert into the localized message text. Set values to a null reference (Nothing in Visual Basic) (Nothing in Visual Basic) if the event message does not contain formatting placeholders for replacement strings.

You must set the Source property on your EventLog component before using WriteEvent. The specified source must be configured for writing localized entries to the log; the source must at minimum have a message resource file defined.

You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an EventLogInstaller, or using the CreateEventSource method. You must have administrative rights on the computer to create a new event source.

The source must be configured either for writing localized entries or for writing direct strings. Use the WriteEntry method if your application writes string values directly to the event log.

If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the WriteEvent method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the WriteEntry method to write strings directly to the event log using that source.

NoteNote

If you write an entry to a remote computer, the value of the message (the text string) might not be what you expect if the remote computer is not running the .NET Framework.

The following example writes two audit entries to the event log myNewLog. The example creates a new event source and a new event log if they do not exist on the local computer. The event message text is specified using a resource identifier in a resource file.


// Create the event source if it does not exist.
string sourceName = "SampleApplicationSource";
if(!EventLog.SourceExists(sourceName))
{
    // Call a local method to register the event log source
    // for the event log "myNewLog."  Use the resource file
    // EventLogMsgs.dll in the current directory for message text.

    string messageFile =  String.Format("{0}\\{1}", 
        System.Environment.CurrentDirectory, 
        "EventLogMsgs.dll");

    CreateEventSourceSample1(messageFile);
}

// Get the event log corresponding to the existing source.
string myLogName = EventLog.LogNameFromSourceName(sourceName,".");
       
EventLog myEventLog = new EventLog(myLogName, ".", sourceName);

// Define two audit events.

// The message identifiers correspond to the message text in the
// message resource file defined for the source.
EventInstance myAuditSuccessEvent = new EventInstance(AuditSuccessMsgId, 0, EventLogEntryType.SuccessAudit);
EventInstance myAuditFailEvent = new EventInstance(AuditFailedMsgId, 0, EventLogEntryType.FailureAudit);

// Insert the method name into the event log message.
string [] insertStrings = {"EventLogSamples.WriteEventSample1"};

// Write the events to the event log.

myEventLog.WriteEvent(myAuditSuccessEvent, insertStrings); 

// Append binary data to the audit failure event entry.
byte [] binaryData = { 3, 4, 5, 6 };
myEventLog.WriteEvent(myAuditFailEvent, binaryData, insertStrings); 


The example uses the following message text file, built into the resource library EventLogMsgs.dll. A message text file is the source from which the message resource file is created. The message text file defines the resource identifiers and text for the category, event message, and parameter insertion strings.

; // EventLogMsgs.mc
; // ********************************************************

; // Use the following commands to build this file:

; //   mc -s EventLogMsgs.mc
; //   rc EventLogMsgs.rc
; //   link /DLL /SUBSYSTEM:WINDOWS /NOENTRY /MACHINE:x86 EventLogMsgs.Res 
; // ********************************************************

; // - Event categories -
; // Categories must be numbered consecutively starting at 1.
; // ********************************************************

MessageId=0x1
Severity=Success
SymbolicName=INSTALL_CATEGORY
Language=English
Installation
.

MessageId=0x2
Severity=Success
SymbolicName=QUERY_CATEGORY
Language=English
Database Query
.

MessageId=0x3
Severity=Success
SymbolicName=REFRESH_CATEGORY
Language=English
Data Refresh
.

; // - Event messages -
; // *********************************

MessageId = 1000
Severity = Success
Facility = Application
SymbolicName = AUDIT_SUCCESS_MESSAGE_ID_1000
Language=English
My application message text, in English, for message id 1000, called from %1.
.

MessageId = 1001
Severity = Warning
Facility = Application
SymbolicName = AUDIT_FAILED_MESSAGE_ID_1001
Language=English
My application message text, in English, for message id 1001, called from %1.
.


MessageId = 1002
Severity = Success
Facility = Application
SymbolicName = GENERIC_INFO_MESSAGE_ID_1002
Language=English
My generic information message in English, for message id 1002.
.


MessageId = 1003
Severity = Warning
Facility = Application
SymbolicName = GENERIC_WARNING_MESSAGE_ID_1003
Language=English
My generic warning message in English, for message id 1003, called from %1.
.


MessageId = 1004
Severity = Success
Facility = Application
SymbolicName = UPDATE_CYCLE_COMPLETE_MESSAGE_ID_1004
Language=English
The update cycle is complete for %%5002.
.


MessageId = 1005
Severity = Warning
Facility = Application
SymbolicName = SERVER_CONNECTION_DOWN_MESSAGE_ID_1005
Language=English
The refresh operation did not complete because the connection to server %1 could not be established.
.


; // - Event log display name -
; // ********************************************************


MessageId = 5001
Severity = Success
Facility = Application
SymbolicName = EVENT_LOG_DISPLAY_NAME_MSGID
Language=English
Sample Event Log
.



; // - Event message parameters -
; //   Language independent insertion strings
; // ********************************************************


MessageId = 5002
Severity = Success
Facility = Application
SymbolicName = EVENT_LOG_SERVICE_NAME_MSGID
Language=English
SVC_UPDATE.EXE
.

Windows 98, Windows 2000 SP4, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see System Requirements.

.NET Framework

Supported in: 2.0
Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.