Patching and Upgrades

Because an installation package can contain the files that make up an application as well the information needed for their installation, Windows Installer can be used to update the application. The installer can update information in the following parts of the installation package:

• The .msi file.
• The files of the application.
• The Windows Installer registration information.

The type of update can be characterized by the changes the update makes to the application’s product code, product version, and package code. The application’s product version is stored in the ProductVersion property. The application’s product code is stored in the ProductCode property. The application’s package code is stored in the Revision Number Summary Property.

An update that changes the application into another product is required to change the ProductCode of the application. For more information about which updates require changing the ProductCode see Changing the Product Code. The update can change the ProductVersion and leave the ProductCode unchanged if future versions of the application will need to differentiate between the updated and nonupdated versions of the current product. The Package Code uniquely identifies the installation package and should always be changed whenever update or upgrade changes any information in the installation package.

When deciding whether to change the product version, you should consider If future versions of the application will need to differentiate between the updated and nonupdated versions of the current product. To ensure differentiation in the future, a minor upgrade should be used instead of a small update.

• If an update changes the .msi file and application files, but does not change the ProductCode property or ProductVersion property, it is termed a small update.
• If the update changes the ProductVersion, but does not change the ProductCode, it is termed a minor upgrade.
• If the update changes the installation into an entirely different product, the ProductCode must change and the update is termed a major upgrade.

To ensure differentiation of versions of the current product in the future, a minor upgrade should be used instead of a small update.

The following table summarizes the different types of updates.

Type of update	Productcode	ProductVersion	Description
Small Update	No change	No change	An update to one or two files that is too small to warrant changing the ProductVersion. The package code in the Revision Number Summary Property does change. Can be shipped as a full installation package or as a patch package.
Minor Upgrade	No change	Changed	A small update making changes significant enough to warrant changing the ProductVersion property. Can be shipped as a full installation package or as a patch package.
Major Upgrades	Changed	Changed	A comprehensive update of the product warranting a change in the ProductCode property. Shipped as a patch package or as a full product installation package.

The Windows Installer can install an application, or an update, for all users of a computer (per-machine context) or for a particular user (per-user context) depending on the access privileges of the user, the value of the ALLUSERS property, and the version of the operating system. Application developers should consider in which context updates will be installed. If the contexts of the application and update are different, the application may not be updated as expected.

Users can update to an application by reinstalling a Windows Installer package for the application. Note that Minor Upgrades can be applied in the same way as Small Updates. For more information about updating an application by reinstalling the application, see these sections:

An update to an application can be provided to users as a Windows Installer patch package. A patch can contain an entire file or only the file bits necessary to update part of a file. This means that the user can download an upgrade patch that is much smaller than the entire product and that preserves user customizations through the upgrade. Note that Minor Upgrades can be applied in the same way as Small Updates. For more information about updating an application using a patch, see these sections:

Patching Initial Installations

A Windows Installer Patch (MSP) can be applied when installing an application for the first time by using the PATCH property.

To apply a patch the first time the application is installed, the PATCH property must be set on the command line. Specify the full path to the patch on the command line as the «PATCH=<path to patch>» property-value pair.

Note that specifying the PATCH property on the command line overrides the patch applicability checks performed when using MsiApplyPatch or the /p Command Line Option.

If a patch is applied using MsiApplyPatch or the /p Command Line Option, the installer compares the applications currently installed on the computer to the list of product codes eligible to receive the patch in the Template Summary property.

When you set the PATCH property on the command line to install on first installation, the applications eligible to receive the patch is determined by validation conditions on the transforms embedded in the patch package. The recommended method for generating a patch package is to use a patch creation tool such as Msimsp.exe and PATCHWIZ.DLL. The validation conditions on transforms in the patch originate from the ProductValidateFlags column in the TargetImages table of the Patch Creation Properties (.pcp) file.

The patch can be applied the first time the application is installed by a command line, another application, or script.

The following shows first-time patching from the command line.

msiexec /I package.msi PATCH=«c:\directory\patch.msp»

The following shows first-time patching from another application.

The following shows first-time patching from script.

**Windows Installer 3.0 and later:В В **

Beginning with Windows Installer version 3.0, multiple patches can be applied when installing an application for the first time. Set the PATCH property to a semicolon delimited list of the patches’ full paths. The following shows first-time patching of multiple patches from the command line.

Windows Installer

This documentation is intended for software developers who want to use Windows Installer to build installer packages for applications. If you’re looking for a redistributable for Windows Installer 4.5 and earlier, see this article. Note that there is no redistributable for Windows Installer 5.0. This version is included with the OS in Windows 7, Windows ServerВ 2008В R2, and later client and server releases (including Windows 10).

Microsoft Windows Installer is an installation and configuration service provided with Windows. The installer service enables customers to provide better corporate deployment and provides a standard format for component management. The installer also enables the advertisement of applications and features according to the operating system. For more information, see Platform Support of Advertisement.

This documentation describes Windows InstallerВ 5.0 and earlier versions. Not all the capabilities available in later Windows Installer versions are available in earlier versions. This documentation does not describe versions earlier than Windows InstallerВ 2.0. Installation packages and patches that are created for Windows InstallerВ 2.0 can still be installed by using Windows InstallerВ 3.0 and later.

Windows InstallerВ 3.0 and later, can install multiple patches with a single transaction that integrates installation progress, rollback, and reboots. The installer can apply patches in a specified order regardless of the order that the patches are provided to the system. Patching using Windows InstallerВ 3.0 only updates files affected by the patch and can be significantly faster than earlier installer versions. Patches installed with Windows Installer 3.0 or later can be uninstalled in any order to leave the state of the product the same as if the patch was never installed. Accounts with administrator privileges can use the API of Windows InstallerВ 3.0 and later to query and inventory product, feature, component, and patch information. The installer can be used to read, edit, and replace source lists for network, URL, and media sources. Administrators can enumerate across user and install contexts, and manage source lists from an external process.

Windows Installer 4.5 and later can install multiple installation packages using transaction processing. If all the packages in the transaction cannot be installed successfully, or if the user cancels the installation, the Windows Installer can roll back changes and restore the computer to its original state. The installer ensures that all the packages belonging to a multiple-package transaction are installed or none of the packages are installed.

Beginning with Windows Installer 5.0, a package can be authored to secure new accounts, Windows Services, files, folders, and registry keys. The package can specify a security descriptor that denies permissions, specifies inheritance of permissions from a parent resource, or specifies the permissions of a new account. For information, see Securing Resources. The Windows Installer 5.0 service can enumerate all components installed on the computer and obtain the key path for the component. For more information, see Enumerating Components. By Using Services Configuration, Windows Installer 5.0 packages can customize the services on a computer. Setup developers can use Windows Installer 5.0 and Single Package Authoring to develop single installation packages capable of installing an application in either the per-machine or per-user installation context.

Where applicable

Windows Installer enables the efficient installation and configuration of your products and applications running on Windows. The installer provides new capabilities to advertise features without installing them, to install products on demand, and to add user customizations.

Windows Installer 5.0 running on Windows ServerВ 2012 or WindowsВ 8 supports the installation of approved apps on WindowsВ RT. A Windows Installer package, patch, or transform that has not been signed by Microsoft cannot be installed on WindowsВ RT. The Template Summary property indicates the platform that is compatible with an installation database and in this case should include the value for WindowsВ RT.

Windows Installer is intended for the development of desktop style applications.

Developer audience

This documentation is intended for software developers who want to make applications that use Windows Installer. It provides general background information about installation packages and the installer service. It contains complete descriptions of the application programming interface and elements of the installer database. This documentation also contains supplemental information for developers who want to use a table editor or a package creation tool to make or maintain an installation.

Run-time requirements

Windows InstallerВ 5.0 is included with, Windows 7, Windows ServerВ 2008В R2, and later releases. There is no redistributable for Windows Installer 5.0.

Versions earlier than Windows Installer 5.0 were released with Windows ServerВ 2008, WindowsВ Vista, Windows ServerВ 2003, WindowsВ XP, and WindowsВ 2000. Windows Installer Redistributables are available for Windows Installer 4.5 and some earlier versions.

Windows InstallerВ 4.5 requires Windows ServerВ 2008, WindowsВ Vista, WindowsВ XP with Service PackВ 2 (SP2) and later, and Windows ServerВ 2003 with Service PackВ 1 (SP1) and later.

Windows InstallerВ 4.0 requires WindowsВ Vista or Windows ServerВ 2008. There is no redistributable for installing Windows InstallerВ 4.0 on other operating systems. An updated version of Windows InstallerВ 4.0, which does not add any new features, is available in WindowsВ Vista with Service PackВ 1 (SP1) and Windows ServerВ 2008.

Windows InstallerВ 3.1 requires Windows ServerВ 2003, WindowsВ XP, or WindowsВ 2000 with Service PackВ 3 (SP3).

Windows InstallerВ 3.0 requires Windows ServerВ 2003, WindowsВ XP, or WindowsВ 2000 with SP3. Windows InstallerВ 3.0 is included in WindowsВ XP with Service PackВ 2 (SP2). It is available as a redistributable for WindowsВ 2000 Server with Service PackВ 3 (SP3) and WindowsВ 2000 Server with Service PackВ 4 (SP4), WindowsВ XP RTM and WindowsВ XP with Service PackВ 1 (SP1), and Windows ServerВ 2003 RTM.

Windows InstallerВ 2.0 is contained in Windows ServerВ 2003 and WindowsВ XP.

Windows InstallerВ 2.0 is available as a package for installing or upgrading to Windows InstallerВ 2.0 on WindowsВ 2000. This package should not be used to install or upgrade Windows InstallerВ 2.0 on Windows ServerВ 2003 and WindowsВ XP.

Patch Packages

A Windows Installer patch (.msp file) is a file used to deliver updates to Windows Installer applications. The patch is a self-contained package that contains all the information required to update the application. A patch package (.msp file) can be much smaller than the Windows Installer package (.msi file) for the entire updated application. For more information about delivering smaller updates to applications, see Reducing Patch Size.

A patch package contains the actual updates to the application and describes which versions of the application can receive the patch. Patches contain at minimum two database transforms. One transform updates the information in the installation database of the application. The other transform adds information that the installer uses for patching files. The installer uses the information provided by the transforms to apply patch files that are stored in the cabinet file stream of the patch package. A patch package does not have a database like an installation package (.msi file.)

Beginning with Windows Installer version 3.0, patch packages can contain information that describe the patching sequence for the patch relative to other updates in the MsiPatchSequence table and additional descriptive information in the MsiPatchMetadata table.

Users can install applications and updates from a network administrative image. Although patch packages can be applied to administrative installations, the recommended method to deliver updates is to have users install the original application and then apply the patches to the local instance of the application on to their computer. This keeps users in synchronization with the administrative image. If a patch is applied to the administrative installation, all clients of that administrative installation must recache and reinstall the application to receive the update. Until a user recaches and reinstalls, the user is unable to install-on-demand and repair installations from the patched administrative installation.

Beginning with Windows Installer 3.0, non-administrators can apply patches to per-user-managed applications after the patch has been approved as trusted by an administrator. For more information on how to do this, see Patching Per-User Managed Applications. Another method is to use least privileged user account patching.

If the AllowLockdownPatch policy has been set, non-administrator users can apply a patch to an existing application while running an installation at elevated privileges. This method is not recommended because it enables untrusted patches to be applied to an application that can run with elevated privileges.

Patch packages are comprised of the following parts. For more information about the construction of patch packages, see Creating a Patch Package.

Summary Information Stream

The summary information stream of the patch package provides information about the identity and purpose of the patch.

The summary information stream holds a minimum of the following:

• A GUID that uniquely identifies the patch. The GUID for this patch is appended with a list of GUIDs for earlier patches that are replaced by this patch.
• A semicolon-delimited list of product codes for valid targets for this patch.
• A semicolon-delimited list of transform substorage names in the order they are to be processed.
• A semicolon-delimited list of sources for this patch.

Transform Substorage

A patch package contains transforms that can add or remove files, registry entries, user interfaces, and customizations. Transforms are included as substorages in the package. A patch package contains two transforms for each target database. One transform is the actual updates to the installation database and is generated from the differences between the original and updated images of the installation package. The other transform adds entries to the Patch, PatchPackage, Media, InstallExecuteSequence, and AdminExecuteSequence tables. Information in the substorage ties it to a specific UpgradeCode, ProductCode, ProductVersion, and ProductLanguage. A patch package that can be applied to multiple targets contains more than one pair of these transforms.

Cabinet File Stream

The cabinet file stream included in a patch can contain these types of files:

• Patch files containing the information required to change the old version of the file into the new version. A single patch file can be used to update one or more old versions of a file.
• Additional files being added to the application that are not present in the old version.
• An entire replacement file. In the rare case where the new version of a file is smaller than the patch required to update the old version of that file, the new file can be included in its entirety. These are new files that are installed over their old versions.