ServiceInstaller Class

Reference

Definition

Namespace:: System.ServiceProcess

Assembly:: System.ServiceProcess.dll

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Installs a class that extends ServiceBase to implement a service. This class is called by the install utility when installing a service application.

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

public class ServiceInstaller : System.Configuration.Install.ComponentInstaller

type ServiceInstaller = class
    inherit ComponentInstaller

Public Class ServiceInstaller
Inherits ComponentInstaller

Inheritance: Object

MarshalByRefObject

Component

Installer

ComponentInstaller
ServiceInstaller

Examples

The following example creates a project installer, called MyProjectInstaller, which inherits from Installer. It is assumed there is a service executable that contains two services, "Hello-World Service 1" and "Hello-World Service 2". Within the constructor for MyProjectInstaller (which would be called by the install utility), ServiceInstaller objects are created for each of these services, and a ServiceProcessInstaller is created for the executable. For the install utility to recognize MyProjectInstaller as a valid installer, the RunInstallerAttribute attribute is set to true.

Optional properties are set on the process installer and the service installers before the installers are added to the Installers collection. When the install utility accesses MyProjectInstaller, the objects added to the Installers collection through a call to InstallerCollection.Add will be installed in turn. During the process, the installer maintains state information indicating which objects have been installed, so each can be backed out in turn, if an installation failure occurs.

Normally, you would not create an instance of your project installer class explicitly. You would create it and add the RunInstallerAttribute attribute to the syntax, but it is the install utility that actually calls, and therefore instantiates, the class.

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

using namespace System;
using namespace System::Collections;
using namespace System::Configuration::Install;
using namespace System::ServiceProcess;
using namespace System::ComponentModel;

[RunInstaller(true)]
public ref class MyProjectInstaller : public Installer
{
private:
    ServiceInstaller^ serviceInstaller1;
    ServiceInstaller^ serviceInstaller2;
    ServiceProcessInstaller^ processInstaller;

public:
    MyProjectInstaller()
    {
        // Instantiate installers for process and services.
        processInstaller = gcnew ServiceProcessInstaller;
        serviceInstaller1 = gcnew ServiceInstaller;
        serviceInstaller2 = gcnew ServiceInstaller;

        // The services run under the system account.
        processInstaller->Account = ServiceAccount::LocalSystem;

        // The services are started manually.
        serviceInstaller1->StartType = ServiceStartMode::Manual;
        serviceInstaller2->StartType = ServiceStartMode::Manual;

        // ServiceName must equal those on ServiceBase derived classes.
        serviceInstaller1->ServiceName = "Hello-World Service 1";
        serviceInstaller2->ServiceName = "Hello-World Service 2";

        // Add installers to collection. Order is not important.
        Installers->Add( serviceInstaller1 );
        Installers->Add( serviceInstaller2 );
        Installers->Add( processInstaller );
    }

    static void Main()
    {
        Console::WriteLine("Usage: InstallUtil.exe [<service>.exe]");
    }
};

int main()
{
    MyProjectInstaller::Main();
}

using System;
using System.Collections;
using System.Configuration.Install;
using System.ServiceProcess;
using System.ComponentModel;

[RunInstaller(true)]
public class MyProjectInstaller : Installer
{
    private ServiceInstaller serviceInstaller1;
    private ServiceInstaller serviceInstaller2;
    private ServiceProcessInstaller processInstaller;

    public MyProjectInstaller()
    {
        // Instantiate installers for process and services.
        processInstaller = new ServiceProcessInstaller();
        serviceInstaller1 = new ServiceInstaller();
        serviceInstaller2 = new ServiceInstaller();

        // The services run under the system account.
        processInstaller.Account = ServiceAccount.LocalSystem;

        // The services are started manually.
        serviceInstaller1.StartType = ServiceStartMode.Manual;
        serviceInstaller2.StartType = ServiceStartMode.Manual;

        // ServiceName must equal those on ServiceBase derived classes.
        serviceInstaller1.ServiceName = "Hello-World Service 1";
        serviceInstaller2.ServiceName = "Hello-World Service 2";

        // Add installers to collection. Order is not important.
        Installers.Add(serviceInstaller1);
        Installers.Add(serviceInstaller2);
        Installers.Add(processInstaller);
    }

    public static void Main()
    {
        Console.WriteLine("Usage: InstallUtil.exe [<service>.exe]");
    }
}

Imports System.Collections
Imports System.Configuration.Install
Imports System.ServiceProcess
Imports System.ComponentModel

<RunInstallerAttribute(True)> _
Public Class MyProjectInstaller
    Inherits Installer
    Private serviceInstaller1 As ServiceInstaller
    Private serviceInstaller2 As ServiceInstaller
    Private processInstaller As ServiceProcessInstaller    
    
    Public Sub New()
        ' Instantiate installers for process and services.
        processInstaller = New ServiceProcessInstaller()
        serviceInstaller1 = New ServiceInstaller()
        serviceInstaller2 = New ServiceInstaller()
        
        ' The services will run under the system account.
        processInstaller.Account = ServiceAccount.LocalSystem
        
        ' The services will be started manually.
        serviceInstaller1.StartType = ServiceStartMode.Manual
        serviceInstaller2.StartType = ServiceStartMode.Manual
        
        ' ServiceName must equal those on ServiceBase derived classes.            
        serviceInstaller1.ServiceName = "Hello-World Service 1"
        serviceInstaller2.ServiceName = "Hello-World Service 2"
        
        ' Add installers to collection. Order is not important.
        Installers.Add(serviceInstaller1)
        Installers.Add(serviceInstaller2)
        Installers.Add(processInstaller)
    End Sub

    Public Shared Sub Main()
        Console.WriteLine("Usage: InstallUtil.exe [<service>.exe]")
    End Sub
End Class

Remarks

The ServiceInstaller does work specific to the service with which it is associated. It is used by the installation utility to write registry values associated with the service to a subkey within the HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services registry key. The service is identified by its ServiceName within this subkey. The subkey also includes the name of the executable or .dll to which the service belongs.

To install a service, create a project installer class that inherits from the Installer class, and set the RunInstallerAttribute attribute on the class to true. Within your project, create one ServiceProcessInstaller instance per service application, and one ServiceInstaller instance for each service in the application. Within your project installer class constructor, set the installation properties for the service using the ServiceProcessInstaller and ServiceInstaller instances, and add the instances to the Installers collection.

Note

It is recommended that you use the constructor for adding installer instances; however, if you need to add to the Installers collection in the Install method, be sure to perform the same additions to the collection in the Uninstall method.

For all classes deriving from the Installer class, the state of the Installers collection must be the same in the Install and Uninstall methods. However, you can avoid the maintenance of the collection across the Install and Uninstall methods if you add installer instances to the Installers collection in your custom installer class constructor.When the install utility is called, it looks for the RunInstallerAttribute attribute. If the attribute is true, the utility installs all the services that were added to the Installers collection that were associated with your project installer. If RunInstallerAttribute is false or does not exist, the install utility ignores the project installer.

The ServiceProcessInstaller associated with your project installation class installs information common to all ServiceInstaller instances in the project. If this service has anything that separates it from the other services in the installation project, that service-specific information is installed by this method.

Note

It is crucial that the ServiceName be identical to the ServiceBase.ServiceName of the class you derived from ServiceBase. Normally, the value of the ServiceBase.ServiceName property for the service is set within the Main() function of the service application's executable. The Service Control Manager uses the ServiceInstaller.ServiceName property to locate the service within this executable.

You can modify other properties on the ServiceInstaller either before or after adding it to the Installers collection of your project installer. For example, a service's StartType may be set to start the service automatically at reboot or require a user to start the service manually.

Normally, you will not call the methods on ServiceInstaller within your code; they are generally called only by the install utility. The install utility automatically calls the ServiceProcessInstaller.Install and ServiceInstaller.Install methods during the installation process. It backs out failures, if necessary, by calling Rollback (or ServiceInstaller.Rollback) on all previously installed components.

The installation utility calls Uninstall to remove the object.

An application's install routine maintains information automatically about the components already installed, using the project installer's Installer.Context. This state information is continuously updated as the ServiceProcessInstaller instance, and each ServiceInstaller instance is installed by the utility. It is usually unnecessary for your code to modify state information explicitly.

When the installation is performed, it automatically creates an EventLogInstaller to install the event log source associated with the ServiceBase derived class. The Log property for this source is set by the ServiceInstaller constructor to the computer's Application log. When you set the ServiceName of the ServiceInstaller (which should be identical to the ServiceBase.ServiceName of the service), the Source is automatically set to the same value. In an installation failure, the source's installation is rolled-back along with previously installed services.

The Uninstall method tries to stop the service if it is running. Whether this succeeds or not, Uninstall undoes the changes made by Install. If a new source was created for event logging, the source is deleted.

Constructors

ServiceInstaller()

Initializes a new instance of the ServiceInstaller class.

Properties

CanRaiseEvents	Gets a value indicating whether the component can raise an event. (Inherited from Component)
Container	Gets the IContainer that contains the Component. (Inherited from Component)
Context	Gets or sets information about the current installation. (Inherited from Installer)
DelayedAutoStart	Gets or sets a value that indicates whether the service should be delayed from starting until other automatically started services are running.
Description	Gets or sets the description for the service.
DesignMode	Gets a value that indicates whether the Component is currently in design mode. (Inherited from Component)
DisplayName	Indicates the friendly name that identifies the service to the user.
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)
Parent	Gets or sets the installer containing the collection that this installer belongs to. (Inherited from Installer)
ServiceName	Indicates the name used by the system to identify this service. This property must be identical to the ServiceName of the service you want to install.
ServicesDependedOn	Indicates the services that must be running for this service to run.
Site	Gets or sets the ISite of the Component. (Inherited from Component)
StartType	Indicates how and when this service is started.

Methods

Commit(IDictionary)	When overridden in a derived class, completes the install transaction. (Inherited from Installer)
CopyFromComponent(IComponent)	Copies properties from an instance of ServiceBase to this installer.
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()	Obsolete. 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()	Obsolete. Obtains a lifetime service object to control the lifetime policy for this instance. (Inherited from MarshalByRefObject)
Install(IDictionary)	Installs the service by writing service application information to the registry. This method is meant to be used by installation tools, which process the appropriate methods automatically.
IsEquivalentInstaller(ComponentInstaller)	Indicates whether two installers would install the same service.
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)	Rolls back service application information written to the registry by the installation procedure. This method is meant to be used by installation tools, which process the appropriate methods automatically.
ToString()	Returns a String containing the name of the Component, if any. This method should not be overridden. (Inherited from Component)
Uninstall(IDictionary)	Uninstalls the service by removing information about it 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)

Applies to

Del via