Package Codes

The package code is a GUID identifying a particular Windows Installer package. The package code associates an .msi file with an application or product and can also be used for the verification of sources. The product and package codes are not interchangeable. For details, see Product Codes.

Nonidentical .msi files should not have the same package code. It is important to change the package code because it is the primary identifier used by the installer to search for and validate the correct package for a given installation. If a package is changed without changing the package code, the installer may not use the newer package if both are still accessible to the installer.

The package code is stored in the Revision Number Summary Property of the Summary Information Stream. Note that letters in product code and package code GUIDs must be uppercase. Utilities such as GUIDGEN generate GUIDs containing lowercase letters. The lowercase letters in these GUIDs must be changed to uppercase to be used as a product code or package code.

Although it is common to ship an application that has the same package code and product code, the two values can diverge as the application is updated. For example, including a new file with the application would require updating the installation database to install the file. If the changes are minor a developer may choose not to change the product code, however, a different .msi file is needed to install the new file and so the package code must be incremented. Conversely, a single package can be used to install more than one product. For example, the installation of a package without a language transform could install the English version of the application and the installation of the same package with a language transform could install the French version. The transform is distinct from the .msi file that determines the package code. The English and French versions could have different product codes and the same package code because they are both installed with the same .msi file.

Product Codes

The product code is a GUID that is the principal identification of an application or product. For more information, see the ProductCode property. If significant changes are made to a product then the product code should also be changed to reflect this. It is not however a requirement that the product code be changed if the changes to the product are relatively minor.

The 32-bit and 64-bit versions of an application’s package must have different product codes. If any 32-bit component of an application is recompiled into a 64-bit component, a new product code must be assigned.

If a server exposed in the PublishComponent Table is recompiled from 32-bits to 64-bits, the GUID in this table may also need to be changed so that 32-bit and 64-bit clients can identify the appropriate qualified component category. In this case, the product code must also be changed.

Note that letters in product code GUIDs must be uppercase. Utilities such as GUIDGEN generate GUIDs containing lowercase letters. The lowercase letters in these GUIDs must be changed to uppercase to be used as a product code or package code. For more information, see Changing the Product Code.

The package code is a GUID identifying a particular Windows Installer package. The package code associates an .msi file with an application or product and can also be used for the verification of sources. The product and package codes are not interchangeable. No two nonidentical .msi files should ever have the same package code. Although it is common to ship an application that has the same package code and product code, the two values can diverge as the application is updated. For more information, see Package Codes.

Patching and Upgrades

Because an installation package can contain the files that make up an application as well the information needed for their installation, Windows Installer can be used to update the application. The installer can update information in the following parts of the installation package:

• The .msi file.
• The files of the application.
• The Windows Installer registration information.

The type of update can be characterized by the changes the update makes to the application’s product code, product version, and package code. The application’s product version is stored in the ProductVersion property. The application’s product code is stored in the ProductCode property. The application’s package code is stored in the Revision Number Summary Property.

An update that changes the application into another product is required to change the ProductCode of the application. For more information about which updates require changing the ProductCode see Changing the Product Code. The update can change the ProductVersion and leave the ProductCode unchanged if future versions of the application will need to differentiate between the updated and nonupdated versions of the current product. The Package Code uniquely identifies the installation package and should always be changed whenever update or upgrade changes any information in the installation package.

When deciding whether to change the product version, you should consider If future versions of the application will need to differentiate between the updated and nonupdated versions of the current product. To ensure differentiation in the future, a minor upgrade should be used instead of a small update.

• If an update changes the .msi file and application files, but does not change the ProductCode property or ProductVersion property, it is termed a small update.
• If the update changes the ProductVersion, but does not change the ProductCode, it is termed a minor upgrade.
• If the update changes the installation into an entirely different product, the ProductCode must change and the update is termed a major upgrade.

To ensure differentiation of versions of the current product in the future, a minor upgrade should be used instead of a small update.

The following table summarizes the different types of updates.

Type of update	Productcode	ProductVersion	Description
Small Update	No change	No change	An update to one or two files that is too small to warrant changing the ProductVersion. The package code in the Revision Number Summary Property does change. Can be shipped as a full installation package or as a patch package.
Minor Upgrade	No change	Changed	A small update making changes significant enough to warrant changing the ProductVersion property. Can be shipped as a full installation package or as a patch package.
Major Upgrades	Changed	Changed	A comprehensive update of the product warranting a change in the ProductCode property. Shipped as a patch package or as a full product installation package.

The Windows Installer can install an application, or an update, for all users of a computer (per-machine context) or for a particular user (per-user context) depending on the access privileges of the user, the value of the ALLUSERS property, and the version of the operating system. Application developers should consider in which context updates will be installed. If the contexts of the application and update are different, the application may not be updated as expected.

Users can update to an application by reinstalling a Windows Installer package for the application. Note that Minor Upgrades can be applied in the same way as Small Updates. For more information about updating an application by reinstalling the application, see these sections:

An update to an application can be provided to users as a Windows Installer patch package. A patch can contain an entire file or only the file bits necessary to update part of a file. This means that the user can download an upgrade patch that is much smaller than the entire product and that preserves user customizations through the upgrade. Note that Minor Upgrades can be applied in the same way as Small Updates. For more information about updating an application using a patch, see these sections:

Product Identification (ProductCode and UpgradeCode)

ProductCode

The ProductCode property is a unique GUID used to identify your application. This identifier varies from version to version of the same installer. We recommend using the same ProductCode for each language of your installer : FAQ : Why do I need to set the same Product Code for each language of a package?

If you have an application, for example, a dictionary or translation app, and you want each language installed/uninstalled separately, then it’s recommended that you use different product codes for each package.

Also, it is important to note that two products with the same ProductCode can not be installed on the same computer. Windows Installer will prevent this with an error reading:

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 Programs and Features in the Control Panel.

The ProductCode property is stored within the .aip project file.

UpgradeCode

Unlike the ProductCode, the UpgradeCode is a GUID representing a related set of products. A set of different versions of your application will have the same UpgradeCode. This enables newer versions of your application to search and upgrade previous versions installed on the same computer.

The UpgradeCode property is stored within the .aip project file.

PackageCode

This is not to be confused with the ProductCode property. Although it is a GUID, the package code is not a property referring to a version of your product. It is more specific than that, meaning it refers to the particular .msi file generated. A new PackageCode is generated each time you build your project. Think of the PackageCode as some sort of checksum. No two .msi files should ever have the same PackageCode unless they are identical.

A common instance in which the PackageCode can be seen in action is when your product has already been installed on the machine. Suppose the user would then double-click the installer again. Windows Installer will check the installer’s ProductCode to see if the product has been installed on the machine. Since it was, Windows Installer will find it and then check the PackageCode of the installed product. One of two things can happen:

• should the PackageCode found be identical with the PackageCode of the installer double-clicked by the user, Windows Installer will run the installer in maintenance mode and the user will then be presented with choices to alter the installed product, repair it or remove it (done through the MaintenanceTypeDlg).
• should the PackageCode found be different than the PackageCode of the installer double-clicked by the user, Windows Installer will display the error mentioned in this article’s «ProductCode» section.

The PackageCode property is NOT stored within the .aip project file. It is instead generated each time you rebuild your project.

Copying your project files

Should you ever feel the need to use one of your projects as a base for another project, we strongly encourage you to save your project as a template and then open it through the Custom Templates tab.

We strongly advise against starting a new project from a copied .aip project file. This is because the ProductCode and UpgradeCode properties are stored in it. You would then end up working on two products having the same ProductCode and UpgradeCode. When you would then try to install both products on the same machine, you would encounter the error discussed in this article’s «ProductCode» section.

Advanced Installer provides you with the possibility to generate new ProductCodes and UpgradeCodes for your project. This can be done through selecting Project->Options->Project IDs. On this tab you can generate new codes for your project. This is an easy fix should you ever find yourself having two projects with the same ProductCode and UpgradeCode.

Changing the Product Code

The product code is a GUID that is the principal identification of an application or product. See Product Codes.

An update that meets the following guidelines generally does not require a change of the product code and can be handled as a small update, or if the version is to change, as a minor upgrade:

• The update can enlarge or reduce the feature-component tree but it must not reorganize the existing hierarchy of features and components described by the Feature and FeatureComponents tables. It can add a new feature to the existing feature-component tree. If it removes a parent feature, it must also remove all the child features of the removed feature.
• The update can add a new component to a new or an existing feature.
• The update must not change the component code of any component. Consequently, a small update or minor upgrade must never change the name of a component’s key file because this would require changing the component code.
• The update must not change the name of the .msi file of the installation package. Instead, because it modifies the package, it should change the package code. Note that this means that the update can change the tables, custom actions, and dialogs in the .msi file without changing the file’s name.
• The update can add, remove, or modify the files, registry keys, or shortcuts of components that are not shared by two or more features. If the update modifies a versioned file, that file’s version must be incremented in the File table. If the update removes resources, it should also update the RemoveFile and RemoveRegistry tables to remove any unused files, registry keys, or shortcuts that have already been installed.
• The update of a component that is shared by two or more features must be backward compatible with all applications and features that use the component. The update can modify the resource of a shared component, such as files, registry entries, and shortcuts, as long as the changes are backward compatible. It is not recommended that the update add or remove files, registry entries, or shortcuts from a shared component.
• A small update is shipped as a Windows Installer patch package. (A full product CD-ROM is usually not provided with a small update.)

The product code must be changed if any of the following are true for the update:

• Coexisting installations of both original and updated products on the same system must be possible.
• The name of the .msi file has been changed.
• The component code of an existing component has changed.
• A component is removed from an existing feature.
• An existing feature has been made into a child of an existing feature.
• An existing child feature has been removed from its parent feature.

Note that adding a new child feature, consisting entirely of new components, to an existing feature does not require changing the product code.

New child features can be authored by including msidbFeatureAttributesFollowParent and msidbFeatureAttributesUIDisallowAbsent in the Attributes field of the Feature table. If the minor upgrade only adds new child features, then REINSTALL=ALL is sufficient to force the installation of the new child features. For more information, see Controlling Feature Selection States.

A new child feature may be hidden from the user. To synchronize the installation state of a new child feature with its parent feature, set the msidbFeatureAttributesFollowParent and msidbFeatureAttributesUIDisallowAbsent bits for the child feature.