Building MSI Updates and Patches

by Robert Dickau, Principal Technical Training Writer, Flexera Software

Introduction

This white paper describes the changes you make to a Windows Installer (MSI) installation package for it to behave as the desired type of update or patch. It begins by discussing information about settings to change in the MSI database. It also highlights the tools in InstallShield® by Flexera™ Software that simplify the process.

Also, if you haven’t read the white paper, “Designing an Update-Friendly MSI Installation,” it has valuable tips on how to build your initial install. You can download it at www.flexerasoftware.com/whitepapers.

Learn More about InstallShield:

If you wish to learn more about the capabilities of InstallShield, please visit the Flexera Software Web site at http://www.flexerasoftware.com/installshield

Using the InstallShield Environment

This white paper frequently refers to the InstallShield development environment. It is assumed you are familiar with the general layout of the InstallShield interface, which contains a list of views with which you can modify different portions of your installation project.

For example, the General Information view is where you set general product and project properties; the Setup Design view enables you to edit the features, components, and component data used by your project; the Registry view enables you to modify the registry data installed by your installation program; and the Direct Editor view gives you access to the raw MSI database tables. It is also assumed you are familiar with some of the wizards available with InstallShield, such as the Release Wizard and Component Wizard.

  • The Release Wizard, available under the Build menu and also from the Releases view, lets you describe the properties—media type, compression settings, and so forth—of a release, and then builds the specified release image.
  • The Component Wizard, available by right-clicking a feature in the Setup Design view, lets you create special types of components, such as components for COM servers, fonts, and Windows services.

The InstallShield Help Library contains information about using every view and wizard in the InstallShield environment. The InstallShield Help Library is available when you press F1 with any view selected; you can also select Contents from the Help menu to view the help library.

In addition to the graphical environment, InstallShield provides several tools for modifying and building projects from the command line or an external script. For example, to build a project from the command line, batch file, or other automated process, you can use the executable IsCmdBld.exe. The IsCmdBld executable is located in the System subdirectory of the InstallShield distribution directory.

To rebuild a project, you pass IsCmdBld the project file path, the product configuration name, and the release name that you want to rebuild. A sample command appears as follows:

iscmdbld -p C:\ProductName.ism -a BuildConfig -r ReleaseName

In addition, InstallShield provides an Automation interface, with which you can modify the contents of a project file without using the graphical environment.

Review of Upgrade Types

Windows Installer supports three types of product upgrades: small updates, minor upgrades, and major upgrades. The three types of upgrades are defined as follows.

  • A small update consists of product changes, such as hot fixes, so small t hat no change to t he product version is necessary or desired. (A drawback to small updates is that external programs, including installers for later versions of your product, will not be able to distinguish a product with the small update applied from one without the small update.)
  • A minor upgrade is a change to the product large enough to merit a change to the product version, such as updating version 1.1 to 1.2, but in which there have been no significant changes to the setup organization between versions. The install-time behavior of a minor upgrade is to install over the existing product.
  • A major upgrade includes substantial product changes, such as updating version 1.2 to 2.0. A major upgrade can contain significant changes to the setup architecture; later. The install-time behavior of a major upgrade can be to uninstall the earlier version and install the new one, or to install over the earlier version and then remove any leftover data.

NOTE: For an earlier product version that was installed with a legacy (non–Windows Installer) setup, a custom action will normally be required to uninstall or modify the existing product installation.

MSI Codes and Updates

Every MSI database contains a handful of codes that identify the product being installed.

  • Package Code: part of the Summary Information Stream, t he package code identifies a particular database. Any two MSI databases with identical package codes must have identical contents, and therefore you should change the package code for each build.
  • ProductVersion: MSI property storing the product version. Note t hat MSI uses only t he first t hree fields of t he ProductVersion property for version comparisons: in a.b.c.d, t he field d is ignored. (Note that this is true just for comparisons of ProductVersion values, and not for file versions. File-version comparisons can use all four fields of a file’s version.)
  • ProductCode: MSI property containing the GUID for the current product. MSI treats two products with different ProductCode GUIDs as unrelated, even if ProductName is the same. (As you will see, the major-upgrade process instructs MSI to treat two products with different GUIDs as related.)
  • UpgradeCode: MSI property containing a GUID representing the current product “family”; in the major-upgrade process, if two products have different ProductCode values but the same UpgradeCode value, MSI knows that the products are related, and are therefore candidates for the major-upgrade process. In general, the upgrade code value never changes.

When you design different types of upgrades, you must change different combinations of these codes. The following table summarizes the required changes.

  Package code (SIS) Product Version Product Code Upgrade Code
Small update X      
Minor upgrade X X    
Major upgrade X X (usually) X  

Inside InstallShield, the package code is exposed in the Summary Information Stream view, under General Information.

In this view, you can select the Package Code setting and click the Generate GUID button (not pictured).

Because the package code should change for every new release, the default behavior of InstallShield is to generate a new package code each time you perform a build. You can modify this behavior by selecting a product configuration icon in the Releases view, and setting Generate Package Code to No, though doing so is strongly discouraged.

Note that you can also use this view to specify a product version, product code, and other properties for the current product-build configuration. If you enter a specific value here, it automatically overrides the value in the Product Properties view.

This is an excerpt. Download the entire pdf: Building MSI Updates and Patches