MSI Upgrade Overview
Before you attempt to create an upgrade of your MSI, you should understand the fundamentals of MSIs and how they support upgrades.
Types of Windows Installer Upgrades
There are three types of upgrades possible with Windows Installer: Small Update, Minor Upgrade and Major Upgrade.
In only very rare instances would you want to create a Small Update or Minor Upgrade. When a Major Upgrade is created, the newer MSI can simply upgrade previous version(s) of a product by executing the newer MSI. For practical reasons and greatest flexibility, we require you to create a Major Upgrade for each revision of your product for an upgrade to work within the Symantec Installation Manager.
- So, What is a "Major Upgrade"?A major upgrade is used to make "major" changes to an installed MSI. With a major upgrade you could add a new top-level feature and install many files, change/add registry values, etc. If you are rolling out a new version of an application with extra functionality it would typically be a major upgrade. The Product Code, Package Code and Product Version are changed in the MSI to support a Major Upgrade.
The Three MSI Codes involved in Upgrades
In order to understand Windows Installer upgrades you need to understand three codes present in every Windows Installer database: the Package Code, the Product Code and the Upgrade Code. These codes are the source of much confusion... make sure you understand the differences of each!
- The Package Code- The Package Code uniquely identifies the Windows Installer database (MSI). It should be changed each time the database is modified. No two non-identical Windows Installer packages should ever share the same package code. The package code is stored in the Summary Information Stream of the MSI.
- The Product Code- The Product Code is a unique GUID identifying the individual product being installed. This code must be unique on the destination computer. If you try to install two packages containing the same Product Code you will see the following error: ''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.'' This code can be found in the Properties table of the MSI. Don't confuse this with the productGuid that you have specified in the config file(s)! Think of this code as a way to identify a specific instance of an installation of your product.
- The Upgrade Code- The Upgrade Code is a GUID which identifies a set of related products. If we have different versions of the same product they should share the same Upgrade Code. This allows any later version of a product to find previous versions and to replace them. Never change this code within the same family of products. This code can also be found in the Properties table of the MSI. This code is typically the same as the productGuid that is specified in your config file(s), but does not have to be. While generally speaking about MSIs this code applies to a "family of products", the Altiris/Symantec convention is to use this code to specify the identity of a single product.
Where to find the Codes in your MSI
- UpgradeCode- Property table
- ProductCode- Property table
- ProductVersion- Property table
- PackageCode- Summary Information Stream
The MSI Upgrade Table
Finally, in order to understand Windows Installer upgrades you need to understand the Upgrade table. There are many properties in the Upgrade table that you will need to set properly to ensure your upgrade works properly.
- Upgrade Code- The FindRelatedProducts MSI action will search all packages on the target machine in order to find any where the Upgrade Code property matches this value. In other words, this code needs to match the UpgradeCode of your previous product(s) so this MSI knows which products to consider for upgrade.
- Minimum Version- The minimum version to search for. Any packages containing the specified UpgradeCode but with a version lower than this will not be detected. Keep in mind that the only the first three numbers are recognized (ex. 7.0.2210.332 will be recognized as 7.0.2210)
- Maximum Version- The maximum version to search for. Any packages containing the specified UpgradeCode but with a version higher than this will not be detected. Keep in mind that the only the first three numbers are recognized (ex. 7.0.2210.332 will be recognized as 7.0.2210)
- Language- You can search only for specific language versions. If this is left null all languages will be detected. All languages should be upgraded by convention.
- Features to remove- You can choose to only remove certain features specified on this field. If this is left blank all feature will be removed (this is most typical).
- Attributes- See the windows installer documentation at [http://msdn.microsoft.com/en-us/library/aa372379(VS.85).aspx]
- Migrate feature states: Feature states, such as advertised, will be migrated to the upgraded version.
- Do not uninstall previous version: The previous version will not be installed.
- Continue installation after a removal failure: Will continue the install if the removal of the base application fails.
- Include minimum version in range: Specifies whether the Min Version specified is included in the search.
- Include maximum version in range: Specifies whether the Max Version specified is included in the search.
- Exclude languages: Specifies whether the languages listed are excluded from detection.
- Action Property- The property that will be created if a matching package is detected. This simply indicates in the installer that an upgrade is taking place.
Creating your MSI Upgrade, Step-By-Step
Now that you have had a crash course in MSI Upgrades, it is time to actually do the work. If you are using a tool such as Wise or Wix to make your changes, make sure you follow the appropriate steps to make these changes. Here are the general steps you need to take to create your Upgrade MSI:
Required Steps
- Step 1:Change your MSI Package Code (this must ALWAYS change with each new build/release)
- Step 2:Change your MSI Product Code (this must ALWAYS change for an MSI Major Upgrade)
- Step 3:Create a new entry containing your MSI Upgrade Code in the UpgradeCode field in the Upgrade table
- Step 4:Specify the minimum version this MSI can upgrade in the VersionMin field of the Upgrade table in your MSI
- Step 5:Specify the maximum version this MSI can upgrade in the VersionMax field of the Upgrade table in your MSI
Optional Steps
- Step 6:Specify the various attributes of your upgrade (see The MSI Upgrade Table above) in your MSI - If you are required to keep previous assemblies installed along with your newer versions, you should make sure you set the flag indicating that you do not want the previous version uninstalled.
Recommended Additional Step (for Wise users)
- Step 7:Run the UpgradeSync tool to verify your changes. This tool will verify that the key paths and components are aligned correctly between the previous and current installations, and if necessary, updates the package, product and version codes. This will ensure that your upgrade is consistent and correct and should minimize problems. This tool can be found in the Wise Installer Editor under Tools->UpgradeSync.
Examples:
- Using Wix, creating an MSI that Upgrades versions 7.0.0 to 7.0.2210 to version 7.0.2300, that will remove the previous version:
<Product Id='YOUR NEW PRODUCT CODE' Name='YOUR PRODUCT NAME' Language='1033' Version='7.0.2300' UpgradeCode='YOUR UPGRADE CODE' Manufacturer='Symantec'>
<Package Id='YOUR NEW PACKAGE CODE' Description='YOUR PRODUCT DESCRIPTION' Comments='Version 7.0.2300' Manufacturer='Symantec' InstallerVersion='200' Compressed='yes'/>
<Upgrade Id='YOUR UPGRADE CODE'>
<UpgradeVersion OnlyDetect='no' Property='PROJECT_UPGRADE' Minimum='7.0.0' Maximum='7.0.2210' IncludeMinimum='yes' IncludeMaximum='yes' RemoveFeatures='all'/>
<Property Id='PROJECT_UPGRADE' Secure='yes'/>
</Upgrade>
...
</Product>
- Upgrade Attributes Wix Reference- See the windows installer documentation at [http://msdn.microsoft.com/en-us/library/aa372379(VS.85).aspx] or wix documentation at [http://wix.sourceforge.net/manual-wix2/wix_xsd_upgradeversion.htm]
Migrate feature states - Wix equivalent: MigrateFeatures='yes' attribute on UpgradeVersion element
Do not uninstall previous version - Wix equivalent: OnlyDetect='yes' on UpgradeVersion element
Continue installation after a removal failure - Wix equivalent: IgnoreRemoveFailure='yes' attribute on UpgradeVersion element
Include minimum version in range - Wix equivalent: IncludeMinimum='yes' attribute on UpgradeVersion element
Include maximum version in range - Wix equivalent: IncludeMaximum='yes' attribute on UpgradeVersion element
Exclude languages - Wix equivalent: ExcludeLanguages='yes' attribute on UpgradeVersion element
Build your MSI and you should have an MSI that supports upgrades of previous versions.
Finally, you must update the current product listing to specify the new product. Here are the steps you must follow using SIM Product Listing Editor (SIMPLE):
- Import your new MSI package(s) that support upgrade
- Create a new Product and name/version it appropriately
- Go to the Product->Components tab. Add the new packages to your product
- Go to the Product->Supersedes tab. Add the previous product version to your list of supersedes
- Go to the Product Listing tab. Add your new product to the product listing
- Finally, generate the new product listing