Upgrading Projects from InstallShield 2010 or Earlier

InstallShield 2020

The following information describes possible upgrade issues that may occur when you upgrade projects that were created with InstallShield 2010 and earlier to InstallShield 2020. It also alerts you to possible changes in behavior that you may notice between new InstallShield 2020 projects and projects that are upgraded from InstallShield 2010 or earlier to InstallShield 2020.

General Information about Upgrading Projects that Were Created in Earlier Versions of InstallShield

If you use InstallShield 2020 to open a project that was created with an earlier version, InstallShield 2020 displays a message box that asks you if you want to convert the project to the new version. If you reply that you do want to convert it, InstallShield creates a backup copy of the project with a file extension such as .770 before converting it. Delete the .770 part from the original project’s file name if you want to reopen the project in the earlier version of InstallShield. Note that you cannot open InstallShield 2020 projects in earlier versions of InstallShield.

You can upgrade projects that were created with the following versions of InstallShield to InstallShield 2020: InstallShield 2010 and earlier, InstallShield 12 and earlier, InstallShield DevStudio, InstallShield Professional 7 and earlier, and InstallShield Developer 8 and earlier. Note that projects that were created with InstallShield MultiPlatform or InstallShield Universal cannot be upgraded to InstallShield 2020.

Changes that Affect All Projects (New and Upgraded Projects)

This section describes changes that affect both new projects and projects that are upgraded from earlier versions of InstallShield.

End of Integration Support for Visual Studio 2003 and Earlier

If you want to create, edit, and build your InstallShield projects directly within Visual Studio, you must use Visual Studio 2005 or later. InstallShield can no longer be integrated with Visual Studio 2003 or earlier.

Deprecation of InstallScript Objects

InstallScript objects have been deprecated in favor of InstallShield prerequisites. In a future release, InstallShield will no longer be able to create or consume InstallScript objects, and no predefined InstallScript objects will be provided. Furthermore, the Merge Module Holder Object will not be available. The recommended alternative for InstallScript objects is InstallShield prerequisites. You can use the InstallShield Prerequisite Editor to begin creating your own InstallShield prerequisites so that you are ready to use them once the InstallScript object technology becomes obsolete. You can share these InstallShield prerequisites among InstallScript, InstallScript MSI, and Basic MSI projects.

InstallShield Builds Only Unicode Versions of Setup.exe and Update.exe; Ability to Create ANSI Versions Is No Longer Available

Now all Setup.exe and Update.exe files that are built in all project types in InstallShield are Unicode. This applies to all new Basic MSI, InstallScript, InstallScript MSI, and QuickPatch projects that you create in InstallShield 2020. It also applies to all projects that you have upgraded from earlier versions of InstallShield to InstallShield 2020. Therefore, the settings that previously enabled you to specify whether you wanted to build a Unicode version or an ANSI version of the setup launcher have been removed:

The Setup Launcher Type setting on the Setup.exe tab for a release in the Releases view has been removed from Basic MSI projects.
The Update Launcher Type setting was removed from Basic MSI, InstallScript MSI, and QuickPatch projects.

In Basic MSI and InstallScript MSI projects, this setting was on the Advanced tab for a patch configuration in the Patch Design view.

In QuickPatch projects, this setting was on the Advanced tab in the Build Settings area of the General Information view.

Changes to Win32 API Definitions

Now that the InstallScript engine has been updated to support Unicode, the Win32 API functions that are prototyped in the InstallScript header file ISRTWindows.h have been updated. Where applicable, wide (W) versions of API prototypes have been added in addition to existing ANSI (A) definitions. For some prototypes, no A or W version is specified; in these cases, the engine now attempt to use the W version. Previously, the A version was used.

If you upgrade an InstallShield 2010 or earlier project to InstallShield 2020, it is possible that these new prototypes could conflict with user-defined prototypes of the same APIs. It is recommended that the InstallScript-provided prototypes be used if possible. However, if you want to use your own prototypes for these Windows APIs instead of the ones that are now prototyped for InstallScript, add ISINCLUDE_NO_WINAPI_H to the list of preprocessor definitions: On the Build menu, click Settings. On the Compile/Link tab, in the Preprocessor Defines box, enter ISINCLUDE_NO_WINAPI_H. Otherwise, you may encounter compile errors.

Ensuring that Your InstallScript Code Supports Unicode

If you use any user-defined Win32 APIs or other external DLL prototypes in your InstallScript code, and the APIs have versions that support Unicode string input, update the prototypes to use BYVAL/BYREF WSTRING or WPOINTER. In addition, review the API functions in your code that accept structures as input to ensure that those that contain string or string pointer members are declared as Unicode as appropriate, if the API requires it.

Update your script to call W versions of Win32 APIs if it is currently calling A versions.

Note that now that the InstallScript engine has been updated to support Unicode, you may see changes in the return values for the InstallScript function StrLength. As a result, you may need to make changes to your InstallScript code calls to this function.

StrLength now behaves the same as StrLengthChars; both of these functions return the number of characters in a given string variable (that is, the number of code units in the UTF-16-encoded string) up to the first null character. This applies to all InstallScript projects that are created in InstallShield 2020, as well as all InstallScript projects that you have upgraded from earlier versions of InstallShield to InstallShield 2020. Previously, StrLength returned the number of characters in a given string variable before a null character in the ANSI code page. The behavior of StrLengthChars has not changed.

Differential Release Support in InstallScript Projects

A differential release that is created in an InstallShield 2011 or later InstallScript project can update a product only if its earlier InstallScript installation was also created in InstallShield 2011 or later. If you want to use InstallShield 2011 or later to create an update for a product whose earlier InstallScript installation was created with InstallShield 2010 or earlier, you should create a full release, instead of a differential release.

This requirement is necessary because of the Unicode support that is new in the InstallShield 2011 InstallScript engine. After a differential release is used to update an earlier version of a product on a target system, the earlier version of the installation (along with the earlier engine run time) is used to run any maintenance operations. Because the InstallShield 2010 and earlier versions of the InstallScript engine cannot read the new Unicode storage format, the installation fails.

Uninstalling 64-Bit Registry Entries that Were Installed by the InstallScript Engine

By default, the InstallScript engine now logs the changes that it makes to the 64-bit part of the registry during an InstallScript or InstallScript MSI installation on 64-bit target systems. Furthermore, the 64-bit registry changes that are logged by the InstallScript engine are now uninstalled during uninstallation.

Note that if you created an InstallShield 2010 or earlier installation that wrote 64-bit registry data and you create an upgrade for your product in InstallShield 2020, the existing 64-bit registry entries that were logged by the base installation are not removed when the product is uninstalled from a target system. The only way to work around this limitation is to manually remove the registry data during uninstallation.

Script Editor Changes

Pressing CTRL+SPACEBAR from within the script editor pane in the InstallScript view no longer displays a list of built-in InstallScript functions that are available for auto completion, as it did in InstallShield 2010 and earlier. Now if you want to see a list of built-in InstallScript functions for auto completion, you simply need to start typing the first letter or letters of that function. The pop-up list also contains other InstallScript keywords. To learn more, see Using Auto Completion when Writing Code in the Script Editors.

The context menu that is displayed when you right-click in a script editor pane is now different than it was in InstallShield 2010 and earlier:

The context menu no longer contains a Show Whitespace command. To show or hide whitespace characters and symbols in the script editors, use the Script Editor Properties dialog box. This dialog box also lets you modify other settings in the script editors, such as font, syntax colors, and line numbering. To access this dialog box, right-click in a script editor and then click Properties.
The context menu no longer contains a Make Uppercase command or a Make Lowercase command. To make text in the script editor uppercase, select it and then press CTRL+SHIFT+U. To make it lowercase, select it and then press CTRL+U.
The context menu no longer contains a Find command or a Replace command. To perform a search in a script, press CTRL+F, and then specify the text that you want to find. To search for a string and replace it with something else, press CTRL+H and then specify the appropriate information. As an alternative, you can use the Find and Replace commands on the Edit menu.

For more keyboard shortcuts, see Keyboard Shortcuts for the Script Editors.

The views that contain the revised script editor are the InstallScript view, the SQL Scripts view, and the Custom Actions and Sequences view (when you are viewing a VBScript or JScript file in this view).

InstallScript Debugger Changes

If you copy the InstallScript Debugger (ISDbg.exe) from your installation development machine to a debug machine so that you can debug InstallScript code, you must also now copy the file called SciLexer.dll to the same folder on the debug machine. You can find SciLexer.dll on your installation development machine in the same folder as the ISDbg.exe file (InstallShield Program Files Folder\System).

For more information, see Debugging an Installation on Any Computer.

Changes that Affect New Projects but Not Upgraded Projects

This section describes changes to InstallShield that may affect new projects but not projects that are upgraded from earlier versions. Note that you may need to make manual changes to upgraded projects.

DPI Changes and Their Effect on InstallScript Dialogs

If you have an InstallShield 2010 or earlier InstallScript or InstallScript MSI project that contains one or more edited InstallScript dialogs and you want to upgrade the project to InstallShield 2020 or later, ensure that your machine uses the same DPI value that was selected when the InstallScript dialogs were edited. Otherwise, the dialogs may be sized incorrectly at run time.

Note that once you have upgraded the project, you can change the DPI value on your machine at any time as needed; if you do, the dialogs are sized correctly at run time. Also note that if you upgrade an InstallShield 2020 or later project that contains one or more edited InstallScript dialogs to a future version of InstallShield, you do not need to use the same DPI value during the upgrade.

Changing Design-Time and Build-Time Locations of Existing InstallShield Prerequisites in Existing Projects

InstallShield now lets you specify the folders where InstallShield should search for InstallShield prerequisite files (.prq files), their associated data files, and their dependencies. Previously, InstallShield searched for .prq files in the following location only: InstallShield Program Files Folder\SetupPrerequisites.

If you move any InstallShield prerequisites from the InstallShield Program Files Folder\SetupPrerequisites folder to a new custom location that you have defined on the Prerequisites tab of the Options dialog box (or any of the other places where search paths can be defined now), you may need to perform the following steps in InstallShield 2010 or earlier projects when you upgrade them to InstallShield 2020:

1. In the Redistributables view or the Prerequisites view, clear the check box for each InstallShield prerequisite that is included in your project but is located in a custom location. Also clear the check box for each InstallShield prerequisite whose data files or dependencies were moved from the default location to a custom location.
2. Click the new Refresh button.
3. Select the check box for each InstallShield prerequisite that you removed from your project in step 1.

InstallShield removes the path of the prerequisite from the ISSetupPrerequisites table of your project. The full path was stored in this table in InstallShield 2010 and earlier projects. Note that if you only clear a prerequisite’s check box and then reselect it without clicking the Refresh button, InstallShield continues to use the full path, rather than just the file name, in the ISSetupPrerequisites table.

If you upgrade an InstallShield 2010 or earlier project to InstallShield 2020, change the location of an InstallShield prerequisite, and then add that prerequisite to your project, you do not need to perform the refresh procedure. Also, if you create a new project in InstallShield 2020, you do not need to perform the refresh procedure. In both cases, InstallShield does not include the path in the ISSetupPrerequisites table of your project, which enables you to use the custom search path, instead of the default path.

Preventing an InstallScript MSI Installation from Overwriting a Future Major Version of the Same Product

The Upgrades view in new InstallScript MSI projects now contains a major upgrade item called ISPreventDowngrade. This item prevents end users from being able to install the current version of your product over a future major version of the same product. If you upgrade an InstallScript MSI project from InstallShield 2010 or earlier to InstallShield 2020, the ISPreventDowngrade item is not added automatically. You can manually add an ISPreventDowngrade item if appropriate. To learn how, see the Preventing the Current Installation from Overwriting a Future Major Version of the Same Product.

See Also