MSI Patching

What is patching?

A patch is an updated version for an application. One can obtain patches from the software manufacturers or internal developers of the original program. One can update an existing application without uninstalling the product. This preserves the customizations of the installation and potentially reduces the cost to make the change. The patch might change only a few bytes of a single application file, making it more efficient to distribute those few bytes, as opposed to uninstalling and redeploying the entire product. At the other extreme, a patch might change all of the files and registry keys in a product. A patch package (.msp) does not include a database like a regular installation package. Instead it contains, at a minimum, one database transform (a transform that adds information to the database of its target installation’s .msi package.) Windows Installer uses this information to apply the patch files that are stored in the cabinet file stream of the patch package.

Patch installation packages comprise the following parts:

• Summary information stream
• Transform sub storage
• Cabinet file stream

Summary information stream

Each sub storage has its own summary information stream, which contains at least the following:

• A GUID that uniquely identifies the patch. The GUID for this patch is appended to a list of GUIDs for earlier patches that are replaced by this patch.
• A list of product codes delimited by semicolons, specifying the valid product configurations to which the patch might be applied targets for this patch.
• A semicolon-delimited list of transform sub-storage names, in the order they are to be applied (sub-storages are described in the following subsection).
• A list of sources delimited by semicolons for this patch.

Transform sub-storage

Transforms can update the database of an application. A transform might be used to add or remove new files, registry entries, user interfaces, or customizations. Each such transform is included in a patch package as sub-storage.

Two transforms are stored in a patch for each target database, and more than one pair of transforms can be stored in a patch if there are multiple targets. The first transform modifies the target to the new version. The second transform adds entries to the Patch, Patch Package, Media, InstallExecuteSequence, and AdminExecuteSequence tables that provide file patching instructions to Windows Installer.

If the target of the installation is an administrative image, an administrator can have Windows Installer apply transforms during the creation of the image. These changes persist in the administrative image of the Windows Installer package of the application. If the target of the installation is a local installation versus an administrative image, Windows Installer reapplies the transforms each time a maintenance-mode or uninstall operation is invoked for the application.

Cabinet file stream

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

Patch files:

Contain the information required to transform the previous version of the file into the new version. One can use a single patch file to update one or more old versions of a file.

New files:

Are added to the application and are not present in the previous version.

Entire file:

Replaces the previous version. In the rare case where the new version of a file is smaller than the patch that would be required to update the previous version of that file, one can include the new file in its entirety as a patch.

---

Why patching?

Advantage: creates a very small MSP file which includes only the changes required to update the MSI, which might be good for Internet downloads. Disadvantages: with anything before MSI 3.0 one need to do a complete reinstall of the application in order to install the patch file, which can be a huge waste of time for small patches on large installations; also, MSPs aren’t so great for adding new features, components, and such-better save that for MSI upgrades.

---

How to apply patch?

One can use the command-line option to apply a patch to software installed on a computer. The command-line option requires that one supply values for the REINSTALL and REINSTALLMODE properties when applying the patch. One do not need to re-cache the *.msi file, or the “v” argument, for REINSTALLMODE because the local copy of the *.msi, in the %windir%\installer directory, is not modified.

Patch installations directly on a local computer

To patch installations directly on a local computer, run the following command:

Msiexec /p patch.msp REINSTALL=[Feature list] REINSTALLMODE=omus

The parameters for REINSTALLMODE are defined in an earlier table, Table 4.

The original source of the installation is required when one applies a patch. However, if the original media are not available, one can use a network location. After one applies the patch, it is cached on the client computer so it can perform an installation-on-demand, a reinstallation, a repair, or a removal of the application.

Patch installations using an administrative image

To patch installations using an administrative image:

1. Create the administrative image, if it does not already exist, with the following command line:
2. msiexec /a <path to the MSI>\package.msi
3. Update the administrative image by running the following command-line option:
4. msiexec /a <path to administrative image>\package.msi /p <path>\patch.msp
5. This update changes the *.msi on the administrative image by directly applying the patch.
6. Update users’ computers by running the installation of the application from the administrative image using one of the following command-line options:
7. msiexec /fvomus <path to administrative image>\package.msi REINSTALL=ALL
8. msiexec /i <path to administrative image>\package.msi REINSTALL=ALL REINSTALLMODE=vomus

Applying a patch to an administrative installation modifies the original *.msi. The “v” argument is required in this situation to cache the modified *.msi to the local system. Failure to cache the *.msi prevents the application from performing maintenance operations. The consequences of this are discussed in the following paragraphs.

Note: A patch changes the package code of an .msi file. To allow Windows Installer to perform maintenance operations such as adding, removing, or repairing an installation, the package codes for the installed application and the source must match. Therefore, a computer that still has the original package code installed cannot be maintained by using a patched administrative image until one update the computer.

If the deployment of the patched administrative image of an application is an update, not a new installation, and it takes a considerable amount of time to reach all target client computers, it is recommended to take one of the following actions:

• Create a new administrative image for the application and apply the patch to it. One can then distribute this new source to the appropriate systems. After one upgrades all systems, one can remove or patch the original administrative image to provide a redundant source.
• Patch the clients directly on a local computer, as described in “Applying Patches to Installed Software” in this paper. This method does not modify the .msi cached on the local system, and therefore the .msi in the administrative image and on the local system remain identical.

Either of the two preceding methods can prevent the application on the client computer and the source administrative image for the application from becoming unsynchronized. If the client computer and source administrative image for an application become unsynchronized, Windows Installer cannot perform maintenance operations for the application, such as adding, modifying, removing, or repairing an installation.

Note: To remove a patch that one has applied, one must remove the entire application, and then reinstall the application without the patch. There is no way to roll back the changes a patch applies to the original package.

Patching an Administrative Image

An administrative image can be patched by using the command-line option mentioned earlier. The resulting administrative image is the same as that produced by an administrative installation that uses a full-product CD that includes the update. The changes made by the patch persist on the administrative image. However, these changes are not automatically propagated to existing installations. The application must be reinstalled by using a command with the following arguments: REINSTALL and REINSTALLMODE properties. The process of patching multiple administrative images by using a software-distribution technology can be automated.

For example, using Systems Management Server (SMS), one can update the distribution points from an updated source. The application cannot be reinstalled from Add or Remove Programs in Control Panel. After the update is completed, an updated .msi file is cached on the client computer. The most common problem during patching software occurs when one do not enter the REINSTALLMODE and the REINSTALL arguments on the command line. If these two are not specified, the patch is not applied. Also, if the patch adds a new feature to the application, one must enter ADDLOCAL on the command line, specifying the feature name of that new feature. However, when one use ADDLOCAL to specify a feature name, do not specify REINSTALL= ALL. Instead, the REINSTALL argument must be a list of the features delimited by commas, which need to be reinstalled. If features that were previously installed locally are now advertised after one applies a patch to an installation, it is a sign of one of the problems described in the preceding two paragraphs. 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. Servicing applications by delivering a Windows Installer patch, rather than a complete installation package for the updated product can have the following 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.
• A Windows Installer patch (.msp file) is a self-contained package that 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 and can contain patch files that are stored in the cabinet file stream of the patch package. Beginning with Windows Installer version 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.

Microsoft Windows Installer accepts a Uniform Resource Locator (URL) as a valid source for a patch. A single Windows Installer patch (.msp file) can be applied to the installation package when installing an application for the first time. To minimize the possibility that the 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

Note: It is not possible to eliminate all circumstances when the application of a patch may require access to the original installation source. To minimize the possibility that the 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.

Downloading and Installing a Patch from the Internet

Microsoft® Windows® Installer accepts a Uniform Resource Locator (URL) as a valid source for a patch. To install a patch located on a Web server at http://MyWeb/MyPatch.msp, use the following command line:

Msiexec /p http://MyWeb/MyPatch.msp

A Patch can be installed by using a script like the following:

<SCRIPT LANGUAGE="VBScript">

<!--

Dim Installer

On Error Resume Next

Set Installer=CreateObject("WindowsInstaller.Installer")

Installer.ApplyPatch "http://server/share/patch.msp", "", 0, "REINSTALL=ALL REINSTALLMODE=omus"

Set Installer=Nothing

-->

</SCRIPT>

Note that because the Installer object is not marked as SafeForScripting on the user’s computer, users need to adjust their browser security settings for the example to work correctly.

User Account Control (UAC) Patching

This topic is pre-release documentation and is subject to change in future releases.]User Account Control (UAC) patching enables the authors of Windows Installer installations to identify digitally-signed patches that can be applied in the future by non-administrator users. If a non-administrator attempts to apply a patch to an application, and the following conditions have not been met, Windows Vista will notify the user that administrator authorization is required before installing the patch. A non-administrator can continue installing the patch, without needing to obtain additional administrator authorization, provided the following conditions are met.

• The application was installed on Windows Vista or Windows XP using Windows Installer 3.0 or later.
• Windows Server “Longhorn”:  Not supported.
• If the application was installed on Windows XP, the application must also have been installed from removable media, such a CD-ROM or DVD disk. This restriction does not apply if the application was installed on Windows Vista.
• The application was not installed from an administrative installation source image.
• The application was originally installed per-machine. For information about how to enable non-administrators to apply patches to per-user-managed applications after the patch has been approved as trusted by an administrator, see Patching Per-User Managed Applications.
• The MsiPatchCertificate table is present in the Window Installer package (.msi file) and contains the information needed to enable UAC. The table and information may have been be included in the original installation package or added to the package by a Windows Installer patch file (.msp file).
• The patches are digitally signed by a certificate listed in the MsiPatchCertificate table.
• The digital signature on the patch package can be verified against the certificate in the MsiPatchCertificate table.
• The signer certificate used to verify the digital signature on the patch package is valid and has not been revoked.
• Least-privilege patching has not been disabled by setting the MSIDISABLELUAPATCHING property or the DisableLUAPatching policy.

A patch that has been applied using UAC patching can also be removed by a non-administrator.

Administrators can apply patches to per-machine installed products regardless of the application’s UAC setting.

An administrator can disable least-privilege patching on the computer by setting the DisableLUAPatching policy to 1. One can set the MSIDISABLELUAPATCHING property to 1 during the initial installation of an application to prevent least-privilege patching for that application only.

This functionality is available beginning with Windows Installer version 3.0. User Account Control (UAC) patching was called least-privilege user account (LUA) patching in Windows XP. LUA patching is not available on Windows 2000 and Windows Server 2003.

Patching Per-User Managed Applications

Beginning with Windows Installer 3.0, it is possible to apply patches to an application that has been installed in a per-user-managed context after the patch has been registered as having elevated privileges. Patches to applications that are installed in a per-user managed context using versions of Windows Installer earlier than version 3.0 cannot be applied.

An application is installed in the per-user-managed state in the following cases.

• The application was installed with administrator authorization via User Account Control (UAC) in Windows Vista.
• The per-user installation of the application was performed using deployment and Group Policy.
• The application was advertised to a specified user and installed by the method described in Advertising a Per-User Application to Be Installed with Elevated Privileges.
• The application was installed per-user while the AlwaysInstallElevated policy was set by the method described in Installing a Package with Elevated Privileges for a Non-Admin.

Privileges are required to install an application in the per-user-managed context; therefore, future Windows Installer reinstallations or repairs of the application are also performed by the installer using elevated privileges. This means that only patches from trusted sources can be applied to the application. Beginning with Windows Installer 3.0, one can apply a patch to a per-user managed application after the patch has been registered as having elevated privileges. To register a patch as having elevated privileges, use the MsiSourceListAddSourceEx function or the SourceListAddSource method of the Patch object, with elevated privileges. After registering the patch, one can apply the patch using the MsiApplyPatch or MsiApplyMultiplePatches functions, ApplyPatch or ApplyMultiplePatches methods of the Installer Object, or the /p command-line option.

Note: A patch can be registered as having elevated privileges before the application is installed.

Patching Initial Installations

A single 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 one 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”

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.

msiexec /I package.msi  PATCH=“c:\directory\patch.msp;c:\directory\patch2.msp;c:\directory\patch3.msp”

Patching Customized Applications

When installing a patch and one or more customization transforms to an application, the patch is typically installed first, followed by the customization. By design, the patch is not broken by the subsequent installation of the customization. However, installing the transforms first, and then the patch, may break the customization.

For example, a break in the customization could occur when a patch is used to update a product from version 1 to version 2 and a customization transform that works for version 1 does not work for version 2. In this case, the version update patch cannot be applied to a customized product without first uninstalling and then reinstalling the original product.

Note that version validation used by the Microsoft Office Customization Wizard permits customizations to be used across changes in the product version. It is the responsibility of the developer to author their customization transform to be compatible across all versions as necessary.

Preventing a Patch from Requiring Access to the Original Installation Source

It is not possible to eliminate all circumstances under which the application of a patch may require access to the original installation source. Adhere to following points to minimize the possibility that the patch will require access to the original source:

• Use whole-file only patches. This eliminates the need to create binary patches for all previously released versions of the file. Note that whole file patches are generally larger in size than binary patches. One can easily set a patch to be a whole file patch by authoring the IncludeWholeFilesOnly property with a value of 1 (one) in the Patch Creation Properties (PCP) file.
• Ensure that none of the custom actions access the original source location.
• Ensure that the ResolveSource action is conditionalized so that it only runs when needed, or alternatively is not present at all.
• Populate the MsiFileHash Table for all unversioned files. The Windows Installer SDK tool, Msifiler.exe, can easily do this for one.
• Ensure that all files have the correct version and language information. The Windows Installer SDK tool, Msifiler.exe, can easily do this for one.

Source Requirements When Patching

Access to the original installation sources may be required to apply the patch in the following cases:

• Prior to Windows Installer 2.0, the application of a patch requires access to the original installation source.
• The patch applies to a feature that is currently run from source. In this case, the feature is transitioned from the run-from-source state to the local state.
• The patch applies to a component that has a missing or corrupted file.
• The patch applies to a file in a component that also contains unversioned files with no MsiFileHash entries. A populated MsiFileHash Table is required to prevent unnecessary recopying of unversioned files from the source location.
• The patch was applied with a REINSTALLMODE of amus or emus. This option is dangerous in that it performs file copy operations regardless of file version. This can lead to down-revving of files and almost always requires the source. The recommended REINSTALLMODE value is omus.
• The cached package for the product is missing. The cached package is needed for application of a patch. The cached package is stored in the %windir%\Installer folder.
• The package is authored to make a call to the ResolveSource Action. This action should generally be avoided or conditionalized appropriately, because its execution always results in an access to the source.
• The package has a custom action that attempts to access the source in some manner. The most common example is a type 23 concurrent installation custom action.

Note: Concurrent installations are not recommended for the installation of applications intended for release to the public. For information about concurrent installations please see Concurrent Installations.

• The patch package consists of binary patches that do not apply to the current version of the file on the computer.

Consider the following example where Windows Installer requires access to the original source when applying a patch:

• Install RTM version of the product Example.
• Apply patch Qfe1.msp to the computer. This patches version 1.0 of Example.dll to version 1.1.
• A new patch, Qfe2.msp is provided, which updates Example.dll to version 1.2 and obsoletes Qfe1.msp. However, the patch was only created to target version 1.0 of Example.dll because it was generated using the RTM version of the product. Example.dll version 1.2 includes the fix contained in Example.dll version 1.1, but the .msp file was generated between the RTM and QFE2 images. So, when Qfe2.msp is applied to the computer, Windows Installer needs to access the original source. The binary patch for Example.dll cannot apply to version 1.1; it can only apply to version 1.0. This results in the Installer recopying version 1.0 of Example.dll from the original source location so that the patch can be applied successfully.

---

What is the difference between Patch and Transforms?

Patching is defined as:

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.

Servicing applications by delivering a Windows Installer patch, rather than a complete installation package for the updated product can have the following 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.

A Windows Installer patch (.msp file) is a self-contained package that 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 and can contain patch files that are stored in the cabinet file stream of the patch package. Beginning with Windows Installer version 3.0, patch packages can contain information that describes the patching sequence for the patch relative to other updates and additional descriptive information.

Transform is defined as:

A transform is a collection of changes applied to an installation. By applying a transform to a base installation package, the installer can add or replace data in the installation database. The installer can only apply transforms during an installation.

---

What is the version control in patching?

Using the ProductVersion property when creating upgrades:

Minor upgrades (which change the value of the ProductVersion property but not the value of the ProductCode property) form the framework for the sequencing logic in Windows Installer. When Windows Installer receives a set of minor upgrades to apply, the new value of the ProductVersion property for each patch is examined and the set of resultant versions will generate (with few exceptions) a single optimal order of application for the patches.

Figure 1 Ordering patches based on the ProductVersion property

Adding small updates to the set of patches for a product does not change this fundamental order defined by the value of the ProductVersion property. These new patches by definition do not change the ProductVersion property when applied to a product; however, the value of the ProductVersion property is still critical in determining the applicability of small updates just as it is a key aspect of minor upgrade applicability checks.

Small updates include as part of their target validation data a declaration of the ProductVersion property to which they can apply. This version targeting data provides the first rough order when determining the optimal order of application for small updates.

Figure 2 ordering small updates based on the values of the ProductVersion property

Unfortunately, when multiple small updates apply to the same version of the product, the value of the ProductVersion property is the same for all of the small updates. In the example above, QFE1, QFE2, and QFE4 all apply to version 1.1 of the product, but there is no way to determine the order to apply those patches. Therefore, the value of the ProductVersion property does not provide enough information about the patches for Windows Installer to determine the best order of application. Given a set of small updates (or a combination of small updates and minor upgrades), it is not possible to define an order of application unambiguously for the patches without some data about:

• Which patches update similar functionality?
• What restrictions exist for the application order of related patches?
• When the changes made by one patch are included in another.
• What to do when patches are uninstalled.

This information is all provided by the sequencing metadata.

Payload: The updates to the product’s files that are contained within a patch. The payload may consist of full copies of a file, a binary delta from one or more earlier versions of a file, or a combination of the two. However, the payload may not have full copies and binary deltas for the same file.

---

Removing Patches

Beginning with Windows Installer version 3.0, it is possible to 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. Windows Installer 3.0 also enables Patch Packages to be authored with a MsiPatchSequence Table that contains patch sequencing information. With versions of Windows Installer earlier than Windows Installer 3.0, the only method to remove particular patches from an application is to uninstall the entire patched application and then reinstall without reapplying any patches being removed. Whether a patch can be uninstalled depends upon how the patch was authored, the version of Windows Installer used to install the patch, and the changes made by the patch to the application. If a patch is not uninstallable, then the only way to remove the patch is to uninstall the entire application and reinstall without applying the patch being removed.

One can uninstall one or more patches using a command line option, the scripting interface, or by calling MsiRemovePatches from another application.  The value of the MSIPATCHREMOVE property lists the patches to be uninstalled. For each patch in the list, the installer verifies that the patch is uninstallable. If the user does not have privileges to remove the patch, the patch is unknown for the product, patch policy prevents removal, or the patch was marked as not uninstallable, the installer returns an error that indicates a failed installation transaction.  Once the patch is verified as removable, the installer removes the patch from the patch application sequence. Note that removing patches from the sequence can cause patches marked obsolete or superseded to become active.

All patches selected for removal are listed in the MsiPatchRemovalList property. This property is a private property that is set by the installer and can be used in conditional expressions or queried by custom actions. The property contains the list of patch code GUIDs of patches to be removed. A custom action can determine whether the installation state of the patch is applied, obsolete or superseded by calling the MsiGetPatchInfoEx or the PatchProperty property of the Patch Object. After a patch is removed the state of the application is the same as if the patch was never installed. If possible, the installer restricts the process to the subset of features affected by the patch being removed. The installer automatically sets the REINSTALL property to the list of affected features. Files that were added by the patch are removed and files that were modified by the patch are overwritten. Files and registry entries are restored to the version expected by the product minus the patch. Features and components that were added by the patch are unregistered from the application.

Uninstallable Patches

Whether a patch can be uninstalled depends upon how the patch was authored, the version of Windows Installer used to install the patch, and the changes made by the patch to the application. If a patch is not uninstallable, then the only way to remove the patch is to uninstall the entire application and reinstall without applying the patch being removed.

Patches can be uninstalled with Windows Installer version 3.0 by using Command Line Options, the MsiRemovePatches function, or the RemovePatches method as described in the Uninstalling Patches section. The Windows Installer verifies that each of the patches listed for removal in the MSIPATCHREMOVE property is uninstallable. If the user does not have privileges to remove the patch, the patch is unknown for the product, patch policy prevents removal, or the patch was marked as not uninstallable, the installer returns an error indicating a failed installation transaction.

Patches that are Not Uninstallable

A patch (.msp file) applied to an installed application is not uninstallable in the following cases. The only method to remove a patch that is not uninstallable is to uninstall the patched application and then reinstall the application without reapplying the patch. In this case, one must reapply any patches that you do not wish to be removed from the application.

• Patches applied using a version of Windows Installer that is less than Windows Installer versions 3.0 are not uninstallable.
• Patches applied to applications installed on a computer that has had the DisablePatchUninstall policy set by an administrator are not uninstallable. When this machine policy has been set, no patches on the computer can be uninstalled, even by an administrator.
• Patches that do not have an MsiPatchMetadata table in their database are not uninstallable.
• Patches that do not include the following row in their MsiPatchMetadata table are not uninstallable. The patch is not uninstallable for other values of Company, Property, and Value.

Company	Property	Value
{Null}	AllowRemoval	1

• The patch has been applied to an application installed in a context for which the user has insufficient privileges to uninstall patches. The words “Not Allowed” in the following table indicate that an administrator or non-administrator user cannot uninstall patches from patched applications installed in this context. The word “Allowed” in this table means that privileges do not prevent an administrator or non-administrator user from uninstalling patches, however for any of the other reasons discussed in this section, it still might not be possible to uninstall the patch.

application Installation Context	Administrator Uninstall of Patch	Non-Administrator Uninstall of Patch
Per-Machine	Allowed	Generally Not Allowed The only exception is if the patch was applied using (LUA) patching. A patch marked as a LUA patch is uninstallable by either administrators or non-administrators. LUA patching is only available for packages installed per-machine from media and require special authoring.
Per-User Non-Managed for Current User	Allowed	Allowed
Per-User Non-Managed for Different User	Not Allowed	Not Allowed
Per-User Managed for Current User	Allowed	Not Allowed
Per-User Managed for Different User	Not Allowed	Not Allowed

• A major upgrade applied by a patch is not uninstallable. Major Upgrades of an application should be performed by installing the upgraded application (.msi file) rather than a patch.
• Patches applied to an administrative installation are not uninstallable. Patching administrative installations is not recommended. The current set of patches should be applied on the user’s computer after the user installs the application from the administrative image. This can prevent the package code cached on the user’s computer from becoming different than the package code on the administrative installation. If the package code cached on the user’s computer becomes different from that on the administrative installation, reinstall the application from the administrative installation and then patch the client computer.
• When a patch adds new content to any of the tables in the following list, Windows Installer marks the patch as being not uninstallable. An uninstallable patch can add new files, assemblies, registry entries, components, or features to an installation by adding new rows to database tables that are not included in this list.
  • BindImage
  • Class
  • Complus
  • CreateFolder
  • DuplicateFile
  • Environment
  • Extension
  • Font
  • IniFile
  • IsolatedComponent
  • LockPermissions
  • MIME
  • MoveFile
  • ODBCAttribute
  • ODBCDataSource
  • ODBCDriver
  • ODBCSourceAttribute
  • ODBCTranslator
  • ProgId
  • PublishComponent
  • RemoveIniFile
  • SelfReg
  • ServiceControl
  • ServiceInstall
  • TypeLib
  • Verb

Note: If a patch adds new content to the RemoveFile or RemoveRegistry tables, Windows Installer does not mark the patch as being not uninstallable. However, the patch is not uninstallable unless the resource to remove the new content does not already exist in the original installation package. For example, if the patch adds a new row to the RemoveFile table, the removed file cannot be restored by uninstalling the patch if the file is external to the File table. The file must have been authored in the File table of the original package plus applied patches for the patch to be uninstallable.

Uninstalling Patches

Beginning with Windows Installer version 3.0, it is possible to uninstall some patches from applications. The patch must be an uninstallable patch. When using a Windows Installer version less than version 3.0, removing patches requires uninstalling the patch product and reinstalling the product without applying the patch.

When an uninstallation of a patch is invoked by any of the following methods, the installer attempts to remove the patch from the first product visible to the application or user requesting the uninstallation. The installer searches for patched products in the following order: per-user managed, per-user unmanaged, per-machine.

Uninstalling a patch using MSIPATCHREMOVE on a command line

One can uninstall patches from a command by using msiexec.exe and the Command Line Options. The following sample command line removes an uninstallable patch, example.msp, from an application, example.msi, using the MSIPATCHREMOVE property and the /i command line option. When using /i, the patched application can be identified by the path to the application’s package (.msi file) or the application’s product code. In this example, the application’s installation package is located at “\\server\share\products\example\example.msi” and the application’s ProductCode property is “{0C9840E7-7F0B-C648-10F0-4641926FE463}”. The patch package is located at “\\server\share\products\example\patches\example.msp” and the patch code GUID is “{EB8C947C-78B2-85A0-644D-86CEEF8E07C0}”.

Msiexec /I {0C9840E7-7F0B-C648-10F0-4641926FE463} MSIPATCHREMOVE={EB8C947C-78B2-85A0-644D-86CEEF8E07C0} /qb

Uninstalling a patch using the standard command line options

With Windows Installer version 3.0, the standard command line options used by Microsoft Windows Operating System Updates (update.exe) to uninstall Windows Installer patches from a command line.

The following command line is the standard command line equivalent of the Windows Installer command line used to uninstall a patch using the MSIPATCHREMOVE property. The /uninstall option used with the /package option denotes the uninstallation of a patch. The patch can be referenced by the full path to the patch or by the patch code GUID.

Msiexec /package {0C9840E7-7F0B-C648-10F0-4641926FE463} /uninstall {EB8C947C-78B2-85A0-644D-86CEEF8E07C0} /passive

Note: The /passive standard option is not an exact equivalent of the Windows Installer /qb option.

Patch Uninstall Custom Actions

To have a custom action run when a particular patch is uninstalled the custom action must either be present in the original application or be in a patch for the product that is always applied. There is no method for marking a custom action within a patch package to be run when the patch is uninstalled because the installer does not apply the patch packages being uninstalled.

Developers can use the MsiPatchRemovalList property to author a Windows Installer package or patch that performs custom actions on the removal of a patch. The custom action can be authored into the original installation package, a patch that has already been applied to the package, or a patch that is not an uninstallable patch. The custom action can be conditionalized on the MsiPatchRemovalList property in the sequence tables. See Using Properties in Conditional Statements for more information about conditionalizing actions.

The custom action can obtain the GUIDs of patches being removed from the value of the MsiPatchRemovalList property. The custom action can determine whether the installation state of the patch is applied, obsolete, or superseded by calling the MsiGetPatchInfoEx or the PatchProperty property of the Patch object.

If the custom action requires special metadata from the patch, the patch should contain a custom action that writes the metadata to a registry or file location when the patch is applied. The custom action in the original application or a patch that is always applied can obtain the information needed to remove the patch’s changes.

Patches making changes that are difficult to undo correctly should not be marked as uninstallable patches.

Restoring the Patched Version of the file

If a file of a shared component is updated by a patch, the change affects all applications that share the component. When the patch is removed, again, the change affects all applications that share the component. This means that removal of a patch by one application can restore the file of the shared component to a lower version than required by another application. This could fix the first application, but cause the second application to stop working. In this case, the second application can be repaired by reinstalling the second application using the methods describe in Reinstalling a Feature or Application. This will restore the patched version of the file.

---

Creating a Patch Package

Developers create a patch package by generating a patch creation file and using Msimsp.exe to call the UiCreatePatchPackageEx function in Patchwiz.dll. Msimsp.exe and Patchwiz.dll are provided in the Windows Installer SDK. Because the application of a patch to a Windows Installer package results in the installation of the original sources using a new .msi file, the new .msi file must remain compatible with the layout of the original source. When one author a patch package one must use an uncompressed setup image to create a patch, for example, an administrative image or an uncompressed setup image from a CD-ROM. This has following restrictions:

• Do not move files from one folder to another.
• Do not move files from one cabinet to another.
• Do not change the order of files in a cabinet.
• Do not change the sequence number of existing files. The sequence number is the value specified in the Sequence column of the File Table.
• Any new files that are added by the patch must be placed at the end of the existing file sequence. The sequence number of any new file in the upgraded image must be greater than the largest sequence number of existing files in the target image.
• Do not add new files to the end of an existing cabinet file. All new files must be added after the last cabinet file in the sequence.
• Do not change the primary keys in the File Table between the original and new .msi file versions.

Note: The file must have the same key in the File Table of both the target image and the updated image. The string values in the File column of both tables must be identical, including the case.

• Do not author a package with File Table keys that differ only in case, for example, avoid the following table example.

File	Component_	FileName
readme.txt	Comp1	readme.txt
ReadMe.txt	Comp2	readme.txt

• The Windows Installer can allow the previous table example when Comp1 and Comp2 are installed on different directories, but then one cannot use Msimsp.exe or Patchwiz.dll to generate a patch for the package. Msimsp.exe and Patchwiz.dll call Makecab.exe, which is case-insensitive and fails.
• When using merge modules in the setup, ensure that file sequence numbers and layout adhere to the above guidelines.

---

Installing Multiple Patches

Multiple patches can be applied to a product in a constant order, regardless of the order that the patches are provided to the system, by authoring patch sequencing information into the MsiPatchSequence table of the patch package. The patches must be installed using Windows® Installer version 3.0 to use this information. Windows Installer versions previous to version 3.0 always install patches in the order that they are provided to the system.

Beginning with Windows Installer version 3.0, the installer can use the information provided in the MsiPatchSequence table to determine which patches are applicable to the Windows Installer package and in which order the patches should be applied.

When the patch package contains a mixture of patches with sequence information in the MsiPatchSequence table and some patches without this information, Windows installer version 3.0 sequences the patches in the order described in the following section: Sequencing Patches. A patch that should not be used can be eliminated from the patching sequence. This prevents the patch from being applied when the target application is patched. This is different than removing a patch that has already been applied to an application.