System.Diagnostics.EventLogInstaller Class

Allows you to install and configure an event log that your application reads from or writes to when running.

See Also: EventLogInstaller Members

Syntax

public class EventLogInstaller : System.Configuration.Install.ComponentInstaller

Remarks

The System.Diagnostics.EventLogInstaller is used by the Installer Tool (Installutil.exe) when installing an event log. The System.Diagnostics.EventLogInstaller class can install event logs only on the local computer.

Use the System.Diagnostics.EventLogInstaller class when your application writes to an event log; it is not necessary to use an event log installer for your application to read from an event log. Applications and services should write to the Application log or a custom log. Device drivers should write to the System log.

Note:

The Security log is read-only.

The installer creates the event source that you specify in the EventLogInstaller.Source property and registers it for the event log specified in EventLogInstaller.Log property. This behavior is similar to calling EventLog.CreateEventSource(string, string) on the System.Diagnostics.EventLog component.

Use the erload:System.Diagnostics.EventLog.WriteEvent and erload:System.Diagnostics.EventLog.WriteEntry methods to write events to an event log. You must specify an event source to write events; 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 configurations. 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 System.Diagnostics.EventLogInstaller, or using the erload:System.Diagnostics.EventLog.CreateEventSource method. You must have administrative rights on the computer to create a new event source.

You can create an event source for an existing event log or a new event log. When you create a new source for a new event log, the system registers the source for that log, but the log is not created until the first entry is written to it.

To install an event log, create a project installer class that inherits from System.Configuration.Install.Installer, and set the System.ComponentModel.RunInstallerAttribute for the class to true. Within your project, create an System.Diagnostics.EventLogInstaller for each event log that your application will write to and add the instance to your project installer class.

When the Installer Tool (Installutil.exe) is called, it looks at the System.ComponentModel.RunInstallerAttribute. If it is true, the tool installs all the items in the System.Configuration.Install.Installer.Installers collection that are associated with your project installer. If System.ComponentModel.RunInstallerAttribute is false, the tool ignores the project installer.

You modify other properties of an System.Diagnostics.EventLogInstaller either before or after adding the instance to the System.Configuration.Install.Installer.Installers collection of your project installer, but before the installer tool runs. You must set the EventLogInstaller.Source property if your application will be writing to the event log.

Use System.Diagnostics.EventLogInstaller to register a new source for a new or existing event log; do not use System.Diagnostics.EventLogInstaller to change an existing source. The System.Diagnostics.EventLogInstaller class does not modify the configuration properties of an existing source to match the specified installation properties. The EventLogInstaller.Install(IDictionary) method throws an exception if the EventLogInstaller.Source property matches a source name that is registered for a different event log on the computer. The EventLogInstaller.Install(IDictionary) method does not register the source if the EventLogInstaller.Source property matches a source name that is already registered for the same event log specified in the EventLogInstaller.Log property.

You can register the event source with localized resource files for your event category and message strings. Your application can write event log entries using resource identifiers, rather than specifying the actual string. The Event Viewer uses the resource identifier to find and display the corresponding string from the localized resource file based on current language settings. You can register a separate file for event categories, messages, and parameter insertion strings, or you can register the same resource file for all three types of strings. Use the EventLogInstaller.CategoryCount, EventLogInstaller.CategoryResourceFile, EventLogInstaller.MessageResourceFile, and EventLogInstaller.ParameterResourceFile properties to configure the source to write localized entries to the event log. If your application writes strings values directly to the event log, you do not need to set these properties.

The source must be configured either for writing localized entries or for writing direct strings. 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 erload:System.Diagnostics.EventLog.WriteEvent method to write entries using resource identifiers to the event log. Create a different source without resource files and then use that source in the erload:System.Diagnostics.EventLog.WriteEntry method to write strings directly to the event log using that source.

Typically, you do not call the methods of the System.Diagnostics.EventLogInstaller class from within your code; they are generally called only by Installutil.exe. The tool automatically calls the EventLogInstaller.Install(IDictionary) method during the installation process. It backs out failures, if necessary, by calling the EventLogInstaller.Rollback(IDictionary) method for the object that generated the exception.

Requirements

Namespace: System.Diagnostics
Assembly: System.Configuration.Install (in System.Configuration.Install.dll)
Assembly Versions: 1.0.5000.0, 2.0.0.0