How to implement a WiX installer upgrade

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.

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”

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.

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 http://wixtoolset.org/ in order to download and install it.

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 (*) :

<ProductId="*"

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.

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.

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’.

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:

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:

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:

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.:

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:

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.

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?

This technology is now available for our custom development services only. Based on the Add-in Express for Office core, it is designed for building custom-tailored Office add-ins with far less coding than you usually have to do. Plus, it includes all Add-in Express features such as True RAD, visual designers, Outlook view and form regions, etc.

Get the best platform for building version-neutral, fast and easy deployable plug-ins by using Add-in Express projects templates, visual designers, components and wizards in combination with a perfect Delphi compiler.

This is an extension for Visual Studio that allows developers to quickly create WiX-based setup projects in a familiar Visual Studio way.

The Designer for WiX Toolset lets you forget the plain Windows Installer XML and concentrate on your deployment logic. It integrates several editors with the Visual Studio IDE and provides a set of vdproj designers to configure the file system, registry, user interface, custom actions, launch conditions and more for your setup projects.

The innovative technology for customizing Outlook views and forms. It is included in all Add-in Express for Office products and can be used to extend Outlook views, e-mail, task and appointment windows, To-Do bar, Reading and Navigation panes with your own custom sub-panes.

Microsoft and the Office logo are trademarks or registered trademarks of Microsoft Corporation in
the United States and/or other countries. All other trademarks are property of their respective owners.