|
<< Click to Display Table of Contents >> RayPack > 8.0 > User Guide > PackDesigner > MSI / MST / RPP Based Projects > Advanced Mode > Custom Actions Add a New Custom Action |
Adding a new custom action to a packaging project has to be triggered by a click on the Create new ... button, displayed at the upper left corner of the CUSTOM ACTIONS dialog. The Custom Action Wizard is invoked, starting to escort packagers throughout the process of custom action definition.
The actual step sequence of the wizard depends on the action type selection made on the first wizard screen:
Standard MSI custom actions:
oExecutable
oDLL
oVBS Script
oJS Script
oThe types Set folder, Set property, and Show error message do not contain any additional steps, but extend the Details step with specific settings.
Wrappers over standard MSI custom actions:
To actually select one of the presented custom action types, the specific icon tile has to be clicked. The current selection is indicated by a colored box with a checkmark in the upper right corner displayed as action type tile.
As soon as one type is selected, the following step has to be called with a click on the NEXT button. At each time during the wizard execution, users may abort the custom action creation by clicking the CANCEL button.
The following wizard steps are displayed for specific custom action type creation procedures:
- Only for custom action type Executable -
Select one of the following source types with a click on the type icon:
•Executable from a binary source
Requires an executable resource object within the Binary table.
Please refer to the help section about Resources to get details on how to manage binary resources via the Visual Designer interface.
•Executable deployed within this package
Requires an executable file object within the File table.
Please refer to the help section about Files and Folders to get details on how to manage files via the Visual Designer interface.
•Executable pointed by a property
Requires a property from the Properties table, containing a path that points to a specific file, which may either be stored within the current packaging project or on the target machine.
Please refer to the help section about Properties to get details on how to manage properties via the Visual Designer interface.
•Executable on destination
Allows to define a path to an executable file.
Clicking NEXT calls the Executable parameters step.
- Only for custom action type Executable -
When Executable from a binary source had been selected in the previous step, users have to select between the available options:
•New file from disk - select a file from a local or shared system drive.
or
•Existing binary stream - select one of the binary resource objects that have already been added to the packaging project.
When Executable deployed within this package had been selected in the previous step, users have to select one of the file objects that have already been added to the packaging project.
When Executable pointed by a property had been selected in the previous step, users have to
•Select the source property - Pick one of the properties that have already been added to the packaging project
and
•Define the path to the executable - The displayed value is automatically updated to match the actual content stored within the source property. Manually adjust it to define the actual path to the executable file.
When Executable on destination had been selected in the previous step, users have to select one of the directory objects that have already been added to the packaging project.
Command line arguments may optionally be given for every executable source type. Define the arguments that have to be appended to the command line that is used to actually call the executable.
Clicking NEXT in this step calls the Details step.
- Only for custom action type DLL -
When a DLL from a binary source has to be used:
Define the Source DLL file by activating one of the available options:
DLL from a binary source may be selected by the definition of either
•New file from disk - select a file from a local or shared system drive.
or
•Existing binary stream - select one of the binary resource objects that have already been added to the packaging project.
DLL deployed within this package offers a drop-down menu to select one of the file objects that have already been added to the packaging project.
The DLL has to be called through the Entry point, passing the handle to the current install session as argument. The specified entry point must match that exported from the DLL.
Clicking NEXT calls the Details step.
- Only for custom action types VBS and JS script -
Scripts may be added to custom actions via several methods:
•as a binary stream resource
•as inline script source code
•as a property value
•as a file deployed within the package
The method selected on the upper area of the wizard interface decides about the controls required to actually add the script, which are displayed in the lower part of the wizard dialog screen:
When source stream is selected, users may either trigger the creation of a new stream resource, or select one of the resources already available within the packaging project.
When inline script is selected, users will have to enter the code during the next wizard step.
When property value is selected, users may either trigger the creation of a new property, or select one of the properties already available within the packaging project.
When deployed file is selected, users may pick one of the files that have already been added to the packaging project.
Clicking NEXT calls the Script content step.
- Only for custom action types VBS and JS script -
The control interface that is shown within this step directly depends on the selections made during the prior one:
When source stream, inline script, or property value have been selected, a text area is displayed, allowing to either manually type the script code, manipulate the already available code, or load source code from an external file. The text area may not be left empty, since a script based custom action must contain the code for execution.
Additionally, when source stream, property value, or deployed file have been selected, there is an input field, allowing users to define the actual function that should be called in the scope of the custom action. The function name is mandatory for deployed files, and optional for the other options.
Clicking NEXT calls the Details step.
Whilst the type depending steps may vary, the following steps are common and required for all types:
The details step demands the definition of the execution mode:
•Immediate - Custom actions that set properties, feature states, component states, or target directories, or that schedule system operations by inserting rows into sequence tables, can in many cases use immediate execution safely.
•Deferred - Custom actions that change the system directly, or call another system service, must be deferred to the time when the installation script is executed.
•Rollback - The rollback procedure runs as a clean-up whenever an installation fails to be executed. Custom actions that are marked to run during rollback will not be executed during the primary installation.
•Commit - The commit procedure runs to finalize successful installations. A commit custom action is the complement to a rollback custom action and can be used with rollback custom actions to reverse custom actions that make changes directly to the system.
Additionally, packagers have to determine the user that is defined to be executor of the custom action:
•Run as system - When custom actions are defined to run as system user, the properties of some user related properties and paths are affected, such as the user related AppData directories and current user registry targets.
•Run as current user - This standard setting impersonates the custom action to the user that actually installs the package.
•Terminal server aware - Required only in terminal server based target environments.
The following optional behavior settings may be activated:
•Run as 64-bit script
On 64-bit operating systems, Windows Installer may call custom actions that have been compiled for 32-bit or 64-bit systems. A 64-bit custom action based on Scripts must be explicitly marked as a 64-bit
•Check exit code upon finishing
If this option is activated, the custom action will be considered as finished successfully if the return code 0 is given. All other return values express erroneous custom action execution. Deactivate this option to ignore the return code and always proceed with the procedure the custom action is a part of.
When Set folder has been selected as action type, this step is used to select the folder that has to be renamed, and the new value it has to be given. The folder identifier has to be an already known object from the Directory table. Users may use the syntax suggestion feature to set the new value based upon dynamic values, such as properties.
When Set property has been selected as action type, this step is used to select the property that has to be changed, and the new value it has to be given. The property identifier has to be an already known object from the Properties table. Users may use the syntax suggestion feature to set the new value based upon dynamic values, such as paths.
When Show error has been selected as action type, this step is used to determine the actual error message that has to be displayed. The message may not be empty.
Clicking NEXT calls the Sequence step.
This step allows to optionally define in which of the installation sequences the custom action should run.
To add the custom action to one of the sequences, users have to expand the toggle for the required sequence type first. Once expanded, the toggle area contains the actual sequence(s) available for the type.
Activate the checkbox left of the sequence description in order to be able to define the position of the custom action within the specific sequence.
Custom actions may be added to no sequence, all sequences, or any combination of sequences in between.
This setting may be changed via the SEQUENCING view of the Advanced mode at any later time.
Clicking NEXT calls the Additional Settings step.
RayPack automatically generates a suggestion for the name of the custom action, based on the action type. The name of the custom action may not be left empty, has to be unique throughout the packaging project, and should not contain special characters.
The optional conditional statement input field may be used to enter a string for evaluation at run time. The custom action will only be executed if the condition is left empty (resembling a NULL value), or is evaluated to be TRUE.
Packagers may adjust the condition later as part of the sequencing management activities.
Clicking NEXT calls the Summary step.
This overview provides a chance to check the settings made during the prior steps. Please verify that all properties are noted correctly towards the desired custom action behavior.
Use the BACK button to navigate to former steps in case of adjustment requirements. Please be aware that going back may affect the already given values in steps that are depending on each other. If, for example, the resource type for a script based custom action is changed, the actual script code has to be re-defined.
Clicking PROCESS creates the custom action according to the settings displayed, and closes the wizard dialog.