Page 1 of 1

Windows Installer XML - Upgrades

#1 Adkins  Icon User is offline

  • D.I.C Addict
  • member icon

Reputation: 66
  • View blog
  • Posts: 560
  • Joined: 27-October 09

Posted 24 May 2011 - 07:45 AM

In this tutorial I am going to go over how to add the functionality to perform an upgrade to your msi. This is a continuation of the Windows Installer XML Intro tutorial that I wrote a while back.

With the release of WiX 3.5 in stable condition it changed the ways of doing an upgrade quite drastically. I will go over both options in case anyone is curious about the old and the new of it. I will however mention that the new is much cleaner to read, easier to implement, and simplified with the hope of cutting back on forgotten elements. Plus it is released and not just release candidate or beta, so it is stable enough for everyday use.

WiX 3.0 and before:
<Property Id="UPGRADE_1" Secure="yes" />

<Upgrade Id="{B46E978F-YOUR-GUID-HERE-61329817CE18}">
    <UpgradeVersion Minimum="1.1.0" Maximum="1.9.0" Property="UPGRADE_1" MigrateFeatures="yes" OnlyDetect="no" IncludeMinimum="yes" IncludeMaximum="yes" />
</Upgrade>

<InstallExecuteSequence>
    <RemoveExistingProducts After="CostFinalize" />
</InstallExecuteSequence>



First off is the obvious. This is not all that is available to do an upgrade. It is actually a little more than the minimum, but that is only because it will give us enough to talk about so you can decide what you want to use personally.

It all starts off with just an Upgrade element. The Id for this element is very important. It has to be the same as the Upgrade Code for the product that you are hoping to upgrade. A copy and paste is the best bet for this one, just to be on the safe side. I mixed this up one time and ended up upgrading one product with another. Not a very helpful feature...

Under that comes the UpgradeVersion elements. There can be more than one of these if you need to know which Version you are coming from. More on that option in a second though. First we have to dive through one example before we start talking about multiple instances. In the list below I have included all the attributes that can be used even if they are not listed in the example. The order of the attributes doesn't matter so if you want to include on the ones below in the example above, by all means go right ahead.
  • Minimum - The minimum version number that this upgrade will effect.
  • Maximum - The maximum version number that this upgrade will effect. This can either be the version of the current product or an earlier version.
  • Property - The upgrade will set a property to the upgrade code when it happens. This is the property that will be used.
  • MigrateFeatures - Upgrade the feature list using the original installation if set to 'yes'.
  • OnlyDetect - Only detects if an update is needed without actually performing it. This can be used if you have an external program that handles upgrades.
  • IncludeMinimum - Determines whether to include the given minimum version number in the list of version numbers that are being searched or not.
  • IncludeMaximum - Determines whether to include the given maximum version number in the list of version numbers that are being searched or not. For simplicity you could make the maximum version number the same as the actual version number and then leave this attribute out.
  • ExcludeLanguages - This will tell the MSI to ignore the language tag that is set for this particular project and upgrade all language version of this product when found. Careful with this, because it runs the risk of replacing language specific files with their neutral counterpart.
  • IgnoreRemoveFailure - This tells Windows Installer that it is no big deal if there is an issue by the removal of the old product.


Lets say that you have a program that runs from within your MSI during an upgrade and that program needs to know what version you are upgrading from. I know we haven't covered anything close to that yet, but it is coming in a later tutorial. If you make multiple UpgradeVersion elements, each with it's own property, then you could use that property to tell your custom action (the program) if you are upgrading from version 1.0 or from version 12.5. More on that once I get to the Tutorial on Custom Actions though.

In addition to the Upgrade element you also need two other things. The property element that will declare the property that you are using in your UpgradeElement (one property element for each property of course), and a RemoveExisitingProducts element. The property element is extremely easy.
  • Id - The name of the property.
  • Value - The default value of the property. If your property won't have a default value (like in our case) then simply don't provide this attribute.
  • Secure - Tells Windows Installer that it is ok to pass this property back and forth between the Windows Installer server and client. This is very important for our use case here.
  • Hidden - The value that is in this property will not show up in logs. This is useful if you are going to be using it for passwords.


RemoveExistingProducts is nothing more than the attribute Before or After (exclusive) and the part of the installation that you want it to come before or after. I would recommend defaulting to After="CostFinalize" because that is the current Best Practice that I have found during my WiX/Windows Installer travels.

WiX 3.5:
<MajorUpgrade DowngradeErrorMessage="An newer version of this product is already installed."/>



This version only has on element. Thats it. It's attributes are as follows:
  • AllowDowngrades - A yes or no letting Windows Installer know if it should allow you to install an older version of the product over a newer one. This defaults to no.
  • AllowSameVersionUpgrades - A yes or no value telling Windows Installer whether or not to perform an upgrade if the same version of the product is installed as what is in the MSI. It defaults to no.
  • Disallow - A yes or no value telling Windows Installer whether to allow upgrades at all. It defaults to no.
  • DisallowUpgradeErrorMessage - This is the error message that will be displayed an upgrade is attempted but disallow is set to yes.
  • DowngradeErrorMessage - This is the error message that will be displayed if the user tries to downgrade the product and AllowDowngrades is set to no.
  • IgnoreRemoveFailure - Lets Windows Installer know that it is not a problem if the old version can't be removed for whatever reason.
  • MigrateFeatures - Takes the list of features to install from the already installed product.
  • RemoveFeatures - A formatted string containing all the features that should be uninstalled in case of an upgrade.
  • Schedule - When you want the old version of the product to be removed.
  • **WIX_UPGRADE_DETECTED** - This is the property that is set when an upgrade takes place. This replaces the property that was used in 3.0 and before.


If you look at my example you will notice that it is missing everything except for one error message. That is because it is using the default value for everything else. This is what I currently use in every setup project that I maintain, because it is simply the standard. No point fixing it if it isn't broken. Any of the defaults can be explicitly written for clarity, but I find it clearer to only list what is not a default.

I think that is about enough information for this tutorial. I hope you enjoyed it and as always I welcome any comments that can make future tutorials better.

Is This A Good Question/Topic? 0
  • +

Page 1 of 1