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:

Keyword Export

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.  

Tags: , ,

10 comments on “Using InstallScript Actions in Suite/Advanced UI Projects

  1. plus.google.com/100459379919211559511 on

    Thank you very much for this information.

    I have tried implementing it in a new InstallScript project as suggested.
    I set the preprocessor define.
    I removed the other obl file references
    I set the isrtsuite.obl file reference

    Now when I compile the file no longer recognizes commands like RegDBSetDefaultRoot or RegDBKeyExist.
    Also, the SuiteSetProperty command is identified as ‘undefined identifier’. Likewise with the Registry commands.
    I am going to start over and try again just in case I did something wrong, but basically I deleted all references in the starting document and started over. Perhaps I should not have. I wanted to delete the OnBegin references and references to dialogs and such that come with a basic project.

    Reply
  2. Danel Lee on

    Josh,

    I am trying to implement this in my suite project.

    I now have coded what I needed and added the actions to the xml file. I have added two actions to the OnBegin event. However, when I execute the code I get errors.

    The code compiles correctly in InstallScript.
    The first action is called. But it returns with an error:
    1-24-2014[01:46:46 PM]: Launching InstallScript action in function ‘IsOSSupported’
    1-24-2014[01:46:46 PM]: Engine: request for proxy handler, 0, 0
    1-24-2014[01:46:48 PM]: Action returned value 0x80004003
    1-24-2014[01:46:48 PM]: Action ‘IsOsSupported’ returned status 0x80070643
    I have included the files stated above in the supported files.
    I tried to refactor the InstallScript project so that it only contains a single line to write to the log file in this particular function. But it still errors out.

    Is there something else I am missing?
    I included the support files, I set the Processor define and the obl file as described above.

    Reply
  3. Josh on

    The following is needed:
    #include “ifx.h”

    Also, the starter project really should be InstallScript, not any MSI types. Then you shouldn’t need to delete anything.

    Reply
  4. Josh on

    It is not currently possible to run suite actions from the suite UI. At this time suite actions can only be sequenced from events lists in the Events view of a suite project.

    Reply
  5. Flexera on

    Yes, this is possible to do. Assuming the DLL is C/C++, you would need to #import the type library from the Suite engine in your DLL code, and query interface from the IDispatch passed from InstallScript to an ISuiteExtension in your DLL code. Note that it may be more efficient, depending on your requirements, to just implement a DLL that is called directly by the Suite engine (instead of using InstallScript).
    – Josh

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *