wixwindows-installermajor-upgrade

Adding entries to MSI UpgradeTable to remove related products

A WiX installer product node has an attribute UpgradeCode. It is used to refer to previous versions of the same product. The value is stored in the UpgradeTable. The UpgradeTable is parsed by the FindRelatedProducts action.

The UpgradeCode allows to remove previous products with the same UpgradeCode. But the plan is to integrate several outdated legacy products to a combined single product. The UpgradeCode of this legacy product is known. I hope adding this code to the UpgardeTable will remove this legacy product too. This can be done by filling the UpgradeTable.

How can I add more entries in the UpgradeTable in a WiX setup?

Edit: What Syntax is required?

Is there a better way to remove products that are absolete after an upgrade?

Solution

  • Short Answer: You add several Upgrade Element entries in your WiX source which will create several rows in the compiled MSI's Upgrade Table which then list products that are to be uninstalled during installation (or that can abort your installation). You must be very careful about the options you specify for each product family to uninstall.

    Major Upgrade Failure: Here is a list to help debug failing major upgrades by identifying the most common problems: Common causes of failed major upgrades.

    Side-By-Side Installations: Be aware that an alternative to uninstalling older versions during a major upgrade, is to make your new version isolated enough to be able to co-exist with existing installations. Such isolation can be challenging, and is a whole other ballgame (prevent: fighting over file associations, incompatible COM server installations, incompatible runtimes, conflicting services, unexpected locks of configuration files and registry keys, etc...).

    MajorUpgrade Element: Newer versions of WiX feature a "convenience feature" for major upgrade implementation in the form of the MajorUpgrade element. This elements simplifies the implementation of normal major upgrades.

    Upgrade Element: In earlier versions of WiX more basic elements had to be used to implement major upgrades. This element is still available, and it is what you need to do more elaborate and fine-grained UpgradeTable configuration.

    The differences between using these methods are very nicely illustrated by Wim Coenen here: Majorupgrade or Upgrade ID which is preferred for Major upgrade? I think that explanation is so good that I refuse to repeat it too much here :-). Give it a quick read please.

    Major Upgrade Configuration Choices: The below is just a sample. The actual configuration of a major upgrade has to be carefully reasoned in each case:

    You obviously have to plan for this and test in detail. Below is a mock-up. This combines the use of the MajorUpgrade Element and Upgrade elements. You can also rely solely on Upgrade elements to do things "manually" with more fine grained control:

    <!-- Major upgrade - Your New Product Line, using the MajorUpgrade convenience element -->
<MajorUpgrade DowngradeErrorMessage="A later version of [ProductName] is already installed" />

<!-- Older Product Line 1: Upgrade Code -->
<Upgrade Id="{11111111-1111-1111-1111-000000000000}">
   <UpgradeVersion Property="PRODUCTLINE1" IncludeMinimum="yes" Minimum="0.0.0" />
</Upgrade>

<!-- Older Product Line 2: Upgrade Code -->
<Upgrade Id="{22222222-2222-2222-2222-000000000000}">
   <UpgradeVersion Property="PRODUCTLINE2"  IncludeMinimum="yes" Minimum="0.0.0" />
</Upgrade>

<!-- Older Product Line 3: Upgrade Code -->
<Upgrade Id="{33333333-3333-3333-3333-000000000000}">
   <UpgradeVersion Property="PRODUCTLINE3"  IncludeMinimum="yes" Minimum="0.0.0" />
</Upgrade>

    I would suggest you change the name of these PRODUCTLINE properties that is inherently understandable as a specific product line. In other words if you uninstall WiX3 you call it WIX3PRODUCTLINE etc... This is so the resulting log file is easier to comprehend.

    Sample Upgrade Table:

    Upgrade Table

    The Attributes column of the Upgrade Table is important to control the behavior of the major upgrade. Continue on uninstall failure, etc...

    And a list of free tools you can use to view a compiled MSI files (for whoever might find this answer): How can I compare the content of two (or more) MSI files?

    UPDATE:

    Older Entries:

    Also want to send you to WiX expert Neil Sleightholm's site for some dated, but still good real-world samples: