Patching

An application that has been installed using the Microsoft Windows Installer can be upgraded by reinstalling an updated installation package (.msi file), or by applying a Windows Installer patch (an .msp file) to the application.

A Windows Installer patch (.msp file) is a self-contained package that contains the updates to the application and describes which versions of the application can receive the patch. Patches contain at a minimum, two database transforms and can contain patch files that are stored in the cabinet file stream of the patch package. For more information about the parts of a Windows Installer patch package, see Patch Packages.

Servicing applications by delivering a Windows Installer patch, rather than a complete installation package for the updated product can have advantages. A patch can contain an entire file or only the file bits necessary to update part of the file. This can enable the user to download an upgrade patch that is much smaller than the installation package for the entire product. An update using a patch can preserve a user customization of the application through the upgrade.

**Windows Installer 4.5 and later:В В **

Beginning with Windows Installer 4.5, developers can mark components in a patch with the msidbComponentAttributesUninstallOnSupersedence value in the Component table. If a subsequent patch is installed, marked with the msidbPatchSequenceSupersedeEarlier value in its MsiPatchSequence table to supersede the first patch, Windows Installer 4.5 and later can unregister and uninstall components marked msidbComponentAttributesUninstallOnSupersedence to prevent leaving behind unused components on the computer. If the component is not marked with with this bit, installation of the superseding patch can leave an unused component on the computer. Setting the MSIUNINSTALLSUPERSEDEDCOMPONENTS property has the same effect as setting this bit for all components.

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

Developers who use Windows Installer 3.0, and author patch packages that have the MsiPatchSequence table can create patch packages that do the following:

• Use the product baseline cached by the installer to more easily service applications with smaller delta patches. For more information about using the product baseline, see Reducing Patch Size.
• Skip actions associated with specific tables that are unmodified by the patch. This can significantly reduce the time required to install the patch. For more information about which tables can be skipped, see Patch Optimization.
• Create and install patches that can be uninstalled singly, and in any order, without having to uninstall and reinstall the entire application and other patches. For more information about uninstalling patches, see Removing Patches.
• Apply patches in a constant order regardless of the order that the patches are provided to the system. For more information about how the Windows Installer determines the sequence used to apply patches, see Sequencing Patches.
• Apply patches to an application that has been installed in a per-user-managed context. For more information, see Patching Per-User Managed Applications.

**Windows Installer 2.0:В В **

The MsiPatchSequence table is not supported. Beginning with Windows Installer 3.0, patch packages can contain information that describes the patching sequence for the patch relative to other updates and additional descriptive information.

The recommended method for creating a patch package is to use patch creation tools such as Msimsp.exe and Patchwiz.dll. Developers can generate a patch creation file as described in the section: Creating a Patch Package. The creation of a small update patch is described in the section: A Small Update Patching Example.

Microsoft Windows Installer accepts a Uniform Resource Locator (URL) as a valid source for a patch. For more information about how to install a patch located on a Web server, see Downloading and Installing a Patch From the Internet.

A single Windows Installer patch (.msp file) can be applied to the installation package when installing an application for the first time. For more information, see Patching Initial Installations.

It is not possible to eliminate all circumstances when the application of a patch may require access to the original installation source. However, to minimize the possibility that your patch will require access to the original source, adhere to the points listed in the following section: Preventing a Patch from Requiring Access to the Original Installation Source.

To minimize the possibility that your patch is not broken by a subsequent customization transform, typically the patch is installed first, followed by the customization. Installing customization transforms first, and then the patch, may break the customization. For more information about patching customized applications, see Patching Customized Applications.

Sequencing Patches

Beginning with Windows Installer 3.0, authors can add patch sequencing information to the patch package database in the MsiPatchSequence table. The installer can use this information to determine which patches are applicable to an installation package, to determine the best patching sequence, and to install patches in an constant order independent of the order they are provided to the system.

Windows Installer 2.0: Not supported. Windows Installer versions previous to Windows Installer 3.0 install patches in the order that they are provided to the system regardless of whether they contain an MsiPatchSequence table.

The following are required to use the patch sequencing functionality.

• Patch packages (.msp files) must have a MsiPatchSequence table containing sequencing information. The installer installs patches that do not have a MsiPatchSequence table in the order that they are provided to the system.
• Patches are installed using Windows Installer 3.0 or later.

Windows Installer version 3.0 has the following functions that applications can use to determine the best patching sequence.

• The MsiDeterminePatchSequence function takes a list of patches and determines in what sequence they can be applied to an installed product. This function accounts for any patches or products that have already been installed on the system.
• The MsiDetermineApplicablePatches function takes a list of patches and determines in what sequence they can be applied to an installed product. This function does not account for any patches or products that have already been installed on the system.

Windows Installer version 3.0 can apply multiple patches to a product in a single patching installation. The group of patches can contain patches that include patching sequence information (a MsiPatchSequence table) and patches that do not. The Windows Installer installs the patch packages without this table in the order that they are provided to the system. The installer accounts for patch packages that lack a MsiPatchSequence table, but that have been marked as obsolete or superseded patches by the method described in the following section.

When Windows Installer version 3.0 installs multiple patches, it follows these steps to determine the sequence in which individual patches are applied to the product:

Installed patches without a MsiPatchSequence table are put in the sequence in the order that they were applied to the product. The first patch that was applied is placed first in the sequence.

New patches without a MsiPatchSequence table are put in the sequence. These patches are being applied by the current patching installation. They are put in the order that they are provided to the system, and placed after all the patches in step 1.

Obsolete patches are eliminated from the sequence of patches.

A patch package can specify in the Revision Number Summary property an explicit list of obsolete patches to be removed by the patch. This list is intended for use by Windows Installer versions earlier than version 3.0. Windows Installer version 3.0 removes the patches marked as obsolete from the sequence, only if the patches do not have the MsiPatchSequence table.

The installer steps through the patching sequence and determines which patches are applicable in the given sequence. When multiple patches are applied to a product, each patch in the sequence also transforms the product’s installation database (.msi file). A patch is applicable in a particular sequence only if its database transform is capable of taking the product code, version, language, and upgradecode that result from applying the transforms of all preceding patch packages to the product database. The installer eliminates any inapplicable patches from the sequence.

The installer begins placing patches that have sequencing information in their MsiPatchSequence table. Minor upgrade patches that have the MsiPatchSequence table are placed in the sequence after the patches that were sequenced in previous steps and in the order of their lowest to highest product versions after being upgraded. Windows Installer then eliminates any minor upgrade patches that are inapplicable in this sequence.

Small update patches targeting minor upgrades having a MsiPatchSequence table, are assigned to the highest version of the minor upgrade patch in the sequence.

All small update patches that remain unassigned after the previous steps, and that have the MsiPatchSequence table, are put in the sequence before the first minor upgrade that has the MsiPatchSequence table, and after the .msi installation database and any patches without the MsiPatchSequence table. Windows Installer then eliminates any small update patches that are inapplicable in this sequence.

Windows Installer version 3.0 eliminates superseded patches from the sequence. When a patch supersedes patches that occur earlier in the patch sequence, the patch contains all the fixes in the earlier patches. The earlier patches are no longer required. The Windows Installer requires the information in the MsiPatchSequence table to eliminate superseded patches.

Patches intended to supersede an earlier set of patches must be authored to supersede the earlier patches in all patch families. Small update patches can only supersede small updates. Minor upgrades can supersede both small updates and other minor upgrades.

Small update patches that carry MsiPatchSequence tables, get sequenced within product versions according to the sequencing information in their MsiPatchSequence tables. This determines the final patching sequence.

A patch that should no longer be used can be eliminated from the patching sequence. For more information about how to eliminate patches from the patching sequence, see Eliminating Patches.

For an example of how the MsiPatchSequence table can be used to apply patches in the order in which they are authored, see the Multiple Patching Example.

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.