How To Implement Updates Using WiX Toolset Installer

Written by Radu Popescu · June 7th, 2021

In this post, we will address installer updates with a focus on the most common scenarios you may encounter when performing a small, minor, or major upgrade.

First, we will see what is inside your WiX Toolset base application and move on to the different types of updates that you can execute for your WiX installers.

What Is Inside Your WiX Toolset Base Application?

To better understand how an application upgrade works, we should first know what its components are and how they interact with each other.

For the scenarios presented in this article, we are using WiX Toolset version 3.11.2. Our base sample application contains an executable file “CMtrace.exe” and a text file“guide.txt” which has the information shown below.

Take note of the ProductID, UpgradeCode, and PackageID in the code below. It will be helpful for future references since they are the ones that are modified through the upgrading process.

Our base application has the following code inside the WiX installer project.

<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
<Product Id="A0174BDA-E73A-4238-802E-6C8D5E427668" UpgradeCode="8127636F-6291-4D43-8CC9-AB702A631C3B" 
Name="SampleApp" Version="1.0.0.0" Manufacturer="Caphyon" Language="1033">
<PackageId="075454EB-3FD5-4FA9-9701-1AA510A1D56F" InstallerVersion="200" Compressed="yes" Comments="Test sample app installer"/>
<MediaTemplate />
<Directory Id="TARGETDIR" Name="SourceDir">
<Directory Id="ProgramFilesFolder">
<Directory Id="INSTALLDIR" Name="SampleApp">
<Component Id="Files" Guid="11111111-2222-3333-4444-555555555555">
<File Id="File1" Source="CMTrace.exe"/>
<File Id="File2" Source="guide.txt"/>
</Component>
</Directory>
</Directory>
</Directory>
 
<Feature Id="Feature1" Level="1" Title="First feature" Description="This is the one and only feature in this installation">
<ComponentRef Id="Files"/>
</Feature>
</Product>
</Wix>

What Are The Main Types of WiX Update Installers?

Small Updates

Small Updates are used to perform small alterations to one or a few files without changing the product version (major.minor.build) or Product ID GUID.

If you look at our example below, you can observe that the only modification to the package is the text inside the guide.txt file. Since this is a quick fix, you can consider Small Update as a hotfix.

In this case, the element changed in the code is: Package GUID

<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
<Product Id="A0174BDA-E73A-4238-802E-6C8D5E427668" UpgradeCode="8127636F-6291-4D43-8CC9-AB702A631C3B" 
Name="SampleApp" Version="1.0.0.0" Manufacturer="Caphyon" Language="1033">
<PackageId="487E2D11-D57C-4365-85EF-4DB9330DD3AA" InstallerVersion="200" Compressed="yes" Comments="Test sample app installer"
<MediaTemplate />
<Directory Id="TARGETDIR" Name="SourceDir">
<Directory Id="ProgramFilesFolder">
<Directory Id="INSTALLDIR" Name="SampleApp">
<Component Id="Files" Guid="11111111-2222-3333-4444-555555555555">
<File Id="File1" Source="CMTrace.exe"/>
<File Id="File2" Source="guide.txt"/>
</Component>
</Directory>
</Directory>
</Directory>
 
<Feature Id="Feature1" Level="1" Title="First feature" Description="This is the one and only feature in this installation">
<ComponentRef Id="Files"/>
</Feature>
</Product>
</Wix>

Minor Updates

Minor Updates are used to perform minor changes to a package increasing its version.

Since the product remains the same, you don't need to change the Product GUID.

The only elements changed in the code are the Version attribute and Package GUID.

<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
<Product Id="A0174BDA-E73A-4238-802E-6C8D5E427668" UpgradeCode="8127636F-6291-4D43-8CC9-AB702A631C3B" 
Name="SampleApp" Version="1.1.0.0" Manufacturer="Caphyon" Language="1033">
<PackageId="487E2D11-D57C-4365-85EF-4DB9330DD3AA" InstallerVersion="200" Compressed="yes" Comments="Test sample app installer"/>
<MediaTemplate />
<Directory Id="TARGETDIR" Name="SourceDir">
<Directory Id="ProgramFilesFolder">
<Directory Id="INSTALLDIR" Name="SampleApp">
<Component Id="Files" Guid="11111111-2222-3333-4444-555555555555">
<File Id="File1" Source="CMTrace.exe"/>
<File Id="File2" Source="guide.txt"/>
</Component>
</Directory>
</Directory>
</Directory>
 
<Feature Id="Feature1" Level="1" Title="First feature" Description="This is the one and only feature in this installation">
<ComponentRef Id="Files"/>
</Feature>
</Product>
</Wix>

Major Updates

Major Updates are used to perform crucial changes to a package, upgrading them from the full version to another.

Let’s assume we perform a Major Upgrade to our application which has the main executable CmTrace2.exe and the 1.0.0 version. Once the upgrade is done, and the functionality is added, the application version will also change to 2.0.0.

The elements changed in the code compared to our base application are Version attribute, Product, and Package GUID.

As a best practice, the UpgradeCode should also be changed every time you make a Major upgrade to your package.

<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
<Product Id="95EF64F6-3CF6-4F3A-9854-CBBE0A7338F5" UpgradeCode="7806A6DF-7FEF-4788-B871-261903DE0381" 
Name="SampleApp" Version="2.0.0.0" Manufacturer="Caphyon" Language="1033">
<PackageId="487E2D11-D57C-4365-85EF-4DB9330DD3AA" InstallerVersion="200" Compressed="yes" Comments="Test sample app installer"/>
<MediaTemplate />
<Directory Id="TARGETDIR" Name="SourceDir">
<Directory Id="ProgramFilesFolder">
<Directory Id="INSTALLDIR" Name="SampleApp">
<Component Id="Files" Guid="11111111-2222-3333-4444-555555555555">
<File Id="File1" Source="CMTrace2.exe"/>
<File Id="File2" Source="guide.txt"/>
</Component>
</Directory>
</Directory>
</Directory>
 
<Feature Id="Feature1" Level="1" Title="First feature" Description="This is the one and only feature in this installation">
<ComponentRef Id="Files"/>
</Feature>
</Product>
</Wix>

You can check the types of upgrades and the differences between them in our article on Updates Deployment.

How to Implement WiX Installer Upgrades - Common Scenarios

Updates are meant to keep track of changes performed to previous versions. No matter what scenario you follow, you should always have the UpgradeCode from the previous version in hand.

Here are some of the common scenarios we will encounter when implementing WiX installer updates.

Detecting and Replacing Files and Versions

In this scenario, we want our new package to detect the previous version and include the additional files that we added to our new package.

To do this, we need to add the section below to the code:

<Upgrade Id='8127636F-6291-4D43-8CC9-AB702A631C3B'>
    <UpgradeVersion OnlyDetect='yes'
        Minimum='1.0.0' IncludeMinimum='yes'
        Maximum='1.0.1' IncludeMaximum='yes' />
</Upgrade>

Upgrade Id should have the value of UpgradeCode from our base application (the one mentioned at the beginning of this article).

OnlyDetect must be set to yes. If set to no, it will remove the previous version.

Minimum and maximum attributes define the version range in which the update will be applied (if found).

Detecting and Replacing the Previous Version Completely

Here, we want our package to remove the previous version. Also, the package can be installed as a standalone. This is mostly used for Major Upgrades.

The only change here is the OnlyDetect value and the maximum value, since now our version range is different (our new application is now version 2.0).

The code should now look like this:

<Upgrade Id='8127636F-6291-4D43-8CC9-AB702A631C3B'>
    <UpgradeVersion OnlyDetect='no'
        Minimum='1.0.0' IncludeMinimum='yes'
        Maximum='2.0.0' IncludeMaximum='yes' /> 
</Upgrade>

More about WiX Toolset: We have a dedicated resource page about the WiX Toolset, which includes various topics related to your installer, using custom actions in WiX, and setting a WiX installer build to the current version.