Working with an Action that Runs InstallScript Code in a Suite/Advanced UI Installation

InstallShield 2015

Project: This information applies to Suite/Advanced UI projects.

Edition: The Advanced UI project type is available in the Professional edition of InstallShield. The Suite/Advanced UI project type is available in the Premier edition of InstallShield. For information about the differences between these two project types, see Advanced UI Projects vs. Suite/Advanced UI Projects.

InstallShield lets you add to your Suite/Advanced UI project an action that calls InstallScript code at run time. These Suite/Advanced UI–based InstallScript actions function much like InstallScript custom actions in Basic MSI projects.

The first step in adding an InstallScript action to a Suite/Advanced UI project is to write the InstallScript code that you want to run from your installation. You can use the InstallScript view in your project to do this. Once you have written the code, you can add an InstallScript action through the Events view of your project.

To add an action that runs InstallScript code in a Suite/Advanced UI installation:

1. Add the InstallScript code to your project:
a. In the View List under Behavior and Logic, click InstallScript.
b. In the InstallScript explorer, right-click the Files node and then click New Script File. InstallShield adds a new file called Setup.rul under the Files node.
c. Select the new .rul file, and then in the right pane, write the code that you want to launch at run time.

To have your Suite/Advanced UI action call an InstallScript function, you must prototype the function with the export keyword; for example:

export prototype MyFunction(OBJECT);

2. Add an InstallScript action that calls your InstallScript code:
a. In the View List under Behavior and Logic, click Events.
b. Right-click the Actions explorer and then click New InstallScript. InstallShield adds an InstallScript action to the Actions explorer.
c. Enter a new name, or right-click it later and click Rename to assign it a new name. Use a name that helps you distinguish this action from other actions in your project.
d. Configure the action’s settings as needed.

Once you have added the action to your project, schedule it as needed. For more information, see Scheduling a Suite/Advanced UI Action.

Tips for Writing InstallScript Code for Suite/Advanced UI Actions

Several InstallScript functions wrap the ISuiteExtension object that is passed to an InstallScript action entry point. These InstallScript functions enable your InstallScript actions to interact with the running Suite/Advanced installation.

SuiteFormatString
SuiteGetProperty
SuiteLogInfo
SuiteResolveString
SuiteSetProperty

To learn more about these functions, see Suite/Advanced UI and Advanced UI Interaction Functions.

Note the following details about the use of InstallScript functions that are called from actions in Suite/Advanced UI installations:

No InstallScript UI–related functions are available for use in a Suite/Advanced UI project; attempting to use any results in either the script failing to compile or, if the script can be compiled, an error is returned at run time. It is highly recommended that any UI that needs to be displayed by an InstallScript action instead be deferred to the UI of the Suite/Advanced UI installation.
An InstallScript action can read and write Suite/Advanced UI properties and use them as a sort of communication mechanism with the Suite UI. (Suite/Advanced UI actions are similar to Basic MSI custom actions and have no access to the UI.) For a list of built-in properties, see Advanced UI and Suite/Advanced UI Property Reference.
InstallScript run-time path variables (PROGRAMFILES, WINDIR, etc.) are not available. These variables normally are implemented through a concept in the script engine known as bound variables, wherein the variables themselves are associated directly to textsub name-value mappings. The textsubs that correspond with these variables are still available; for example, <PROGRAMFILES> can be resolved through the InstallScript functions TextSubGetValue or TextSubSubstitute. Path-type Suite/Advanced UI properties are also defined through the Suite/Advanced UI engine and can be read with SuiteGetProperty.
The szStatusText member of the LAAW_PARAMETERS structured variable is not available for use in InstallScript actions that are called in Suite/Advanced UI installations.

You can debug the InstallScript actions in your Suite/Advanced UI installation with the InstallScript Debugger. To learn more, see Troubleshooting Issues with an Advanced UI or Suite/Advanced UI Installation.

See Also