EventLogInstaller Class

Definition

Namespace:

System.Diagnostics

Assembly:

System.Configuration.Install.dll

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

public ref class EventLogInstaller : System::Configuration::Install::ComponentInstaller

public class EventLogInstaller : System.Configuration.Install.ComponentInstaller

type EventLogInstaller = class
    inherit ComponentInstaller

Public Class EventLogInstaller
Inherits ComponentInstaller

Inheritance

Object

MarshalByRefObject

Component

Installer

ComponentInstaller

EventLogInstaller

Examples

The following code example sets the installation properties for a new event source. The code example sets the source name and the event log name, and adds the EventLogInstaller to the Installers collection.

#using <System.dll>
#using <System.Configuration.Install.dll>

using namespace System;
using namespace System::Configuration::Install;
using namespace System::Diagnostics;
using namespace System::ComponentModel;

[RunInstaller(true)]
ref class MyEventLogInstaller: public Installer
{
private:
   EventLogInstaller^ myEventLogInstaller;

public:
   MyEventLogInstaller()
   {
      // Create an instance of an EventLogInstaller.
      myEventLogInstaller = gcnew EventLogInstaller;

      // Set the source name of the event log.
      myEventLogInstaller->Source = "NewLogSource";
         
      // Set the event log that the source writes entries to.
      myEventLogInstaller->Log = "MyNewLog";
         
      // Add myEventLogInstaller to the Installer collection.
      Installers->Add( myEventLogInstaller );
   }
};

using System;
using System.Configuration.Install;
using System.Diagnostics;
using System.ComponentModel;

[RunInstaller(true)]
public class MyEventLogInstaller: Installer
{
    private EventLogInstaller myEventLogInstaller;

    public MyEventLogInstaller()
    {
        // Create an instance of an EventLogInstaller.
        myEventLogInstaller = new EventLogInstaller();

        // Set the source name of the event log.
        myEventLogInstaller.Source = "NewLogSource";

        // Set the event log that the source writes entries to.
        myEventLogInstaller.Log = "MyNewLog";

        // Add myEventLogInstaller to the Installer collection.
        Installers.Add(myEventLogInstaller);
    }

    public static void Main()
    {
        MyEventLogInstaller myInstaller = new MyEventLogInstaller();
    }
}

   Imports System.Configuration.Install
Imports System.Diagnostics
Imports System.ComponentModel

<RunInstaller(True)>  _
Public Class MyEventLogInstaller
   Inherits Installer
   Private myEventLogInstaller As EventLogInstaller
   
   Public Sub New()

      ' Create an instance of an EventLogInstaller.
      myEventLogInstaller = New EventLogInstaller()

      ' Set the source name of the event log.
      myEventLogInstaller.Source = "NewLogSource"

      ' Set the event log that the source writes entries to.
      myEventLogInstaller.Log = "MyNewLog"

      ' Add myEventLogInstaller to the Installer collection.
      Installers.Add(myEventLogInstaller)
   End Sub

 Public Shared Sub Main()
 End Sub
 Dim myInstaller As New EventLogInstaller()
End Class

Remarks

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

Use the 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 Source property and registers it for the event log specified in Log property. This behavior is similar to calling CreateEventSource on the EventLog component.

Use the WriteEvent and 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 EventLogInstaller, or using the 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 Installer, and set the RunInstallerAttribute for the class to true. Within your project, create an EventLogInstaller for each event log that your application will write to and add the instance to your project installer class.

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

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

Use EventLogInstaller to register a new source for a new or existing event log; do not use EventLogInstaller to change an existing source. The EventLogInstaller class does not modify the configuration properties of an existing source to match the specified installation properties. The Install method throws an exception if the Source property matches a source name that is registered for a different event log on the computer. The Install method does not register the source if the Source property matches a source name that is already registered for the same event log specified in the 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 CategoryCount, CategoryResourceFile, MessageResourceFile, and 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 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 WriteEntry method to write strings directly to the event log using that source.

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

Constructors

EventLogInstaller()

Initializes a new instance of the EventLogInstaller class.

Properties

CanRaiseEvents	Gets a value indicating whether the component can raise an event. (Inherited from Component)
CategoryCount	Gets or sets the number of categories in the category resource file.
CategoryResourceFile	Gets or sets the path of the resource file that contains category strings for the source.
Container	Gets the IContainer that contains the Component. (Inherited from Component)
Context	Gets or sets information about the current installation. (Inherited from Installer)
DesignMode	Gets a value that indicates whether the Component is currently in design mode. (Inherited from Component)
Events	Gets the list of event handlers that are attached to this Component. (Inherited from Component)
HelpText	Gets the help text for all the installers in the installer collection. (Inherited from Installer)
Installers	Gets the collection of installers that this installer contains. (Inherited from Installer)
Log	Gets or sets the name of the log to set the source to.
MessageResourceFile	Gets or sets the path of the resource file that contains message formatting strings for the source.
ParameterResourceFile	Gets or sets the path of the resource file that contains message parameter strings for the source.
Parent	Gets or sets the installer containing the collection that this installer belongs to. (Inherited from Installer)
Site	Gets or sets the ISite of the Component. (Inherited from Component)
Source	Gets or sets the source name to register with the log.
UninstallAction	Gets or sets a value that indicates whether the Installutil.exe (Installer Tool) should remove the event log or leave it in its installed state at uninstall time.

Methods

Commit(IDictionary)	When overridden in a derived class, completes the install transaction. (Inherited from Installer)
CopyFromComponent(IComponent)	Copies the property values of an EventLog component that are required at installation time for an event log.
CreateObjRef(Type)	Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object. (Inherited from MarshalByRefObject)
Dispose()	Releases all resources used by the Component. (Inherited from Component)
Dispose(Boolean)	Releases the unmanaged resources used by the Component and optionally releases the managed resources. (Inherited from Component)
Equals(Object)	Determines whether the specified object is equal to the current object. (Inherited from Object)
GetHashCode()	Serves as the default hash function. (Inherited from Object)
GetLifetimeService()	Retrieves the current lifetime service object that controls the lifetime policy for this instance. (Inherited from MarshalByRefObject)
GetService(Type)	Returns an object that represents a service provided by the Component or by its Container. (Inherited from Component)
GetType()	Gets the Type of the current instance. (Inherited from Object)
InitializeLifetimeService()	Obtains a lifetime service object to control the lifetime policy for this instance. (Inherited from MarshalByRefObject)
Install(IDictionary)	Performs the installation and writes event log information to the registry.
IsEquivalentInstaller(ComponentInstaller)	Determines whether an installer and another specified installer refer to the same source.
MemberwiseClone()	Creates a shallow copy of the current Object. (Inherited from Object)
MemberwiseClone(Boolean)	Creates a shallow copy of the current MarshalByRefObject object. (Inherited from MarshalByRefObject)
OnAfterInstall(IDictionary)	Raises the AfterInstall event. (Inherited from Installer)
OnAfterRollback(IDictionary)	Raises the AfterRollback event. (Inherited from Installer)
OnAfterUninstall(IDictionary)	Raises the AfterUninstall event. (Inherited from Installer)
OnBeforeInstall(IDictionary)	Raises the BeforeInstall event. (Inherited from Installer)
OnBeforeRollback(IDictionary)	Raises the BeforeRollback event. (Inherited from Installer)
OnBeforeUninstall(IDictionary)	Raises the BeforeUninstall event. (Inherited from Installer)
OnCommitted(IDictionary)	Raises the Committed event. (Inherited from Installer)
OnCommitting(IDictionary)	Raises the Committing event. (Inherited from Installer)
Rollback(IDictionary)	Restores the computer to the state it was in before the installation by rolling back the event log information that the installation procedure wrote to the registry.
ToString()	Returns a String containing the name of the Component, if any. This method should not be overridden. (Inherited from Component)
Uninstall(IDictionary)	Removes an installation by removing event log information from the registry.

Events

AfterInstall	Occurs after the Install(IDictionary) methods of all the installers in the Installers property have run. (Inherited from Installer)
AfterRollback	Occurs after the installations of all the installers in the Installers property are rolled back. (Inherited from Installer)
AfterUninstall	Occurs after all the installers in the Installers property perform their uninstallation operations. (Inherited from Installer)
BeforeInstall	Occurs before the Install(IDictionary) method of each installer in the installer collection has run. (Inherited from Installer)
BeforeRollback	Occurs before the installers in the Installers property are rolled back. (Inherited from Installer)
BeforeUninstall	Occurs before the installers in the Installers property perform their uninstall operations. (Inherited from Installer)
Committed	Occurs after all the installers in the Installers property have committed their installations. (Inherited from Installer)
Committing	Occurs before the installers in the Installers property commit their installations. (Inherited from Installer)
Disposed	Occurs when the component is disposed by a call to the Dispose() method. (Inherited from Component)

See also

• EventLog
• CreateEventSource
• Installutil.exe (Installer Tool)