Using InstallScript Actions in Suite/Advanced UI Projects

InstallShield 2013 added support for actions in Suite/Advanced UI projects similar to custom actions in MSI installations. With Suite/Advanced UI actions it is possible to run EXEs, call code in a DLL, run a PowerShell script, or set properties. These action types are supported directly in the Events view in Suite/Advanced UI projects. Another action type is currently supported but does not have any exposed support in the IDE: InstallScript actions. This article provides information on the steps needed to work with InstallScript actions in a Suite/Advanced UI project in InstallShield 2013 Premier Edition.

The following steps provide a rough outline of what is required to implement InstallScript actions in a Suite/UI project:

1. Write and compile InstallScript for use in a Suite/Advanced UI installation.
2. Include the compiled script (setup.inx), ISRT.dll, and ISSetup.dll as support files in a Suite/Advanced UI project.
3. Add CallInstallScript actions to the Actions collection in the Suite/Advanced UI project and sequence them as needed through the Events view.

The recommended approach to building InstallScript suitable for a Suite/Advanced UI project

1. Create a new InstallScript project.
2. In the InstallScript project, on the Build menu, click Settings, and change the following:
   1. Preprocessor Definitions: _ISCRIPT_SUITE_EXTENSION (add any others you need)
   2. Libraries: isrtsuite.obl (add any others needed; isrt.obl and ifx.obl cannot be included with isrtsuite.obl)
3. Write script as needed. Functions that can be called by a Suite/Advanced UI action must be prototyped with the export keyword. (This is the same requirement for InstallScript custom actions in Basic MSI projects.)
4. Compile or build the InstallScript project. The compiled script will be located in the project folder’s Script Files subfolder (as setup.inx).

A Suite entry point should be prototyped and defined as follows in your script:

There are a number of InstallScript functions that wrap the ISuiteExtension object that is passed to an InstallScript Suite action entry point. These functions are documented in the help article Suite/Advanced UI and Advanced UI Interaction Functions. (The FeatureConfigureFeaturesFromSuite function can be ignored.)

Note the following details about InstallScript functions supported in Suite actions:

• No InstallScript UI–related functions are available for use in a Suite/Advanced UI project; attempting to use any will result in either the script failing to compile or, if the script can be compiled, an error will be 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 Suite UI.
• 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 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 backed 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 engine and can be read with SuiteGetProperty.

Not including support for InstallScript UI–related functions or for bound variables allowed for a large increase in initialization speed for InstallScript actions in a Suite/Advanced UI installation (compared to InstallScript custom actions in a Basic MSI installation, which can take up to 2-3 seconds to fully initialize per action) and reduced a number of internal dependencies in the script engine.

To add CallInstallScript actions to a Suite/Advanced UI project

1. Open a Suite/Advanced UI .issuite project file in a text editor.
2. Locate the <Actions></Actions> collection/element.
3. Add as many CallInstallScript elements as needed to this collection. Each element defines a specific InstallScript action/function to call. The element should look like the following:

<CallInstallScript Id=”NameOfSuiteAction” Arguments=”ScriptExportedFunctionName” />

The Id attribute defines the name of the action that is normally listed in the Events view in the IDE. The Arguments attribute for CallInstallScript elements specifies the name of the exported InstallScript function to call in compiled script code.

4. Save the project and reopen it in InstallShield after adding any InstallScript actions.

In the Events view the new InstallScript actions will be listed as DLL actions (since the IDE doesn’t currently know about InstallScript actions in Suite/Advanced UI projects). You can sequence your actions either by dragging and dropping each action to a certain point in the event sequences (such as at any point during OnBegin), or right-click anywhere in the events list and select Add Existing Action->Your Action to add at that point in the sequence.

Files to be included in Support Files | Language Independent in a Suite/Advanced UI project

• setup.inx (from the Script Files folder of the project used to write/compile the script)
• ISRT.dll: this is located in Program FilesInstallShield2013RedistLanguage Independenti386
• ISSetup.dll: this is located in Program FilesInstallShield2013RedistLanguage Independenti386ISP (do not use the copy that is in the i386 folder; this does not implement the required functionality for Suite/Advanced UI support)
• ISBEW64.exe: this is located in Program FilesInstallShield2013RedistLanguage Independentx64 (do not use the copy in the I64 folder)

##########

View this video to learn more about the new capabilities of InstallShield 2013 which was designed to help application producers and their customers take advantage of the latest technology trends by simplifying the preparation and installation of web/server applications, 64-bit applications and the deployment of applications to virtual environments. Plus, InstallShield 2013 includes support of all the latest Microsoft Windows platforms.