Upgrading Projects from InstallShield 11.5 or Earlier

InstallShield 2016

For InstallShield 12, a number of improvements were made to the InstallScript MSI architecture to resolve issues with security (COM/DCOM) and other areas that can cause some installations to fail for various reasons. The architecture was improved for InstallShield 12 to resolve these issues and to make InstallScript MSI a more reliable project type. The improvements also help increase the reliability of InstallScript projects, as well as Basic MSI projects that include InstallScript custom actions.

The following table compares the earlier design with the current design:

Architecture Changes

In InstallShield 11.5 and Earlier

In InstallShield 12 and Later

Each InstallScript custom action is handled by ISScriptBridge.dll (a C++ MSI DLL), which forwards actual script execution to the ongoing IDriver.exe process.

Each InstallScript custom action is handled by ISSetup.dll (a single C++ MSI DLL), which contains the full InstallScript engine.

A set of engine files is required. They must be installed by ISScript.msi before the primary installation begins.

No engine files or ISScript.msi file is required. ISSetup.dll is self-contained.

All InstallScript custom actions execute in a shared IDriver.exe process. The IDriver.exe process remains resident until a final shutdown custom action is required.

Each InstallScript custom action is independent and has its own self-contained lifecycle. From the custom action entry point, ISSetup.dll starts the script engine, executes the relevant script, and shuts down the engine.

Advantages of the Architecture Changes That Were Introduced in InstallShield 12

The architecture in InstallShield 12 and later has several advantages over the earlier architecture:

End users no longer encounter error 1607, error 1608, or other COM/DCOM run-time errors that are related to finding the running IDriver.exe file. When these errors occurred under the earlier model, they were difficult to resolve, often requiring changes to DCOM settings. Also, the reliance on the running object table made the model brittle across the spectrum of usage scenarios, including Fast User Switching and Windows Terminal Services.
The engine binding is static. No shared engine files are installed to Program Files\Common Files\InstallShield. The reliance in InstallShield 11.5 and earlier on shared engine files made the model brittle because separate installations were not isolated. Changes to one engine version could break an existing installation. Isolation, especially for an installer, is one key to reliability.
The ISScript.msi file (the InstallScript engine installer) is no longer needed. The earlier model required an ISScript.msi file to execute prior to the primary .msi file. Because the full application was not contained in a single .msi file, the installation essentially required a bootstrap for Basic MSI installations that had InstallScript custom actions. This was very inflexible for enterprises that use Active Directory for managed environments. Also, it was confusing for advanced users who expect the main .msi file to be self-contained. InstallScript MSI installations still require a bootstrap, so that requirement is no different than the earlier architecture; however, Basic MSI installations with InstallScript custom actions no longer require a bootstrap.
Fewer InstallShield custom actions are needed to run the installation. The earlier model relied on a deep coupling between startup and shutdown custom actions that could easily fail. If one of the required custom actions was deleted or moved, the installation would not work properly.

Disadvantages of the Architecture Changes That Were Introduced in InstallShield 12

The disadvantages of the architecture in InstallShield 12 and later include the following:

InstallScript events are not available in Basic MSI and merge module projects; therefore, all InstallScript code for these project types must be run by InstallScript custom actions. Global variables do not share state between these custom action invocations. Therefore, you can declare a global variable in one InstallScript custom action script and then use that global variable throughout the script. However, if your Basic MSI installation has a second InstallScript custom action, the global variable declared in the first script is not available to the second script.

With the earlier model, InstallScript developers were able to use script code in any of the InstallScript events in Basic MSI projects, and any InstallScript global variables shared state. This allowed setup authors to write custom actions with a more holistic view and sense of continuity across the installation. However, because global variables are generally discouraged in programming, the new limitation should actually result in better-written InstallScript code.

In-memory objects must be serialized in order to be shared between custom action invocations. With the earlier model, InstallScript developers could store complex object-based data in global variables. As with the aforementioned disadvantage, this may actually result in better InstallScript code.

Upgrading InstallShield 11.5 and Earlier Projects

The extensive rearchitecture that has been introduced in InstallShield 12 may require some manual changes when you upgrade projects that were created with InstallShield 11.5 or earlier to InstallShield 2016.

To upgrade your project:

1. Before you convert your project, create a backup version of your project file and any InstallScript files.
2. Open InstallShield 2016.
3. On the File menu, click Open. The Open dialog box opens.
4. Browse to select the project file (.ism) of the InstallShield 11.5 or earlier project that you want to upgrade. A dialog box opens, prompting you to specify whether you want to upgrade the project.
5. Click Yes.

InstallShield upgrades your project and saves a backup copy of the project file (.ism).

To learn about possible manual changes that you may need to make to upgraded projects, see the following:

Upgrading InstallShield 11.5 or Earlier Basic MSI Projects that Have InstallScript Custom Actions
Upgrading InstallShield 11.5 or Earlier InstallScript MSI Projects
Upgrading InstallShield 11.5 or Earlier InstallScript Projects
Upgrading InstallShield 11.5 or Earlier QuickPatch Projects that Have InstallScript Custom Actions
Creating Standard Patches for InstallShield 11.5 and Earlier InstallScript MSI Projects
Upgrading InstallShield 11.5 or Earlier InstallScript MSI Object Projects or Projects that Contain This Type of Object

See Also