How to implement a WiX installer upgrade

Posted on Thursday, January 23rd, 2014 at 10:05 am by Pieter van der Westhuizen.

So by now, I hope we all know and have come to accept the fact that Visual Studio setup projects are a thing of the past and that we’ve all become comfortable with using the WiX toolset to build our Windows Installers.

Building the application
Building the WiX setup project
Creating a WiX upgrade

But, building a WiX setup project is one thing, upgrading it is another. I’m sure many of you have encountered this dreaded message before:

“Another version of this product is already installed. Installation of this version cannot continue. To configure or remove the existing version of this product, use Add/Remove Programs on the Control Panel”

Error message: Another version of this product is already installed.

With the latest version of the WiX toolset, the default Product.wxs template helps you to avoid the above mentioned error, but for the sake of clarity we’ll illustrate why this error happens before we get into how to avoid it.

Building the application
Building the WiX setup project
Creating a WiX upgrade

Building the application

The sample application, which we need to deploy to the end-user, will be a very simple Windows form application that displays a Calendar control and a button. When the user clicks the button a message will display the selected date. The link label at the bottom of the form, will display help information contained in a ReadMe.txt file.

A simple Windows form application that displays a Calendar control and a button.

Building the WiX setup project

Start by creating a new Windows Installer XML Setup Project in Visual Studio. If you do not see the project templates, you probably do not have the WiX toolset installed. Head over to https://wixtoolset.org/ in order to download and install it.

Building the WiX setup project

The project template will create a boilerplate WiX setup file (Product.wxs) for you. The first thing you need to notice is that the Id attribute’s value is set to an asterisk (*) :

<Product Id="*"

It is important to keep this value an asterisk, if you set it to a GUID, you will run into problems when trying to upgrade your WiX setup project. The error message, mentioned above, will be one of them.

Add the following to the Product element:

<Media Id="1" Cabinet="WinApp.cab" EmbedCab="yes" />
 
<Feature Id="Executable" Level="1">
  <ComponentRef Id="Executable" />
  <ComponentRef Id="Documentation" />
  <ComponentGroupRef Id="RegistryGroup" />
</Feature>
 
<Property Id="WIXUI_INSTALLDIR" Value="INSTALLDIR" />
<UIRef Id="WixUI_InstallDir" />

The full XML for the Product element should look as follows:

<Product Id="*" Name="Win App" Language="1033" Version="1.0.0.0" 
           Manufacturer="WinApp Software Inc." 
           UpgradeCode="a9b1d837-9b09-491b-bd81-b794560745a4">
    <Package InstallerVersion="200" Compressed="yes" InstallScope="perMachine" />
 
    <MajorUpgrade DowngradeErrorMessage="A newer version of [ProductName] is already installed." />
 
    <Media Id="1" Cabinet="WinApp.cab" EmbedCab="yes" />
 
    <Feature Id="Executable" Level="1">
      <ComponentRef Id="Executable" />
      <ComponentRef Id="Documentation" />
      <ComponentGroupRef Id="RegistryGroup" />
    </Feature>
 
    <Property Id="WIXUI_INSTALLDIR" Value="INSTALLDIR" />
    <UIRef Id="WixUI_InstallDir" />
 
  </Product>

In the XML above we’ve added three features: (a) to install the applications’ executable; (b) to install the applications’ help file; and (c) to create an entry in the Windows registry.

The most important element for this article is <MajorUpgrade>. This element is used to upgrade all older versions of your WiX setup. You’ll notice that it contains a DowngradeErrorMessage attribute, which is added by default and is shown when a user tries to install an older version of the .msi when an already newer version exists on the target computer. This behavior is enabled by default in order to prevent out-of-order installations.

Next, add the following below the <Product> element:

<Fragment>
    <Directory Id="TARGETDIR" Name="SourceDir">
      <Directory Id="ProgramFilesFolder">
        <Directory Id="INSTALLDIR" Name="Win App">
          <Component Id="Executable" Guid="7B289C8E-6F5B-4A7B-A9A1-E78A89239714">
            <File Id="WinAppExe" Name="WinApp.exe" Source="..\WinApp\bin\Debug\Winapp.exe" Vital="yes" />
            <RemoveFolder Id="INSTALLDIR" On="uninstall" />
          </Component>
          <Component Id="Documentation" Guid="E4AA4677-6DDA-4746-A956-0A636DBB2995">
            <File Id="ReadMeTxt" Name="ReadMe.txt" Source="..\WinApp\bin\Debug\ReadMe.txt" Vital="yes" />
          </Component>
        </Directory>
      </Directory>
    </Directory>
 
    <ComponentGroup Id="RegistryGroup">
      <Component Id="_69CB4E7B_273F_4510_B885_4633736280D0" Guid="2EC2BF60-997B-44BB-BA82-C5760FB48A19" Transitive="no" Directory="TARGETDIR">
        <RegistryKey Root="HKLM" Key="Software" ForceCreateOnInstall="no" ForceDeleteOnUninstall="no" />
      </Component>
      <Component Id="_A159385C_39DE_404D_833B_6F83828512C0" Guid="1D85B1A4-ABDD-4EB5-8E70-82C609462AEB" Transitive="no" Directory="TARGETDIR">
        <RegistryKey Root="HKLM" Key="Software\WinApp Software" ForceCreateOnInstall="no" ForceDeleteOnUninstall="no" />
      </Component>
      <Component Id="_AAF14A16_5774_4861_AD86_C21F01857F59" Guid="E5F8A3A2-209A-4297-8B01-F7BB4FC6603B" Transitive="no" Directory="TARGETDIR">
        <RegistryValue Root="HKLM" Key="Software\WinApp Software" Type="string" Name="License" Value="Free" />
      </Component>
    </ComponentGroup>
 
  </Fragment>

This XML is used to copy the WinApp.exe and ReadMe.txt files to the target installation folder and it will create a Windows registry entry under HKEY_LOCAL_MACHINE\Software\WinApp Software, called License, whose value will be set to 'Free’.

The full XML for the Product.wxs file follows below:

<?xml version="1.0" encoding="UTF-8"?>
<Wix xmlns="https://schemas.microsoft.com/wix/2006/wi">
  <Product Id="*" Name="Win App" Language="1033" Version="1.0.0.0" Manufacturer="WinApp Software Inc." UpgradeCode="a9b1d837-9b09-491b-bd81-b794560745a4">
    <Package InstallerVersion="200" Compressed="yes" InstallScope="perMachine" />
 
    <MajorUpgrade DowngradeErrorMessage="A newer version of [ProductName] is already installed."
                  MigrateFeatures="yes" />
 
    <Media Id="1" Cabinet="WinApp.cab" EmbedCab="yes" />
 
    <Feature Id="Executable" Level="1">
      <ComponentRef Id="Executable" />
      <ComponentRef Id="Documentation" />
      <ComponentGroupRef Id="RegistryGroup" />
    </Feature>
 
    <Property Id="WIXUI_INSTALLDIR" Value="INSTALLDIR" />
    <UIRef Id="WixUI_InstallDir" />
 
  </Product>
 
  <Fragment>
    <Directory Id="TARGETDIR" Name="SourceDir">
      <Directory Id="ProgramFilesFolder">
        <Directory Id="INSTALLDIR" Name="Win App">
          <Component Id="Executable" Guid="7B289C8E-6F5B-4A7B-A9A1-E78A89239714">
            <File Id="WinAppExe" Name="WinApp.exe" Source="..\WinApp\bin\Debug\Winapp.exe" Vital="yes" />
            <RemoveFolder Id="INSTALLDIR" On="uninstall" />
          </Component>
          <Component Id="Documentation" Guid="E4AA4677-6DDA-4746-A956-0A636DBB2995">
            <File Id="ReadMeTxt" Name="ReadMe.txt" Source="..\WinApp\bin\Debug\ReadMe.txt" Vital="yes" />
          </Component>
        </Directory>
      </Directory>
    </Directory>
 
    <ComponentGroup Id="RegistryGroup">
      <Component Id="_69CB4E7B_273F_4510_B885_4633736280D0" Guid="2EC2BF60-997B-44BB-BA82-C5760FB48A19" Transitive="no" Directory="TARGETDIR">
        <RegistryKey Root="HKLM" Key="Software" ForceCreateOnInstall="no" ForceDeleteOnUninstall="no" />
      </Component>
      <Component Id="_A159385C_39DE_404D_833B_6F83828512C0" Guid="1D85B1A4-ABDD-4EB5-8E70-82C609462AEB" Transitive="no" Directory="TARGETDIR">
        <RegistryKey Root="HKLM" Key="Software\WinApp Software" ForceCreateOnInstall="no" ForceDeleteOnUninstall="no" />
      </Component>
      <Component Id="_AAF14A16_5774_4861_AD86_C21F01857F59" Guid="E5F8A3A2-209A-4297-8B01-F7BB4FC6603B" Transitive="no" Directory="TARGETDIR">
        <RegistryValue Root="HKLM" Key="Software\WinApp Software" Type="string" Name="License" Value="Free" />
      </Component>
    </ComponentGroup>
 
  </Fragment>
 
</Wix>

When we build our WiX setup project, it will generate an .msi file. Run this installer and you’ll notice that the following files are deployed to C:\Program Files (x86)\Win App\:

ReadMe.txt; and
Winapp.exe.

The path might differ if you’ve selected another location during setup. If you look in the Windows Programs and Features list, you’ll also see the Win App application was listed with a version number of 1.0.0.0 and a publisher name of WinApp Software:

Version 1 of the Win App is installed

Creating a WiX upgrade

In order to create an upgrade for our WiX installer, we first need to increase the assembly version for the windows application we’ve created earlier. To do this, right-click on the project in the Visual Studio Solution Explorer window and select properties. In the properties window, on the Application tab, click on the Assembly Information button and change the version number on the Assembly Information dialog:

Changing the version number in the Assembly Information dialog

We’ll also change the next version to use a Rich Text document for the help file instead of a plain text file. So add a new file to the project called Help.rtf.

Next, open the Product.wxs file and set the Version attribute value to 2.0.0.0:

<Product Id="*" Name="Win App" Language="1033" Version="2.0.0.0" Manufacturer="WinApp Software Inc." UpgradeCode="a9b1d837-9b09-491b-bd81-b794560745a4">

Because, we’re using a new help file, we’ll want to remove the old ReadMe.txt. To do this, we’ll first remove the old Component element that adds the ReadMe.txt file and add a new Documentation component and a <RemoveFile> element to the Documentation Component e.g.:

<Component Id="Documentation" Guid="E4AA4677-6DDA-4746-A956-0A636DBB2995">
  <File Id="HelpRtf" Name="Help.rtf" Source="..\WinApp\bin\Debug\Help.rtf" Vital="yes" />
  <RemoveFile Id="RemoveReadMe" Name="ReadMe.txt" On="both"/>
</Component>

The XML above will add the new Help.rtf file and remove the old ReadMe.txt file from the target installation folder. When you build your project and run the installer, you should no longer see the ReadMe.txt file in the target installation folder and the version number of the application in Windows Programs and Features list, should have been increased:

The version number of the application is increased.

Thank you for reading. Until next time, keep coding!

Available downloads:

Sample project

You may also be interested in:

Deployment, WiX
Filed under VDProj to WiX Converter and WiX Designer

13 Comments

Ian Crane says:

September 25, 2014 at 12:19 pm

What if you only update the contents of readme.txt? Will it just overwrite it or do you have to remove and add it?
Pieter van der Westhuizen says:

September 26, 2014 at 12:18 am

Hi Ian,

You would still need to update the version number of the application in order for the installer to upgrade the old version.
Thomas Freudenberg says:

March 6, 2015 at 10:55 am

This works great, however, the setup still asks me for the target directory. How would you skip InstallDirDlg during a major update? I tried different customizations of WixUI_InstallDir, but I’m not experienced enough to get it right. Even https://windows-installer-xml-wix-toolset.687559.n2.nabble.com/Hide-InstallDirDlg-during-upgrade-td5014310.html did not help me.
Pieter van der Westhuizen says:

March 9, 2015 at 11:35 pm

Hi Thomas,

Thanks for reading! Have you tried setting the UIRef element to WixUI_Minimal? For example:
<UIRef Id="WixUI_Minimal" />

It is one of the built-in Wix dialogs.

Hope this help! :)
Thomas Freudenberg says:

March 10, 2015 at 3:18 am

I tried to customize the UI sequence already. However, I never managed to get the conditions right, when to switch to what dialog.
Pieter van der Westhuizen says:

March 10, 2015 at 6:19 am

Hi Thomas,

I had a quick read of the link you posted.
Now, I have not tested this myself yet, but it looks like you can set conditions on when to hide/show dialogs.

Maybe try something like the following:
<UIRef Id=”WixUI_Minimal” />

<Publish Dialog=”WixUI_InstallDir” Control=”Back” Event=”NewDialog” Value=”WixUI_InstallDir”
Order=”4″>NOT Installed</Publish>

Far as I understand this will only show the InstallDir dialog if the product is not installed.
As I’ve said I’ve not tested this myself, but it wont hurt to give it a shot :)
Germán Hayles says:

July 8, 2015 at 6:35 am

I noticed that in the ‘Assembly Information’ dialog in this example there was a GUID value.

When I bring mine up, no GUID value is present. Is this why I’m getting the “Newer Version Already Installed” message?

Steps I take to create an installer.
1) Make the usual code updates to my Add-In
2) Update the version number (e.g. 1.0.10016 to 1.0.10017)
3) I leave the “*” alone. I do not create a GUID
4) I compile the Setup project then try running it on my test machine that has the previous version of the Add-In installed.
Pieter van der Westhuizen says:

July 13, 2015 at 7:52 am

Hi Germán,

Make sure you also incrementthe version number in the .wxs file:
<Product Id="*" Name="Win App" Language="1033" Version="2.0.0.0"

I've followed your steps and also incremented the version number in the .wxs file and it installed without a problem.

Hope this helps!
Lipo says:

July 6, 2016 at 9:31 am

I’ve made an installer using the WIX toolset (3.10). I’d like to enable upgrades but I can’t make it work. Every time I run the msi it installs another version. I can’t figure out what’s wrong. Whats am I missing?

product.wxs file:
Andrei Smolin (Add-in Express Team) says:

July 7, 2016 at 3:56 am

Hello Lipo,

Installing a new version is the goal of upgrading.
Rob says:

November 16, 2017 at 10:56 pm

Hello Lipo

A little late probably to help you :)

I hope that Andrei Smolin was joking. Having App 1.0.0 and App 1.0.1 BOTH installed is NOT the goal of upgrading!

We do not use the MajorUpgrade option so this may be incompatible with MajorUpgrade.

Add an Upgrade option to make it work properly:
roopa says:

July 10, 2020 at 5:28 am

hi,
i have a product installed using VdProj.
How to use WIX for upgrading this project?
Andrei Smolin (Add-in Express Team) says:

July 10, 2020 at 8:50 am

Hello roopa,

I’ve added a file called OneMoreDialog.wxs to the project via the Add New Item dialog. In ProgressDialog.wxs, I’ve added and modified by adding this tag: . As to OneMoreDialog, you can show anything you like here; I’ve used a version of UserRegDialog. For me, this doesn’t show ProgressDialog; I believe the dialog is shown too quickly for me to notice it. I think this is because you are expected to control it via events it produces and I didn’t do that. See also https://stackoverflow.com/questions/47988864/wix-progress-bar-in-ui-sequence.