Export (0) Print
Expand All

ServiceInstaller Class

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

For a list of all members of this type, see ServiceInstaller Members.

System.Object
   System.MarshalByRefObject
      System.ComponentModel.Component
         System.Configuration.Install.Installer
            System.Configuration.Install.ComponentInstaller
               System.ServiceProcess.ServiceInstaller

[Visual Basic]
Public Class ServiceInstaller
   Inherits ComponentInstaller
[C#]
public class ServiceInstaller : ComponentInstaller
[C++]
public __gc class ServiceInstaller : public ComponentInstaller
[JScript]
public class ServiceInstaller extends ComponentInstaller

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

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, instantiate one ServiceProcessInstaller instance per service application, and one ServiceInstaller instance for each service in the application. Finally, add the ServiceProcessInstaller instance and the ServiceInstaller instances to your project installer class.

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.

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.

Example

[Visual Basic, C#, C++] 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.

[Visual Basic, C#, C++] 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.

[Visual Basic, C#, C++] Normally, you would not instantiate 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.

[Visual Basic] 
Imports System
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
End Class

' </Sn

[C#] 
using System;
using System.Collections;
using System.Configuration.Install;
using System.ServiceProcess;
using System.ComponentModel;

[RunInstallerAttribute(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);
   }
}


[C++] 
#using <mscorlib.dll>
#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;

[RunInstallerAttribute(true)]
public __gc class MyProjectInstaller: public Installer{
private:
   ServiceInstaller* serviceInstaller1;
   ServiceInstaller* serviceInstaller2;
   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 = S"Hello-World Service 1";
      serviceInstaller2->ServiceName = S"Hello-World Service 2";

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

[JScript] No example is available for JScript. To view a Visual Basic, C#, or C++ example, click the Language Filter button Language Filter in the upper-left corner of the page.

Requirements

Namespace: System.ServiceProcess

Platforms: Windows NT Server 4.0, Windows NT Workstation 4.0, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family

Assembly: System.Serviceprocess (in System.Serviceprocess.dll)

See Also

ServiceInstaller Members | System.ServiceProcess Namespace | ServiceBase.ServiceName | ServiceProcessInstaller | ServiceBase | EventLog

Show:
© 2014 Microsoft