Service manipulation objects come along with a quite substantial set of setting options. In order to provide a clean and easy to master interface for these objects, the edit service area is separated into four activity blocks:
Whilst basic properties are always available for editing, the other settings are grouped in tabs users have to call manually.
Basic Properties
Service Name
This property is the name of the service on the target machine.
•If a service is created, the name will be set for internal service recognition and handling.
•If a service is controlled, the name used in this value has to match the name of the controlled service on the target device. The matching is executed case insensitive.
Service names may consist of max. 256 alphanumerical characters. It is not allowed to use slash ("/") and back-slash ("\") within service names.
Component
Each service manipulation item needs a component relation.
•For service creations, the key path of the related component must be the executable for the new service. Additionally, the service is only created if the component is actually installed during Installer sequences.
•For service controls, the component decides whether the service control task is executed during the Installer sequences.
Please keep in mind that the default component RayPack selects when the service manipulation object is added to the packaging project will very likely not be the one desired for the target package. Make sure to adjust this setting to the correct component!
Tab: Create
|
Note: The properties users can manipulate within this tab are not of relevance for service control items.
However, to turn a controller item into a service manipulation object that actually creates a service, users may deactivate the Create Service checkbox available within this tab.
Users may likewise turn a service control item into a service creator object by activating the Create Service checkbox available within this tab.
If the manipulation type is switched, users have to check the service manipulation object regarding the existence and validity of all required settings and references. Especially for control items that have been turned into creator items, the key path file status of the related component must be verified towards the correct service executable. |
Create Service
This option is active when the service manipulation item is designed to create a new service on the target machine.
It is not possible to deactivate this checkbox until a service manipulation item has been extended with a set of control commands (see below)
Display name
This is the localizable service name as it will be displayed for users on the target system.
Description
The description will be visible in the service management interface of the operating system on the target machine.
Executable
This read only field displays the executable file derived from the key path value of the related component. If this field is empty, the component does not contain a suiting key path file yet.
Arguments
Add parameters to the command line used to run the service. If more than one parameter is added, they have to be separated by null ("[~]").
Toggle Group: Properties
Start-up type
The option selected here is translated into a set of bit flags for service start-up control.
•Automatic - the service starts automatically with the operating system
•Manual - the service starts if and when the service control manager calls the StartService function.
•Disabled - the service cannot be started any more.
Error control
The option selected here is translated into a set of bit flags which control the reaction triggered on service start-up errors on the target machine.
•Log and continue - logs the error and continues with the start-up operation.
•Log and show message - logs the error, displays a message box and continues the start-up operation.
•Log and restart service - logs the error if it is possible and the system is restarted with the last configuration known to be good. If the last-known-good configuration is being started, the start-up operation fails.
If the checkbox "Abort install on error" is active, the installation of the target package itself will be aborted if the service could not be created successfully.
Service type
Services may run as a separate process, or as a service program with shared code components in the same process. Please refer to the MSDN documentation about service programs for details on how to pick the right option.
Interaction
This checkbox is used to mark services that interact with the desktop. If interaction is allowed is controlled by the security mechanisms of the target devices operating system.
Please note that the Login property within the credentials section must be set to "LocalSystem" or null ("[~]") when using this option.
Load order group
A Service Group is a collection of similar services that are loaded together at start-up. Entering a value into the Load order group input field indicates that the new service is added to the specified group.
Dependencies
Enter the names of service groups or individual services that must be started on the target device before the current service item may be started. If several dependencies have to be entered, separation by Null ("[~]") is due. Please refer to the MSDN documentation for details on how to handle complex dependency notations.
Toggle Group: Credentials
Login
The user profile used to run the service. Depending on the service type and interactivity settings, the login value must either be noted including the domain name (DomainName\Username or .\UserName for built-in domain users), or has to be represented by "LocalSystem" or null ("[~]").
Password
The password that matches the login user name defined above.
Toggle Group: Permissions
|
Note: Permission handling is not available for service manipulation items within packaging projects that use a Windows Installer schema below 500. Please set the Installer schema via the Summary information view available within the Setup organisation section of the Visual Designer mode. |
Within the permissions section, users are able to add permission definitions which are added to the MsiLockPermissionsEx Installer database table. Click on the Add button to create a new combination of Security Descriptor Definition and condition string. RayPack allows to add several permission handling items to a service.
Removing a permission restriction is executed by clicking on the delete button, displayed at the upper right corner of the permission definition set area.
SDDL
The string defined in the Security Descriptor Definition Language defines the actual permission set for the given service. When a permission set is added, RayPack prepares a default string that has to be adjusted to the actual needs of the packaging project. Even though it is possible to directly change the SDDL string within the displayed input field, it is recommended to use the extended editor dialog. Use the "edit sddl text" button below the SDDL input field to open that editor dialog.
Condition
If the permission is bound to specific conditions, these may be defined with support or the RayPack condition builder. Use the "edit in condition builder" button below the condition input field to open that editor.
Tab: Controls
Both service manipulation item types allow the definition of control commands to be applied to the service during installation and uninstallation run-time. When a new service control item is added to a packaging project, RayPack automatically adds an item to the control tab, assigning the service to start during installation and wait for the SCM report before the installation carries on. The identifier of the control command is defined automatically as a unique combination of several values (such as the name of the parent service manipulation object, an incrementing index value and the keyword "Control").
A service control item needs to have at least one control command, whilst service installer items may be executed without any control command at all.
To add a control command, users click on the Add button which is displayed above the list of already existing control commands. A new command is added with the very same default settings applied as described above.
To delete a control command, users click on the Delete button at the right hand side of the control command that is about to be deleted.
Please note that Deleting a control command is impossible for service control items when there is no other control command left for the service control object.
Each control command can be adjusted towards the following options:
Install action
The command to apply during the installation sequence of the target package may be any combination of:
•Start - starts the service during the StartServices action.
•Stop - stops the service during the StopServices action.
Stopping a service also stops all depending services
•Delete - deletes the service during the DeleteServices action.
Deleting a service causes the installer to stop it before it is actually deleted
Uninstall action
The command to apply during the uninstallation sequence of the target package may be any combination of:
•Start - starts the service during the StartServices action.
•Stop - stops the service during the StopServices action.
Stopping a service also stops all depending services
•Delete - deletes the service during the DeleteServices action.
Deleting a service causes the installer to stop it before it is actually deleted
Wait Type
Users may decide to let the installation wait for the SCM (Service Controll Manager) to report the service to be in a pending state before the installation proceeds, or to wait for max. 30 seconds for the service to complete before the installation proceeds.
Argument
Add parameters to the command line used to run the service. If more than one parameter is added, they have to be separated by null ("[~]").
Tab: Configure Settings
Within this tab, users may manage Events and Recovery actions for the service manipulation event. Both sub-tabs are displayed below the main tab navigation bar.
Sub-tab: Events
Service manipulation event objects are internally stored within the Installer database table MsiServiceConfig. A list of already created events is displayed when this sub-tab is loaded. To display the details for an event, the downwards arrow icon left of each events title bar has to be clicked. (Another click on the now visible upwards arrow icon collapses the details pane.)
To add an event, users click on the Add button above the list of already available event items, and adjust the default settings of the newly created object.
To delete an event, users click on the Delete button that is displayed at the right-hand side of each event items data block.
The following event properties may be edited:
Event trigger
Events may be triggered by Install, Uninstall, and/or Reinstall - the actual combination of active triggers is an arbitrary user definition.
Wait type and Argument
The set of available options for the Argument property actually depends on the selected Wait type:
•Wait type: Configure the time delay of an auto-start service
Argument options:
oTurn off the auto-start service delay
oStart the service after other auto-start services plus time delay
•Wait type: Change the list of privileges required by the service
Argument options:
oThe argument string required to do so may be changed within the SERVICE PERMISSIONS dialog. Click on the edit argument link at the right-hand side of the argument input field to open the editor dialog. Activate the checkbox in the outer left column of the privilege list to define the privilege to be required for the service. Deactivate checkboxes to remove existing requirements.
•Wait type: Add a service SID type to the process token containing this service
Argument options:
oNone
oRestricted
oUnrestricted
•Wait type: Configure the length of the time the SCM waits before proceeding with other shutdown operations
Argument options:
oThe required argument value is an integer, resembling the seconds the SCM should wait.
•Wait type: Configure when to run the failure actions for this service
Argument options:
oRun the actions only if the service terminates without reporting SERVICE_STOPPED
oRun the actions if the service terminates reporting SERVICE_STOPPED
Sub-tab: Recovery Actions
Service manipulation recovery actions are internally stored within the Installer database table MsiServiceConfigFailureOptions. They define actions that have to be executed at the next system start after a failed service run.
A list of already created recovery actions is displayed when this sub-tab is loaded. To display the details for an action, the downwards arrow icon left of each items title bar has to be clicked. (Another click on the now visible upwards arrow icon collapses the details pane.)
To add a recovery action, users click on the Add button above the list of already available event items, and adjust the default settings of the newly created object.
To delete a recovery action, users click on the Delete button that is displayed at the right-hand side of each action items data block.
The following recovery action properties may be edited:
Trigger
Recovery actions may be triggered by Install, Uninstall, and/or Reinstall - the actual combination of active triggers is an arbitrary user definition and translated into a bit flag value.
Reset Period
The reset period defines the time (in seconds) of successful service up time that is required before the SCM failure count for the specific service is reset.
Reboot Message
If a reboot is due, the entered value will be displayed before the system restarts.
Command
If a command has to be executed as part of the recovery routine, it has to be defined here. If no value is given, the existing command will be used unchanged. Entering null ("[~]") suppresses any command execution.
SCM Actions
Each recovery action may include one or more Service Control Manager (SCM) actions. Internally, these actions are stored as a matching pair of sequence arrays within the MsiServiceConfigFailureAction table columns Actions and DelayActions.
A list of already created recovery actions is displayed when the details pane of a recovery action is loaded. To display the details for an SCM action, the downwards arrow icon left of each items title bar has to be clicked. (Another click on the now visible upwards arrow icon collapses the SCM actions details pane.)
To add an SCM action, users click on the Add button above the list of already available SCM action items, and adjust the default settings of the newly created object.
To delete an SCM action, users click on the Delete button that is displayed at the right-hand side of each SCM action items data block.
For each SCM action, users may edit the following properties:
Action
Users have to pick from the available set of actions:
•Restart service
•Reboot computer
•Run command
•No action
Delay
The milliseconds to wait before the action defined above is actually executed.