A major upgrade occurs when an old MSI package is removed during the install of a new MSI package. Major upgrades are a popular way to upgrade because they are easy to implement and easy to deploy.
To implement a major upgrade, you provide three things:
- Identify the packages to participate in the upgrade.
- Define a versioning scheme.
- Indicate how to execute the upgrade.
Before a major upgrade can take place we must identify the old and the new MSI packages.
Product/@UpgradeCodeattribute must be specified in the old MSI package.
UpgradeCodeis used to locate the package to be upgraded and thus it must be present in the old MSI package. Since the
UpgradeCodeis important to enable future major upgrades the WiX toolset warns if it is not specified.
It is common for the
UpgradeCodeto be set once and never change for the lifetime of the product.
Change the GUID in the
The Windows Installer only allows an MSI package to install if it has a unique
Product/@Id. Since a major upgrade requires the new MSI package to install to remove the old MSI package, the new MSI package must have a different
You may use
Product/@Idto generate a new GUID with every build. That can be a convenient way to enable major upgrades.
Define a versioning scheme
With the ability to find an older version of the MSI package and install a newer version of the MSI package, it is time to define a versioning scheme using the
An MSI package may use the standard four fields in a
ProductVersion (major.minor.build.revision). However, the Windows Installer only evaluates the first three fields (major.minor.build) when considering a major upgrade. For example, the Windows Installer considers
22.214.171.124 equivalent to
126.96.36.199. This behavior can surprise many developers new to the Windows Installer.
Therefore, it is recommended to use a versioning scheme where daily builds update one of the first three fields of the
Execute the upgrade.
MajorUpgrade element makes it easy to define the upgrade. For example,
<Wix> <Product ...> <Package .../> <MajorUpgrade DowngradeErrorMessage='A newer version of [ProductName] is already installed.' />