System.Configuration.Install 1.0.5000.0 2.0.0.0 System.Configuration.Install.ComponentInstaller

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

Use the 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.

The Security log is read-only.

The installer creates the event source that you specify in the property and registers it for the event log specified in property. This behavior is similar to calling on the component.

Use the and 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 , or using the 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 , and set the for the class to true. Within your project, create an 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 . If it is true, the tool installs all the items in the collection that are associated with your project installer. If is false, the tool ignores the project installer.

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

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

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

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

- Constructor
  To be added.

  Initializes a new instance of the class.

  1.0.5000.0
  2.0.0.0
- Property
  2.0.0.0
  System.Runtime.InteropServices.ComVisible(false)
  System.Int32 To be added.

  Use the and properties to write events with localized category strings. The Event Viewer displays the category for an event entry, if you supply a category when you write the event. Event log categories are application-defined strings that help filter events, or provide information on an event. For example, your application can define separate categories for different components or different operations.

  Event categories are optional; if your application does not use categories, do not set the and properties.

  For details about defining event messages and building event resource files, see the "Message Compiler" topic in the Platform SDK documentation at http://msdn.microsoft.com.

  Gets or sets the number of categories in the category resource file.

- Property
  2.0.0.0
  System.Runtime.InteropServices.ComVisible(false)
  System.ComponentModel.TypeConverter("System.Diagnostics.Design.StringValueConverter, System.Design, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")
  System.ComponentModel.Editor("System.Windows.Forms.Design.FileNameEditor, System.Design, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a", "System.Drawing.Design.UITypeEditor, System.Drawing, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")
  System.String To be added.

  Use the and properties to write events with localized category strings. The Event Viewer displays the category for an event entry if you supply a category when you write the event. Event log categories are application-defined strings that help filter events, or provide information about an event. For example, your application might have separate categories for different components or different operations.

  Event categories are optional; if your application does not use categories, do not set the and properties.

  For details about defining event messages and building event resource files, see the "Message Compiler" topic in the Platform SDK documentation at http://msdn.microsoft.com.

  Gets or sets the path of the resource file that contains category strings for the source.

- Method
  System.Void ``

  The component specified by the parameter must be an ; otherwise, an exception is thrown.

  Typically, you do not call the methods of the from within your code; they are generally called only by the Installer Tool (Installutil.exe). is used by Installutil.exe to set the property values for the to the values of an existing .

  If the of the that is passed in is an empty string (""), you must set the property to a valid value before the installer executes.

  Copies the property values of an component that are required at installation time for an event log.

  An to use as a template for the . 1.0.5000.0 2.0.0.0
- Method
  System.Void ``

  The method writes event log information to the registry, and associates the event log with a log that is specified by the property. If the log does not already exist (and a source is specified), creates a log and associates the new source with it.

  Typically, you do not call the methods of the from within your code; they are generally called only by the Installer Tool (Installutil.exe). The tool automatically calls the method during the installation process to write registry information that is associated with the event log being installed. Installation is transactional, so if there is a failure of any installation project component during the installation, all the previously-installed components are rolled back to their pre-installation states. This is accomplished by calling each component's method.

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

  An application's install routine uses the project installer's property to automatically maintain information about the components that have already been installed. This state information, which is passed to as the parameter, is continuously updated as the tool installs each . Usually, it is not necessary for your code to explicitly modify this state information.

  Performs the installation and writes event log information to the registry.

  An used to save information needed to perform a rollback or uninstall operation. 1.0.5000.0 2.0.0.0
- Method
  System.Boolean ``

  Typically, you do not call the methods of the from within your code; they are generally called only by the Installer tool (Installutil.exe).

  Determines whether an installer and another specified installer refer to the same source.

  true if this installer and the installer specified by the parameter would install or uninstall the same source; otherwise, false.

  The installer to compare. 1.0.5000.0 2.0.0.0
- Property
  System.ComponentModel.TypeConverter("System.Diagnostics.Design.StringValueConverter, System.Design, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")
  System.String To be added.

  You can use the property to associate the source you specify in the property with either an existing log or a new log on the local computer. The Installer Tool (Installutil.exe) uses this information to map the source to the log in the computer's registry. Applications and services should write to the Application log or a custom log. Device drivers should write to the System log.

  To write entries to an event log, you must create a source and register it with an event log. An event source can only write to one log at a time. The installer uses the value of the property to register your application with the event log as a valid source of entries. If you do not specify a log name before the installer runs, the installer registers your source to the Application log. If you specify a new source and an existing log, the installer creates a new event source and associates it with the log you specify. If you specify both a new source and a new log, the installer associates the new source with the new log in the registry, but the log is not created until the first entry is written to it.

  The operating system stores event logs as files. When you use or the method to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension.

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

  For more detailed information about the behaviors of event logs and sources, see the class documentation for the and properties.

  Gets or sets the name of the log to set the source to.

  1.0.5000.0
  2.0.0.0
- Property
  2.0.0.0
  System.Runtime.InteropServices.ComVisible(false)
  System.ComponentModel.TypeConverter("System.Diagnostics.Design.StringValueConverter, System.Design, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")
  System.ComponentModel.Editor("System.Windows.Forms.Design.FileNameEditor, System.Design, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a", "System.Drawing.Design.UITypeEditor, System.Drawing, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")
  System.String To be added.

  Use the property to configure an event log source to write localized event messages. Event messages are application-defined strings that describe the event to the user.

  Your application can write event log entries using resource identifiers. A resource identifier indexes a message located in the . The Event Viewer uses the resource identifier to find and display the corresponding string from the localized resource file based on current language settings.

  The event source must be configured either for writing localized entries or for writing direct strings. Use the method to write localized entries for a source configured with a message resource file.

  If your application writes event message strings directly, rather than using a resource identifier in a localized resource file, do not set the property.

  If the property is not the local computer identifier ("."), the .NET Framework assumes that the resource file is on a remote computer. If the property value contains a drive letter, the resource file is assumed to be on the \\<machinename>\<drive>$ share (for example, \\server\c$). If the value contains the string %systemroot%, the resource file is assumed to be on the \\<machinename>\admin$ share (for example, \\server\admin$).

  For details about defining event messages and building event resource files, see the "Message Compiler" topic in the Platform SDK documentation at http://msdn.microsoft.com.

  Gets or sets the path of the resource file that contains message formatting strings for the source.

- Property
  2.0.0.0
  System.Runtime.InteropServices.ComVisible(false)
  System.ComponentModel.TypeConverter("System.Diagnostics.Design.StringValueConverter, System.Design, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")
  System.ComponentModel.Editor("System.Windows.Forms.Design.FileNameEditor, System.Design, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a", "System.Drawing.Design.UITypeEditor, System.Drawing, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")
  System.String To be added.

  Use the property to configure an event log source to write localized event messages with inserted parameter strings. Each localized event message specified in the property can contain placeholders for insertion strings. These placeholders are used to specify the position and resource identifier for a language-independent string within the event message. The Event Viewer replaces the placeholders with the corresponding strings from the and formats the event log message for the localized event entry.

  For example, the following section of a message text file defines a string with a parameter placeholder:

  `MessageId = 1501 Severity = Success Facility = Application SymbolicName = COMPONENT_STARTING Language=English Component %%6050 is starting. .`

  Within the parameter resource file, the insertion string must be defined with the resource identifier that corresponds to the placeholder, as shown below:

  `MessageId = 6050 Severity = Success Facility = Application SymbolicName = COMPONENT_NAME_MSGID Language=English TRIGGER.EXE .`

  The event source must be configured either for writing localized entries or for writing direct strings. Use the method to write localized entries for a source configured with a message resource file.

  If your application writes event message strings directly to the event log, or if your does not contain messages with parameter insertion placeholders, do not set the property.

  For details about defining event messages and building event resource files, see the "Message Compiler" topic in the Platform SDK documentation at http://msdn.microsoft.com.

  Gets or sets the path of the resource file that contains message parameter strings for the source.

- Method
  System.Void ``

  The method undoes the effects of the method. is called if the installation of any component in the installation project fails. The method creates or sets the properties for an event log and event source. either deletes the event log and source or resets the properties of a pre-existing source to its pre-installation values.

  Typically, you do not call the methods of the from within your code; they are generally called only by the Installer Tool (Installutil.exe). The tool calls the method, when this or another component has failed to install, to undo any changes that the installation process has already made.

  An application's install routine uses the project installer's property to automatically maintain information about the components that have already been installed. This state information, which is passed to as the parameter, is continuously updated as the tool rolls back each . Usually, it is not necessary for your code to explicitly modify this state information.

  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.

  An that contains the pre-installation state of the computer. 1.0.5000.0 2.0.0.0
- Property
  System.ComponentModel.TypeConverter("System.Diagnostics.Design.StringValueConverter, System.Design, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")
  System.String To be added.

  The event source indicates what logs the event. It is often the name of the application, or the name of a component within a large application.

  The installer uses the value of the property to register your application with the event log as a valid source of entries. A new source name cannot match an existing source name or an existing event log name. Each source can only write to one event log at a time; however, your application can use multiple sources to write to multiple event logs. For example, your application might require multiple sources configured for different event logs or different resource files.

  Applications and services should write to the Application log or a custom log. Device drivers should write to the System log. If you do not specify a log name before the installer runs, the installer registers your source to the Application log. If you specify the name of a log that does not exist, the system registers the to that log, but the log is not created until the first entry is written to it.

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

  For more detailed information about the behaviors of event logs and sources, see the class documentation for the and properties.

  Gets or sets the source name to register with the log.

  1.0.5000.0
  2.0.0.0
- Method
  System.Void ``

  If the property value is Remove, the method deletes the source and the associated log that the installer created if the and properties specified the creation of a new event log and source.

  Typically, you do not call the methods of the from within your code; they are generally called only by the Installer Tool (Installutil.exe) in uninstall mode. The tool automatically calls the method to restore the parts of the system that were affected by the installation to their pre-installation states. This includes deleting registry information that is associated with the event log being uninstalled.

  An application's uninstall routine uses the project installer's property to automatically maintain information about the components that have already been uninstalled. This state information, which is passed to as the parameter, is continuously updated as the tool uninstalls each . Usually, it is not necessary for your code to explicitly modify this state information.

  Removes an installation by removing event log information from the registry.

  An that contains the pre-installation state of the computer. 1.0.5000.0 2.0.0.0
- Property
  System.ComponentModel.DefaultValue(System.Configuration.Install.UninstallAction.Remove)
  System.Configuration.Install.UninstallAction To be added.

  When you install an event log, you can optionally connect it to an existing log. If you do so, you must decide whether the log should return to its pre-installation state, or remain in its current, post-installation state. If you elect to return the event log to its pre-installation state, changes to the event log entries at installation are not restored. You can reset only the event log properties that are associated with the to their pre-installation values.

  Gets or sets a value that indicates whether the Installer Tool (Installutil.exe) should remove the event log or leave it in its installed state at uninstall time.

  1.0.5000.0
  2.0.0.0