Upgrading InstallShield 11.5 or Earlier InstallScript MSI Projects

InstallShield 2016

The following sections explain details about upgrading InstallScript MSI projects that were created in InstallShield 11.5 or earlier to InstallShield 2016.

Global Variables, Global Pointers, and SUPPORTDIR

With InstallShield 2016 and earlier versions, when an InstallScript MSI installation initializes, it loads the compiled InstallScript file, and it calls InstallScript events in this “main” loaded InstallScript file as necessary during the installation.

However, for InstallShield 12 and later, when a function within the InstallScript is called by the Windows Installer engine as an InstallScript custom action, the custom action behaves like an InstallScript custom action in a Basic MSI installation. That is, the function is executed in a completely separately loaded script instance; the script is loaded before the action is called and unloaded after the action completes. Thus, each InstallScript function that is called by the Windows Installer engine as an InstallScript custom action executes in its own session with complete InstallScript engine loading and unloading. This behavior is different than with InstallShield 11.5 and earlier: the custom actions were called in the single main loaded script file instance that was loaded during initialization and unloaded at the end of the installation.

A major implication of this change in behavior is that InstallScript functions that are called as InstallScript custom actions no longer have access to global variables and pointers that are maintained by the main executing script file:

Another implication of this change is that each custom action initializes and uses its own individual SUPPORTDIR. Therefore, you cannot share information across individual calls using files in SUPPORTDIR, since each custom action invocation will have its own unique SUPPORTDIR. You can share information using FOLDER_TEMP or some other file location.

Note that FOLDER_TEMP may not be the same path for all of your InstallScript custom actions. If you have some InstallScript custom actions that run in system context and some that do not, they will have different temp paths if the package is running in an elevated state. The InstallScript custom actions run in the context of a different user, so storing files in the temp directory and retrieving it later may not work in certain scenarios.

Windows Installer Properties and Deferred, Commit, and Rollback InstallScript Custom Actions

Deferred, commit, and rollback InstallScript custom actions in InstallScript MSI installations have access to only some of the built-in Windows Installer properties: CustomActionData, ProductCode, and UserSID. If you want an InstallScript custom action to access any other properties (such as SUPPORTDIR) during deferred, commit, or rollback execution, you need to pass them as CustomActionData. You can do so by scheduling an immediate set-a-property type of custom action (or, for example, an immediate InstallScript custom action with the MsiSetProperty function) to set a property that matches the name of the custom action. The value of this property is then available in the CustomActionData property within the deferred custom action.

For example, if you want to access a property such as SUPPORTDIR, you could create an immediate custom action that is called MyCustomActionName and that sets the MyCustomActionName property to [SUPPORTDIR], and then substitute "SUPPORTDIR" with "CutomActionData" in the MsiGetProperty call:

MsiGetProperty(hMSI, "CustomActionData", szSupportDir, nLen)

For more details, see the following:

Note that failure to compensate for an unavailable Windows Installer property may cause unexpected results during installation. For example, since in a deferred action, MsiGetProperty(hMSI, "INSTALLDIR", szInstallDir, nLen) sets szInstallDir to the empty string, szInstallDir ^ szFile may refer to a file in the current directory instead of a file in [INSTALLDIR]. The current directory for a deferred custom action is often [SystemFolder].

Deferred, commit, and rollback InstallScript custom actions do not have access to the ProductLanguage property. If your installation includes multilanguage support and it also has a deferred, commit, or rollback InstallScript custom action that needs access to the language in which the end user is running the installation, the installation assumes that this language is the installation’s default language. This could be a problem if an end user runs the installation in a language other than the default language. However, deferred, commit, and rollback custom actions do not typically display any user interface, so this would usually not be a problem.

Changes to the DoInstall Function

The DoInstall function now launches the setup executable file of the child installation instead of using the already-running installation engine to run the child installation. This change should be automatic; that is, it should not require any changes to existing InstallScript code. The child installation may take slightly longer to initialize than in previous versions because the installation executable file needs to initialize. For more information, see DoInstall.

Note that now calling DoInstall is similar to calling LaunchAppAndWait. When the installation is run from any removable media, such as a CD-ROM or a floppy disk, the Setup.exe file on Disk1 may not be available during the entire installation. (If Setup.exe becomes unavailable while it is running, the operating system sometimes displays a prompt to request that the end user insert the correct disk, and this may cause the installation to fail.) Therefore, to avoid this problem, the Setup.exe file is copied to a Temp folder, and the installation is relaunched from there. The original Setup.exe then terminates. However, when this happens, DoInstall (or LaunchAppAndWait, if it is called) behaves as if the installation has completed, and it does not wait.

Several workarounds for this issue exist. One method is to use the /clone_wait parameter when you are launching the child installation; as a result of this workaround, the launched installation keeps the original launched process running, and the parent installation then waits. Note, however, that this may cause problems if the original CD containing Setup.exe is not available throughout the entire installation. This includes multiple-CD installations, where the first CD is not available during some parts of the installation.

The only other way to avoid this problem is to add code that determines the ID of the child processes of the launched process and wait for the child process to complete.

Changes to Disk1 Files

InstallShield no longer places the following file on the Disk1 image of the built installation because it is no longer needed:

ISScript<version>.msi

In InstallShield 12 and later, the following file is placed on the Disk1 image of the built installation:

ISSetup.dll

The Disk1 file changes have not been known to cause any upgrade issues. These changes are reported for informational purposes.

Changes to the InstallScript Engine Files

With InstallShield 12 and later, InstallScript MSI installations no longer install InstallScript engine files to the following directory:

<COMMONFILES>\InstallShield\Professional\Runtime\<MajorVersion>\<MinorVersion>\Intel32

For InstallShield 11.5 and earlier InstallScript MSI projects, several files were stored in the Binary table:

For InstallShield 12 and later, all of these files (except ISScriptBridge.dll, which is no longer used) are stored inside the ISSetup.dll file, and that is the only file that is stored in the Binary table.

The InstallScript engine file changes have not been known to cause any upgrade issues. These changes are reported for informational purposes.

InstallScript-Related Custom Actions

Several built-in InstallScript-related custom actions were eliminated in InstallShield 12 for InstallScript MSI projects. If you upgrade an InstallScript MSI project from InstallShield 11.5 or earlier to InstallShield 2016, InstallShield removes these built-in custom actions from your project. Because these custom actions have been removed, some existing InstallScript event handler functions that were previously called by the custom actions are now called directly from InstallScript. For more information, see Creating and Scheduling InstallScript Custom Actions that Call InstallScript Event Handlers for InstallScript MSI Projects.

Changes for Deploying an InstallScript MSI Installation Without a Setup.exe File

To allow InstallScript MSI installations to be run without the Setup.exe file so that the packages can be deployed through technologies such as Active Directory, you may be able to use the instructions that are described in Knowledge Base article Q108166 - HOWTO: Deploying an MSI Wrapped with an InstallShield Script-Based Setup.exe. However, if you follow the procedure that is described in that article and users launch the .msi file directly, some of the InstallScript events (such as OnMoved) are never called. The reason that they are not called is that some of the InstallScript event handler functions that were previously called by built-in InstallScript-related custom actions are not called, since the InstallScript-related custom actions have been removed.

For more information, see Creating and Scheduling InstallScript Custom Actions that Call InstallScript Event Handlers for InstallScript MSI Projects.

See Also

Run-Time Behavior for InstallScript MSI Installations

Upgrading Projects from InstallShield 11.5 or Earlier

Open topic with navigation