A question was asked in Aaron Stebner’s blog about major upgrades via MSP patch files with sequencing information. I would like to take this opportunity — at Aaron’s request — to explain a few guidelines regarding major upgrades in Windows Installer.

Basically, a major upgrade is an update to a product that changes all of the ProductCode, ProductVersion, and package code (the latter should always change for any update). A major upgrade — unlike small or minor updates — can be installed either by patching the product or installing a new product MSI. In order to remove the product or certain features of the existing product, you add entries to the Upgrade table with the Remove column empty or set to ALL to remove all features, or a comma-delimited list of feature names to remove only certain features. For the Visual Studio Windows Installer projects when “RemovePreviousVersions” is set to “True”.

Starting with Windows Installer 3.0, however, things have changed a little. You can now use the more robust supersedence feature instead of obsolescence which requires that a patch has information during compile time about all patches that it obsoletes (removes from the patched view of the product). This new feature also allows for proper sequencing and supersedence of patches when installing multiple patches in a single installer transaction. Major upgrade patches, however, are eliminated from the list of patches. Major upgrade patches are also not uninstallable, while a major upgrade product is. From the Windows Installer SDK:

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.

This is due in part to the new product baseline cache feature introduced in Windows Installer 3.0. Files are cached for the RTM and any minor upgrades for a product if all small updates include the MsiPatchSequence table or at least one minor update includes the MsiPatchSequence table. Small updates can then ship a delta patch that contains the binary differences between the new file and the target baseline to reduce patch size. Because a baseline is cached for a product identified by its ProductCode and a major upgrade changes the ProductCode, the baseline would be invalidated for any patches targeting the major upgrade. To ensure that the old baseline is removed with the upgraded product and a new baseline is created for the new product, ship major upgrades as product MSIs. This also means you can ship a new product that’s both a standalone installer as well as an upgrade to any existing products.

So, because MSI 3.0-style patches are identified as having an MsiPatchSequence table that cannot be empty and because sequenced major upgrades cannot be installed, patch authoring tools like PatchWiz.dll will not allow creation of sequenced major upgrade patches. Instead, PatchWiz.dll will return via tools like msimsp.exe the error code ERROR_PCW_CANT_GENERATE_SEQUENCEINFO_MAJORUPGD (defined as 0xC00E5182 in PatchWiz.h).