Designing an Update-Friendly MSI Installation

by Robert Dickau, Principal Technical Training Writer, Flexera Software


Creating and deploying software updates is standard procedure for virtually every software company in the world. Knowing strategies for how to create an update-friendly Windows Installer (MSI) installation goes a long way to ensuring a smooth, error-free update experience for your end users down the road.

In this white paper, you will learn about designing your original Windows Installer setup project to best prepare it for future upgrades, and how to design upgrade packages to install later versions of your products. It will also provide an introduction to the different types of updates supported by Windows Installer. Finally, at times throughout the white paper it will explain how InstallShield® from Flexera Software can assist with the installation and update authoring process.

Types of Upgrades

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 that no change to the 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. 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-MSI) setup, a custom action will normally be required to uninstall or modify the existing product installation.

Packaging and Deploying Upgrades

Windows Installer provides different methods for packaging upgrades, and the different options affect the way the upgrade is applied to a target system.

Packaging Options

An upgrade can be packaged for deployment to the target system as a full installation (MSI package). An upgrade packaged as a full installation can be authored (using custom actions, command-line switches, or a setup launcher) to upgrade an existing product if one is present, or otherwise to behave as a first-time installation.

An upgrade can also be packaged as a Windows Installer patch file (a file with the MSP extension). A Windows Installer patch contains changes between the files (and other data) and MSI tables in the earlier and later versions. The file differences stored in a patch can be binary, byte-level differences, possibly resulting in a much smaller deliverable than an update packaged as a full installation package. An update that you package as a patch file can be used only to upgrade an existing, installed product, and cannot be used as a first-time installation.

Small updates and minor upgrades are commonly packaged as patches, while major upgrades are usually packaged as full installation packages.

NOTE: A common misapprehension is that patches are a separate type of upgrade, as opposed to a packaging mechanism. In fact, the patch-development process involves first designing a minor or major upgrade, and then packaging it as a patch. Before creating a patch, it is recommended you test the update as a full installation package.

Deploying Upgrades and Patches

When you run an MSI installation package for the first time on a given system, Windows Installer caches the MSI database in the “super-hidden” directory %WINDIR%\ Installer. By default, when you run the same package a second or later time on the same system, Windows Installer runs the package in maintenance mode, using the cached database. (A package is typically authored to show a different series of dialog boxes for first-time installations and maintenance-mode installations, using conditions such as “Not Installed”.)

During the initial installation, the MSI database is cached on the user’s system, but the product’s data files are not. If a maintenance operation results in a file having to be installed, MSI will require access to the original installation source, prompting the user to locate the source if it cannot be found (for example, if the installation was performed from a CD-ROM that is no longer in the drive). For this reason, you should either build a release with the MSI database external to a setup launcher, or create a setup launcher that caches the installation on the local machine.

When you deploy a major upgrade package, no special command-line switches or property values are required. When deploying a minor upgrade package, however, you will generally need to set appropriate values for the REINSTALLMODE and REINSTALL properties, as described in the following section.


To avoid maintenance mode for a small update or minor upgrade installer, the MSI property REINSTALLMODE must be set at the command line, either by the user or by a setup launcher. The REINSTALLMODE property defines what types of data should be reinstalled: the value is a string of characters, where each character indicates a particular type of data to reinstall. (A major upgrade typically does not need any special properties set at the command line.)

The default REINSTALLMODE value is “omus”, where the characters stand for the following:

  • o: reinstall a file only if it is missing from the target system, or if the existing file on the target system is older.
  • m: reinstall machine-wide registry data.
  • u: reinstall user-specific registry data.
  • s: reinstall shortcuts.

When deploying a small update or minor upgrade, the key is to re-cache the cached MSI database by including the letter “v” in the REINSTALLMODE value, as in REINSTALLMODE=voums. (The order of characters in the REINSTALLMODE value is unimportant.)

NOTE: The “v” option for REINSTALLMODE must be set at the command line when the minor upgrade installation is launched; the other REINSTALLMODE settings can be activated within a running installation. InstallShield can help you create a setup launcher for a minor upgrade that detects if an earlier version of a product is installed on a system, and sets REINSTALLMODE and REINSTALL appropriately. Moreover, MSI validation rule ICE40 posts a warning if REINSTALLMODE is set in the Property table.

For an update installer, the REINSTALL property should also typically be set. The REINSTALL property should be set to a comma-separated list of features to reinstall (using the internal feature names, and not the localized display names), or to the special value “ALL”. Setting REINSTALL to ALL causes only the features already installed by an earlier installation to be reinstalled. For this reason, setting REINSTALL to ALL is inappropriate for a first-time installation: during a first-time installation, no features have yet been installed.

When running a minor upgrade packaged as a full MSI package, a typical command line is the following: msiexec /i ProductName.msi REINSTALLMODE=voums REINSTALL=ALL

A patch can be distributed using the MSP file, or by creating an Update.exe file that wraps the MSP and passes the appropriate REINSTALLMODE and REINSTALL property values to the Windows Installer engine.

To deploy a patch, a typical command line is the following: msiexec /p patch.msp REINSTALLMODE=oums REINSTALL=ALL

Because a patch does not modify the existing cached MSI database, including the “v” setting for REINSTALLMODE is unnecessary.

At run time, a patch transforms the cached MSI database, and then runs it in maintenance mode. A patch file is also cached on a target system, in the same location as cached MSI databases.

This is an excerpt. Download the entire pdf: Designing an Update-Friendly MSI Installation