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:

1. Identify the packages to participate in the upgrade.
2. Define a versioning scheme.
3. Indicate how to execute the upgrade.

Identify packages

Before a major upgrade can take place we must identify the old and the new MSI packages.

1. A Product/@UpgradeCode attribute must be specified in the old MSI package.

   The UpgradeCode is used to locate the package to be upgraded and thus it must be present in the old MSI package. Since the UpgradeCode is important to enable future major upgrades the WiX toolset warns if it is not specified.

   It is common for the UpgradeCode to be set once and never change for the lifetime of the product.

2. Change the GUID in the Product/@Id attribute.

   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 Product/@Id.

   You may use * for the Product/@Id to 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 Product/@Version attribute.

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 1.0.0.0 equivalent to 1.0.0.1. 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 Product/@Version.

Execute the upgrade.

Finally, the MajorUpgrade element makes it easy to define the upgrade. For example,

<Wix>
  <Product ...>
    <Package .../>

    <MajorUpgrade DowngradeErrorMessage='A newer version of [ProductName] is already installed.' />