Upgrading Projects to InstallShield 12

[#1]

Summary

This article explains details about migrating projects that were created with InstallShield 11.5 or earlier to InstallShield 12. It also provides an overview of the advantages of this new architecture.

Synopsis

Flexera no longer provides support for Installshield 12.x. Please read Flexera Software's end of life policy document for more information on Flexera Software's policy as well as the end of life announcement for more information. In order to continue receiving support please upgrade to our latest version. Thank you for using Installshield.

The InstallScript MSI architecture has had a number of issues with security (COM/DCOM) and other areas that can cause some installations to fail for various reasons. The architecture has been improved dramatically 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.

This article explains details about migrating projects that were created with InstallShield 11.5 or earlier to InstallShield 12. It also provides an overview of the advantages of this new architecture. The article contains the following sections:

• Background
• General Discussion
• Discussion on Basic MSI Projects with InstallScript Custom Actions
• Discussion on InstallScript MSI Object Projects and Merge Module Projects
• Discussion on InstallScript MSI Projects
• Discussion on InstallScript Projects
• Discussion on QuickPatch Projects with InstallScript Custom Actions
• Discussion on Standard Patches for InstallScript MSI Projects
• Additional Information
• References

Background

The architecture in place in InstallShield 12 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 in the running object table (ROT). When these errors occurred under the earlier model, they were difficult to resolve, often requiring changes to DCOM settings. Also, the reliance on the ROT 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 (except temporarily on 64-bit systems, which is explained in the "Changes to the InstallScript Engine Files" sections in this article). 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 InstallScript MSI installations. 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.

Discussion

General Discussion

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 12.

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 12.
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).

Discussion on Basic MSI Projects with InstallScript Custom Actions

Global Variables, Global Pointers, and SUPPORTDIR

With InstallShield 12, when a Basic MSI installation executes an InstallScript custom action, the compiled InstallScript is loaded before the action is called, and it is unloaded after the action completes. Thus, each 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 compiled InstallScript was loaded once before the first InstallScript custom action that was used by the InstallScript was executed, and it was unloaded at the end of the installation after all InstallScript custom actions were completed.

A major implication of this change in behavior is that global variables and pointers are no longer maintained between individual InstallScript custom action calls:

• If you need to store a value across multiple custom action calls, you must use some external mechanism such as the registry, Windows Installer properties, or an external data file to store the information between calls. If you choose to use Windows Installer properties in deferred, commit, or rollback InstallScript custom actions, see the guidelines in Windows Installer Properties and Deferred, Commit, and Rollback InstallScript Custom Actions.
• If you need to use a COM object or some other global object across custom action calls, you must initialize the object for each individual custom action call in order for the object to be valid.

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 Basic 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 pages:

• Tip: MSI Properties and Deferred Execution
• Obtaining Context Information for Deferred Execution Custom Actions

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.

InstallScript Debugger and InstallScript Custom Actions

In order to use the InstallScript Debugger to debug deferred, commit, or rollback InstallScript custom actions, you must make a registry change to the system on which you are debugging. For more information about this issue, as well as instructions on configuring the registry, see Knowledge Base article: Q112187 - BUG: InstallScript Debugger Does Not Debug Deferred, Commit, or Rollback InstallScript Custom Actions (see related kb section).

Predefined InstallScript Event Handler Functions

The predefined InstallScript event handler functions are no longer available in Basic MSI projects with InstallScript custom actions. In InstallShield 11.5 and earlier, the following InstallScript event handler functions were available for Basic MSI projects:

• OnBegin
• OnMoving
• OnMoved
• OnEnd

InstallShield no longer supports these event handler functions for Basic MSI projects that have InstallScript custom actions. They are not called once the project is rebuilt with InstallShield 12. Note that these event handler functions still compile in InstallShield 12; they are just not called.

If you use these event handler functions in your project, you need to manually schedule custom actions that call these functions. To learn how, see Knowledge Base article: Q112168 - HOWTO: Creating and Scheduling InstallScript Custom Actions that Call InstallScript Event Handlers (see related kb section).

InstallShield InstallScript Scripting Engine Merge Module

Beginning with InstallShield 12, the InstallShield scripting engine merge module is no longer available for inclusion in Basic MSI projects. In InstallShield 11.5 and earlier, you could use this merge module to distribute the InstallScript engine for installations that did not include Setup.exe. InstallShield 12 automatically includes the InstallScript engine as part of ISSetup.dll in Basic MSI installations that have InstallScript custom actions, regardless of whether Setup.exe is used. Therefore, you do not need this merge module in InstallShield 12 projects.

If you use InstallShield 12 to try to build a release for a project that has this merge module, you may encounter a build error such as the following one:

ISDEV : error -4075: File not found. An error occurred merging Module 'InstallShieldScriptingEngine.4F635B62_07BF_4779_B74E_D80C29D508E3:0' for Feature 'NewFeature1'.

To resolve this build error, remove this merge module from your project; you can do so by clearing its check box in the Redistributables view.

Changes to the InstallScript Engine Files

With InstallShield 12, Basic MSI installations that include InstallScript custom actions no longer install InstallScript engine files to the following directory:

<COMMONFILES>\InstallShield\Driver\<Version>\Intel 32

Only 64-bit systems cache InstallScript engine files. A single shared engine file is installed on 64-bit systems to the following location if it is writable:

Documents and Settings\All Users\Application Data\InstallShield\ISEngine 12.0\IsBe.dll

If the aforementioned location is not writable, the shared engine file is installed to the following location:

Documents and Settings\<Current User>\Application Data\InstallShield\ISEngine 12.0\IsBe.dll

The IsBe.dll file remains on the system only while the installation is running. It is removed once no InstallShield installation is running. Also, this file is used only by installations created with InstallShield 12; it is not shared by InstallShield installations created by future versions of InstallShield.

Note that the IsBe.dll file is shared by InstallScript projects, InstallScript MSI projects, and Basic MSI projects with InstallScript custom actions running on the system.

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

• Setup.inx
• Isconfig.ini
• Isrt.dll
• ISScriptBridge.dll
• _isresXXXX.dll (where XXXX is the language?one .dll was included for each language included in the installation)
• StringxXXXX.txt (where XXX is the language?one .txt was included for each language in the installation)

For InstallShield 12, 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.

These changes have not been known to cause any upgrade issues. These changes are reported in this article for informational purposes.

Discussion on InstallScript MSI Object Projects and Merge Module Projects

The merge module project type has been enhanced: it now has the same InstallScript view that is available in Basic MSI projects. This enhanced version of the merge module project type replaces the InstallScript MSI object project type, which is no longer available in InstallShield.

If you use InstallShield 12 to open an InstallScript MSI object project that was created with an earlier version of InstallShield, the project will be converted into a merge module project. Predefined InstallScript event handlers are not available in merge module projects that have InstallScript custom actions. Therefore, if you have an InstallShield 11.5 or earlier InstallScript MSI object project that uses InstallScript event handler functions, you must manually schedule custom actions that call these functions when the project is converted to a merge module project in InstallShield 12. To learn how, see Knowledge Base article Q112168 - HOWTO: Creating and Scheduling InstallScript Custom Actions that Call InstallScript Event Handlers (see related kb section).

Building upgraded projects that contain already-built InstallScript MSI objects (.imm files) will fail; these objects cannot be consumed in InstallShield 12. If you try to do so, a build error such as the following one occurs:

ISDEV : error -4075: File not found. An error occurred merging Module 'InstallShieldMSIObjectName.4F635B62_07BF_4779_B74E_D80C29D508E3:0' for Feature 'NewFeature1'.

where "InstallShieldMSIObjectName.4F635B62_07BF_4779_B74E_D80C29D508E3:0" is information that is specific to the missing InstallScript MSI object. To resolve this build error, remove this InstallScript MSI object from your project; you can do so by clearing its check box in the Redistributables view.

Note that InstallShield 12, as well as earlier versions of InstallShield, can consume InstallShield 12 merge modules that have InstallScript custom actions.

Discussion on InstallScript MSI Projects

Global Variables, Global Pointers, and SUPPORTDIR

With InstallShield 12 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, 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:

• If you need to interact with the main executing InstallScript file to perform tasks such as using or changing global variables or modifying objects that are maintained by the main executing script file (which includes updating the status bar or logging script operations for uninstallation), your function must be called from an InstallScript event?not as an InstallScript custom action. Functions that are called from InstallScript events are executed in the main InstallScript instance. (Exception: Some InstallScript error events such as OnFilesInUse are called as a result of an error message from the Windows Installer engine. The Windows Installer engine launches these InstallScript error events as InstallScript custom actions; thus, the limitations of InstallScript custom actions also apply to these InstallScript events.)
• If you need to store a value across multiple InstallScript custom action calls, you must use some external mechanism such as the registry, Windows Installer properties, or an external data file to store the information between calls. If you choose to use Windows Installer properties in deferred, commit, or rollback InstallScript custom actions, see the guidelines in Windows Installer Properties and Deferred, Commit, and Rollback InstallScript Custom Actions.
• If you need to use a COM object or some other global object across custom action calls, you must initialize the object for each individual custom action call in order for the object to be valid.

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 pages:

• Tip: MSI Properties and Deferred Execution
• Obtaining Context Information for Deferred Execution Custom Actions

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.

InstallScript Debugger and InstallScript Custom Actions

In order to use the InstallScript Debugger to debug deferred, commit, or rollback InstallScript custom actions, you must make a registry change to the system on which you are debugging. For more information about this issue, as well as instructions on configuring the registry, see Knowledge Base article Q112187 - BUG: InstallScript Debugger Does Not Debug Deferred, Commit, or Rollback InstallScript Custom Actions (see related kb section).

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.

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, 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 in this article for informational purposes.

Changes to the InstallScript Engine Files

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

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

Only 64-bit systems cache InstallScript engine files. A single shared engine file is installed on 64-bit systems to the following location if it is writable:

Documents and Settings\All Users\Application Data\InstallShield\ISEngine 12.0\IsBe.dll

If the aforementioned location is not writable, the shared engine file is installed to the following location:

Documents and Settings\<Current User>\Application Data\InstallShield\ISEngine 12.0\IsBe.dll

The IsBe.dll file remains on the system only while the installation is running. It is removed once no InstallShield installation is running. Also, this file is used only by installations created with InstallShield 12; it is not shared by InstallShield installations created by future versions of InstallShield

Note that the IsBe.dll file is shared by InstallScript projects, InstallScript MSI projects, and Basic MSI projects with InstallScript custom actions running on the system.

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

• Setup.inx
• Isconfig.ini
• Isrt.dll
• ISScriptBridge.dll
• _isresXXXX.dll (where XXXX is the language?one .dll was included for each language included in the installation)
• StringxXXXX.txt (where XXX is the language?one .txt was included for each language in the installation)

For InstallShield 12, 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.

These changes have not been known to cause any upgrade issues. These changes are reported in this article 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 12, 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.

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 (see related kb section). 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.

Changes to the InstallScript Engine Files

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

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

Only 64-bit systems cache InstallScript engine files. A single shared engine file is installed on 64-bit systems to the following location if it is writable:

Documents and Settings\All Users\Application Data\InstallShield\ISEngine 12.0\IsBe.dll

If the aforementioned location is not writable, the shared engine file is installed to the following location:

Documents and Settings\<Current User>\Application Data\InstallShield\ISEngine 12.0\IsBe.dll

The IsBe.dll file remains on the system only while the installation is running. It is removed once no InstallShield installation is running. Also, this file is used only by installations created with InstallShield 12; it is not shared by InstallShield installations created by future versions of InstallShield

Note that the IsBe.dll file is shared by InstallScript projects, InstallScript MSI projects, and Basic MSI projects with InstallScript custom actions running on the system.

This change has not been known to cause any upgrade issues. This change is reported in this article for informational purposes.

Discussion on QuickPatch Projects with InstallScript Custom Actions

QuickPatch projects that are created in InstallShield 12 for InstallScript MSI projects can only patch media that were also created with InstallShield 12. If you want to use InstallShield 12 to create an update for an application whose previous InstallScript MSI installation was created with InstallShield 11.5 or earlier, you should create a create a minor-upgrade package instead of a QuickPatch, and use the Patch Design view to create a standard patch. Subsequent patches from this version can be created as QuickPatch projects.

Creating a QuickPatch for a Basic MSI project (with or without InstallScript custom actions) has not been known to cause any issues.

Discussion on Standard Patches for InstallScript MSI Projects

InstallShield 12 does not support the creation of InstallScript MSI patches (using the Patch Design view) where both the latest and previous setups were created with InstallShield 11.5 or earlier. Creating a patch where the latest setup is created with InstallShield 12 and the previous setup was created with InstallShield 11.5 or earlier has not been known to cause any issues.