Services View Settings

Project:The Services view (and the Services area for a component) is available in the following project types:

• Basic MSI
• DIM
• InstallScript MSI
• Merge Module
• MSI Database
• MSM Database
• Transform

Tip:The View Filter at the top of the Services view lets you select a component or feature whose service data you want to display in the view. The View Filter lists your project’s hierarchy of features, subfeatures, and components. Selecting a feature shows the services for all of the components in that feature.

The Services settings are organized into the following main categories:

• General Settings
• Install Settings
• Control Settings
• Configure Settings

Tip:You must be familiar with the technical details of your service before you can configure its settings.

General Settings

Use the General area to specify the component that you want to contain your service.

General Settings

Setting

Description

Component

Select the component that contains the service executable file, or click the ellipsis button (...) in this setting to create or select a component for the service executable file.

The service executable file should be the key file of its component. For more information, see Component Key Files.

In addition, the Remote Installation setting for the component must be set to Favor Local. For more information, see Setting a Component’s Remote Installation Setting.

Install Settings

Use the Install Settings area to specify whether you want the installation to install your service. If the service should be installed, also use these settings to specify information such as the display name and description, as well as when the service should be started.

Install Settings

Setting

Description

Enable Service Install

Specify whether the service should be installed at run time.

If you select No for this setting, any values that you entered for the remaining settings in the Install Settings section are deleted from the project. Note that when No is selected for this setting, the remaining settings in the Install Settings section are read-only.

Key Name

Enter a key name for the service. The key name is a database key; it is not displayed to end users.

Display Name

Enter the name that you want to be displayed in the service control manager for this service. If you leave this setting blank, the service’s name (that is, the text that is used for the name of your service’s subnode under the Advanced Settings node) is used.

When you type a value for this setting, you are creating a string entry and setting its initial value for all of the languages that are currently in the project. As an alternative to typing a new value, you can click the ellipsis button (...) in this setting to select an existing string. For more information, see Using String Entries in InstallShield.

Description

Enter a description of the service. This description is registered on the target system when the service is installed, and it is displayed in the service control manager’s Description column. It is also displayed in the Description box on the General tab of the service’s Properties dialog box.

When you type a value for this setting, you are creating a string entry and setting its initial value for all of the languages that are currently in the project. As an alternative to typing a new value, you can click the ellipsis button (...) in this setting to select an existing string. For more information, see Using String Entries in InstallShield.

Service Type

Select the type of service that you are installing. Available options are:

• Win32 that runs in its own process
• Win32 that shares a process

The WIN32_OWN_PROCESS type of service contains the code for only one service. The WIN32_SHARE_PROCESS type of service contains code for more than one service, enabling them to share code.

Interact with Desktop

Specify whether the service interacts with the desktop. If your service has a user interface, select Yes.

If you select Yes, the User Name setting must be left blank, since the service will be installed to run in the built-in LocalSystem account.

Start Type

Specify when to start the service. Available options are:

• Automatic—The service starts automatically when the system starts.
• On Demand—The service starts when the service is requested through the service control manager.
• Disabled—The service cannot be started.

Note that some services may support other start types (that is, during operating system initialization or by the operating system loader). However, these options are not available for the Start Type setting because the Windows Installer does not include support for them.

Error Control

Select the appropriate action that the service control manager should perform if the service fails to start. Available options are:

• Log the error and continue
• Log the error, display a message, and continue
• Log the error and restart

Abort Install on Failure

Specify whether the entire installation should fail if the service cannot be installed on the target system. The default value is No.

Note:If you select Yes for this setting and end users run the installation in silent or basic UI mode, Windows Installer 3 or later must be present on the target system.

Load Order Group

Enter the name of the load-ordering group, if any, of which this service is a member.

Dependencies

Enter any service or load-ordering groups that this service requires. The system attempts to start the required service or at least one member of the load-ordering group before starting this service.

Separate multiple dependencies with a comma (,).

You must precede the name of each load-ordering group with the SC_GROUP_IDENTIFIER—which is typically the plus sign (+)—so that the service control manager can distinguish it from a service.

User Name

Enter the account under which the service will be logged on. To install the service under the local system account, leave this setting blank. (Microsoft does not recommend installing services that impersonate the privileges of a single user.)

If the service type is Win32 that runs in its own process, the value that you enter should use the following format:

DomainName\UserName

If the service will be logged on under the built-in domain, you can use the following format:

.\UserName

Password

Enter a password for this service. Leave this setting blank if the User Name setting is empty—that is, when the service is logged on under the local system account. The password is not used if you have not specified a user name.

Start Parameters

Enter any command-line parameters or properties that are required to run the service.

Permissions

This setting lets you set permissions for your service.

To configure permissions, click the Add New Service Permissions button. InstallShield adds a new permission setting, plus additional rows of related settings under it. Configure each of the settings as necessary.

You may want to add multiple permission items if, for example, you want to pass different arguments during installation and uninstallation.

Note:The permission settings are supported beginning with Windows Installer 5. Earlier versions of Windows Installer ignore these settings.

An installation should not contain both the MsiLockPermissionsEx table and the LockPermissions table. If you use this Permissions setting, and the settings under it, you are configuring the MsiLockPermissionsEx table of the package. If Traditional Windows Installer handling is selected for the Locked-Down Permissions setting in the General Information view and you have set permissions for one or more files, folders, or registry keys in your project, you are configuring the LockPermissions table of the package.

Key Name

Enter a key name for the permissions. The key name is an internal name; it is not displayed to end users.

Note:The permission settings are supported beginning with Windows Installer 5. Earlier versions of Windows Installer ignore these settings.

An installation should not contain both the MsiLockPermissionsEx table and the LockPermissions table. If you use this Permissions setting, and the settings under it, you are configuring the MsiLockPermissionsEx table of the package. If Traditional Windows Installer handling is selected for the Locked-Down Permissions setting in the General Information view and you have set permissions for one or more files, folders, or registry keys in your project, you are configuring the LockPermissions table of the package.

Security Descriptor

Use valid security descriptor definition language (SDDL) to enter a valid SDDL string. For more information about SDDL, see the “Access Control” section of the Microsoft Windows Software Development Kit (SDK).

Tip:You can use angle brackets (for example, <DomainName\UserName>) or environment variables (for example, [%UserDomain][%UserName]) to indicate the domain and user name of the user whose account SID is going to be determined at run time.

Note:The permission settings are supported beginning with Windows Installer 5. Earlier versions of Windows Installer ignore these settings.

An installation should not contain both the MsiLockPermissionsEx table and the LockPermissions table. If you use this Permissions setting, and the settings under it, you are configuring the MsiLockPermissionsEx table of the package. If Traditional Windows Installer handling is selected for the Locked-Down Permissions setting in the General Information view and you have set permissions for one or more files, folders, or registry keys in your project, you are configuring the LockPermissions table of the package.

Condition

This setting lets you enter a statement that the installation must evaluate before securing permissions for the service on the target system. The permissions are not configured if the condition evaluates to false. However, the permissions are configured if the condition evaluates to true, assuming that the service’s feature is installed.

To create a condition for the permissions, click the ellipsis button (...) in this setting. For more information, see Condition Builder Dialog Box.

Note:The permission settings are supported beginning with Windows Installer 5. Earlier versions of Windows Installer ignore these settings.

An installation should not contain both the MsiLockPermissionsEx table and the LockPermissions table. If you use this Permissions setting, and the settings under it, you are configuring the MsiLockPermissionsEx table of the package. If Traditional Windows Installer handling is selected for the Locked-Down Permissions setting in the General Information view and you have set permissions for one or more files, folders, or registry keys in your project, you are configuring the LockPermissions table of the package.

Control Settings

Use the Control Settings area to specify how you want to control the service when this component is installed or uninstalled. For example, before updating a running service, your installation may need to delete it.

Control Settings

Setting

Description

Events

This setting lets you specify one or more control events that are required for your service.

To add an event, click the Add New Service Control Event button. InstallShield adds a new event setting, plus additional rows of related settings under it. Configure each of the settings as necessary.

You can place all of your control options in a single event. However, you might need to create additional events if, for example, you want to pass different arguments during installation and uninstallation.

Key Name

Enter a key name for the control event. The key name is an internal name; it is not displayed to end users.

Operation Time

To specify how you would like to schedule the operation that occurs for the service at run time, select the appropriate option for each of the following settings:

• Install Start—Specify whether you want to start the service during installation. If you select Yes, the service starts when the installation reaches the StartServices action in the Installation sequence.
• Install Stop—Specify whether you want to stop the service during installation. If you select Yes, the service stops when the installation reaches the StopServices action in the Installation sequence.
• Install Delete—Specify whether you want to delete the service during installation. If you select Yes, the service is deleted when the installation reaches the DeleteServices action in the Installation sequence.
• Uninstall Start—Specify whether you want to start the service during uninstallation. If you select Yes, the service starts when the uninstallation reaches the StartServices action in the Installation sequence.
• Uninstall Stop—Specify whether you want to stop the service during uninstallation. If you select Yes, the service stops when the uninstallation reaches the StopServices action in the Installation sequence.
• Uninstall Delete—Specify whether you want to delete the service during uninstallation. If you select Yes, the service is deleted when the uninstallation reaches the DeleteServices action in the Installation sequence.

Wait Type

Specify how Windows Installer should proceed after initiating the control event. Available options are:

• Wait for the event to complete—Windows Installer waits for the event—starting, stopping, or deleting—to finish, up to a maximum of 30 seconds, before proceeding. Select this option if the event is critical to the installation and you want to allow additional time for the event to return a failure error.
• Wait for the SCM—Windows Installer waits for the service control manager to report that the service is in a pending state.

The service control manager maintains the system’s database of services and exposes an interface for controlling these services.

Service Argument

Specify the arguments that you want to be passed to the service. Separate multiple arguments with a comma (,).

Configure Settings

Use the Configure Settings area to specify how to customize the service that is included in the selected component.

Note:The configuration settings are supported beginning with Windows Installer 5. Earlier versions of Windows Installer ignore these settings.

Configure Settings

Setting

Description

Events

This setting lets you specify one or more configuration changes that are required for your service.

To add an event, click the Add New Service Configuration Event button. InstallShield adds a new event setting, plus additional rows of related settings under it. Configure each of the settings as necessary.

Note:This setting is supported beginning with Windows Installer 5. Earlier versions of Windows Installer ignore this setting.

Key Name

Enter a key name for the configuration event. The key name is an internal name; it is not displayed to end users.

Note:This setting is supported beginning with Windows Installer 5. Earlier versions of Windows Installer ignore this setting.

Run Time

To specify when you would like the service configuration event to occur at run time, select the appropriate option for each of the following settings:

• During Install—Specify whether you want the event to occur during installation.
• During Uninstall—Specify whether you want the event to occur during uninstallation.
• During Reinstall—Specify whether you want the event to occur during reinstallation.

Note:This setting is supported beginning with Windows Installer 5. Earlier versions of Windows Installer ignore this setting.

Configuration Type

Specify what configuration change should be made to the service. The change takes effect the next time that the system is started. Available options are:

• Configure time delay of an auto-start—This option is applicable if the service is an installed auto-start service, or if Automatic is selected for the Start Type setting in the Install Settings area. If you select this option, click the ellipsis button (...) in the Arguments setting to indicate the time delay.
• Configure when to run recovery actions—If you select this option, click the ellipsis button (...) in the Arguments setting to specify when to run the recovery actions for the selected service.
• Add a service SID type to the process token—If you select this option, click the ellipsis button (...) in the Arguments setting to indicate the appropriate security identifier (SID) type that you want to add for the service.
• Change list of required privileges—If you select this option, click the ellipsis button (...) in the Arguments setting to select the appropriate privileges.
• Configure SCM pre-shutdown delay—If you select this option, enter the length of the time delay (in milliseconds) in the Arguments setting. To reset the time delay to the default of 3 minutes, leave the Arguments setting blank. The service control manager waits for the specified period of time after sending the SERVICE_CONTROL_PRESHUTDOWN notification to the service.

Note that each option has its own set of corresponding values for the Arguments setting. Therefore, if you change the value for the Arguments setting and next change the value for the Configuration Type setting, you may need to change the value for the Arguments setting again.

Note:This setting is supported beginning with Windows Installer 5. Earlier versions of Windows Installer ignore this setting.

Arguments

To specify the value that corresponds with the configuration change that you selected in the Configuration Type setting, click the ellipsis button (...).

Note:This setting is supported beginning with Windows Installer 5. Earlier versions of Windows Installer ignore this setting.

Recovery Actions

This setting lets you specify one or more recovery actions that are to be run after the service fails.

To add a recovery action, click the Add New Recovery Action button. InstallShield adds a new recovery action setting, plus additional rows of related settings under it. Configure each of the settings as necessary.

Note:This setting is supported beginning with Windows Installer 5. Earlier versions of Windows Installer ignore this setting.

Key Name

Enter a key name for the recovery action. The key name is an internal name; it is not displayed to end users.

Note:This setting is supported beginning with Windows Installer 5. Earlier versions of Windows Installer ignore this setting.

Run Time

To specify when the system should run the recovery action after the service has failed, select the appropriate option for each of the following settings:

• During Install—Run the action when the service’s component is being installed.
• During Uninstall—Run the action when the service’s component is being uninstalled.
• During Reinstall—Run the action when the service’s component is being reinstalled.

Note:This setting is supported beginning with Windows Installer 5. Earlier versions of Windows Installer ignore this setting.

Reset Period

Specify the amount of time (in seconds) between the reset intervals for the service’s failure count.

The service control manager counts the number of times that the service has failed since the system was last restarted. When this interval has elapsed, the count is reset to the number 0 if the service has not failed during the reset period. When the service fails, the system performs an action that is specified for the SCM Actions setting. The appropriate action is determined by subtracting the number 1 from the number of failures since the last system restart. For example, if the action fails a sixth time, the system performs the fifth action type that is listed in the SCM Actions setting. If actions are not specified in the SCM Actions setting, the Reset Period setting is ignored.

To indicate that the failure count should never be reset, leave this setting blank.

Note:This setting is supported beginning with Windows Installer 5. Earlier versions of Windows Installer ignore this setting.

Reboot Message

Specify the message that should be displayed before the computer is restarted in response to a service control manager action of Reboot Computer. Note that Reboot Computer must be listed as one of the action types for the SCM Actions setting; otherwise, the Reboot Message setting is ignored.

When you type a value for this setting, you are creating a string entry and setting its initial value for all of the languages that are currently in the project. As an alternative to typing a new value, you can click the ellipsis button (...) in this setting to select an existing string. For more information, see Using String Entries in InstallShield.

Note:This setting is supported beginning with Windows Installer 5. Earlier versions of Windows Installer ignore this setting.

Run Command

Specify the command line that should be run in response to a service control manager action of Run Command. Use the absolute path; UNC paths are not supported. For example, enter C:\myscripts\recovery.cmd, rather than \\computername\c$\myscripts\recovery.cmd. Programs or scripts that you specify should not require input from end users.

The command line that you specify is used by a new process that runs under the same account as the service.

Note that Run Command must be listed as one of the action types for the SCM Actions setting; otherwise, the Run Command setting is ignored.

When you type a value for this setting, you are creating a string entry and setting its initial value for all of the languages that are currently in the project. As an alternative to typing a new value, you can click the ellipsis button (...) in this setting to select an existing string. For more information, see Using String Entries in InstallShield.

Note:This setting is supported beginning with Windows Installer 5. Earlier versions of Windows Installer ignore this setting.

SCM Actions

This setting lets you specify one or more service control manager actions that should occur if the service fails. The actions are performed in the order that they are listed under this setting.

To add an action, click the Add New SCM Action Event button. InstallShield adds a new Type setting, plus a Delay setting under it. Configure both of the settings as necessary.

Note:This setting is supported beginning with Windows Installer 5. Earlier versions of Windows Installer ignore this setting.

Type

Specify the type of action that the service control manager should perform if the service fails. Available options are:

• Run Command
• Reboot Computer
• Take No Action
• Restart Service

Note:The Restart Service action is not supported with .msi packages. Including this action with an .msi package will result in Windows Installer Error 1939.

Note:The Type setting is supported beginning with Windows Installer 5. Earlier versions of Windows Installer ignore this setting.

Delay

Specify the time (in milliseconds) that the service control manager should wait before performing the action that is specified in the Type setting.

Note:This setting is supported beginning with Windows Installer 5. Earlier versions of Windows Installer ignore this setting.