Using an UpgradeCode

The UpgradeCode is primarily used for supporting major upgrades, although small and minor upgrade patches may use the UpgradeCode for product validation. During major upgrades, the FindRelatedProducts, MigrateFeatureStates, and RemoveExistingProducts actions detect, migrate, and remove previous versions of the product. The FindRelatedProducts action searches for products using criteria based upon the UpgradeCode, ProductLanguage, and ProductVersion. These criteria are specified in the Upgrade table.

Given the criteria used by the FindRelatedProducts action, the UpgradeCode can be the same for different languages and versions of a single product. This is because the Upgrade table allows for differentiating between products along version and language lines.

Across different versions of the same product, you may never need to change the UpgradeCode. Each stand-alone product should have its own UpgradeCode. A product suite should also have its own UpgradeCode. Doing so will allow the suite to upgrade previous versions of the suite or stand-alone products by using multiple rows in the Upgrade table.

The following two scenarios illustrate the use of the UpgradeCode.

  • Product A and Product B were shipped with the same ProductLanguage, ProductVersion, and UpgradeCode. Product A and Product B have different ProductCodes. Because the products were assigned the same UpgradeCode, the Upgrade table cannot be authored to differentiate the older version of Product A from the older version of Product B. In this case, you will be unable to have an upgrade installation of Product A that ignores Product B. Because these were different products, they should have each been assigned a different UpgradeCode.
  • The English and French versions of Product A were shipped with the same ProductVersion and UpgradeCode. Both the English and French versions of Product A have different ProductLanguages and ProductCodes. Even though both the English and French language versions share the same UpgradeCode, it is possible to author the Upgrade table such that only the older English language version will be detected and upgraded and the older French version ignored. Different language versions of a product can use the same UpgradeCode.