How to: Write Entries to Event Logs

When you write an entry to an event log, you specify the message you want to write to the log as a string. A message should contain all information needed to interpret what caused the problem and what to do to correct the problem.

There are two ways you can write an entry to the log; both are equally valid. The most direct way is to register an event source with the log to which you want to write, then instantiate a component and set its Source property to that log, and finally call WriteEntry. If you do this, you do not have to set the Log property for the component instance; the log is automatically determined when you connect to a source that has already been registered. For more information on registering a source, see How to: Add Your Application as a Source of Event Log Entries.

The other way to approach this process is to instantiate an EventLog component, set its Source, MachineName, and Log properties, and call the WriteEntry method. In this case, the WriteEntry method would determine whether the source already existed and register it on the fly if it did not.

The following conditions must be met in order to successfully write a log entry:

• The source must be registered with the desired log.

  Note

  You must set the Source property on your EventLog component instance before you can write entries to a log. When your component writes an entry, the system automatically checks to see if the source you specified is registered with the event log to which the component is writing, and calls CreateEventSource if needed. In general, 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. If creating the source during installation is not an option, then try to create the source well ahead of the first write operation, perhaps during your application initialization. If you choose this approach, be sure your initialization code is running with administrator rights on the computer. These rights are required for creating new event sources.

• The message you specify cannot be more than 16K in length.

• Your application must have write access to the log to which it is attempting to write. For more information, see Security Ramifications of Event Logs.

You can specify several parameters when you write an entry, including the type of entry you're making, an ID that identifies the event, a category, and any binary data you want to append to the entry.

To write an event log entry

1. Instantiate an EventLog component. For more information, see How to: Create EventLog Component Instances.

2. Use the CreateEventSource method to register an event source with the log to which you want to write an entry, using a unique string for the source string. Set the Source property for the component to the source you registered. For more information, see How to: Configure EventLog Component Instances. Call the WriteEntry method to specify the entry to be written to the log.

   If Not EventLog.SourceExists("MyApp1") Then
       EventLog.CreateEventSource("MyApp1", "Application")
   End If 
   Dim eventLog1 As New EventLog
   eventLog1.Source = "MyApp1"
   eventLog1.WriteEntry("This is a simple event log entry")
   

   if (!System.Diagnostics.EventLog.SourceExists("MyApp1"))
       System.Diagnostics.EventLog.CreateEventSource(
          "MyApp1", "Application");
   EventLog eventLog1 = new EventLog();
   eventLog1.Source = "MyApp1";
   eventLog1.WriteEntry("This is a simple event log entry");
   

To write a localized event log entry

1. Instantiate an EventLog component. For more information, see How to: Create EventLog Component Instances.

2. To write localized event log entries, use the WriteEvent method. In this case, you specify the event properties with resource identifiers rather than with 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. For information registering a resource file, see EventSourceCreationData Class.

   If Not EventLog.SourceExists("MyApp1") Then
       EventLog.CreateEventSource("MyApp1", "Application")
   End If 
   Dim eventLog1 As New EventLog
   eventLog1.Source = "MyApp1"
   eventLog1.WriteEvent(New EventInstance(1, 1), New String() {"message"})
   

   if (!System.Diagnostics.EventLog.SourceExists("MyApp1"))
       System.Diagnostics.EventLog.CreateEventSource(
          "MyApp1", "Application");
   EventLog eventLog1 = new EventLog();
   eventLog1.Source = "MyApp1";
   eventLog1.WriteEvent(new System.Diagnostics.EventInstance(1, 1), new string[] { "message" });
   

See Also

Tasks

How to: Configure EventLog Component Instances

How to: Create EventLog Component Instances

How to: Add Your Application as a Source of Event Log Entries

Walkthrough: Exploring Event Logs, Event Sources, and Entries

Concepts

Introduction to the EventLog Component

Reference

EventLog

Change History