WindowsInstaller Update/Upgrade/Patch - Application Packaging Concepts

What is an upgrade?

In simple words upgrade is a new version of a software is designed to replace an older version of the same product.

In addition, the installation routines for upgrades often check to make sure that an older version is already installed on your computer; if not, you cannot install the upgrade.

Windows Installer supports three types of product upgrades: major upgrades, minor upgrades, and small updates

MSI Properties responsible for Upgrade are:

·         Product Code

·         Package Code

·         Product Version

Product Code

Windows Installer property that contains the GUID of a product.

Windows Installer treats two products with different Product Code GUIDs as unrelated, even if the values for the Product Name Property are the same.

Package Code

The package code identifies a particular database therefore EVERY MSI build have different package code.

Product Version

Windows Installer property that contains the product version & uses only the first three fields of the Product Version property for version comparisons.

For example, for a product version of 1.2.3.4, the 4 is ignored.

Upgrade Code

Windows Installer property that contains a GUID representing the product family.

The Upgrade Code is primarily used for supporting major upgrades, we may never need to change the Upgrade Code

The Upgrade Code should be consistent across different versions and languages of a family of related products for patching purposes.

For any type of upgrade, we can change various combinations of the package code, product version, and product code to identify the product being installed. The following table identifies when each code should be changed for different types of upgrades.

The following table indicates the change in property as per the Update/Upgrade type:

Upgrade Type	Package Code	Product Version	Product Code	Upgrade Code
Small Update	Yes	No	No	Never Change
Minor Upgrade	Yes	Yes	No	Never Change
Major Upgrade	Yes	Yes	Yes	Never Change

Types of Upgrade

1. Small Updates

A small update is also commonly referred to as a quick fix engineering (QFE) update and does not permit reorganization of the feature-component tree.

A typical small update changes only one or two files or a registry key. Because a small update changes the information in the .msi file, the installation package code must be changed. The package code is stored in the Revision Number Summary property of the Summary Information Stream.

The product code is never changed with a small update, so all of the changes introduced by a small update have to be consistent with the guidelines described in Changing the Product Code. An update requires a major upgrade to change the Product Code. If it is necessary to differentiate between products without changing the product code, use a minor upgrade.

In Small update:

·         An update to one or two files that is too small to warrant changing the Product      Version.

·         The package code GUID does change.

·         Can be shipped as a full installation package or as a patch package.

·         No change in Product Code and Product Version.

2. Minor update

A minor upgrade is an update that makes changes to many resources and can be used to add new features and components but cannot reorganize the feature-component tree.

Can be shipped as a full installation package or as a patch package.

An application can be upgraded by reinstalling an updated installation package (.msi file), or by applying a Windows Installer patch (an .msp file) to the application.

In Minor update:

·         No change in Product Code

Command line for small and minor update

Msiexec /fvomus [path to updated .msi file]                       OR

Msiexec /I [path to updated .msi file] REINSTALL=ALL     REINSTALLMODE=vomus                             OR

Msiexec /I [path to updated .msi file] REINSTALL= F1, F2               REINSTALLMODE=vomus

The REINSTALLMODE property is a string that contains letters specifying the type of reinstall to perform.

Code	Option
p	Reinstall only if the file is missing.
o	Reinstall if the file is missing or is an older version.
e	Reinstall if the file is missing, or is an equal or older version.
d	Reinstall if the file is missing or a different version is present.
c	Verify the checksum values, and reinstall the file if they are missing or corrupt. This flag only repairs files that have msidbFileAttributesChecksum in the Attributes column of file table.
a	Force all files to be reinstalled, regardless of checksum or version.
u	Rewrite all required registry entries from the Registry table that go to the HKEY_CURRENT_USER Or HKEY_USERS registry hive.
m	Rewrite all required registry entries from the Registry table that go to the HKEY_LOCAL_MACHINE Or HKEY_CLASSES_ROOT registry hive.
s	Reinstall all shortcuts and re-cache all icons overwriting any existing shortcuts and icons.
v	Use to run from the source package and re-cache the local package. Do not use the v reinstall option code for the first installation of an application or feature.

3. Major update

A major upgrade is a comprehensive update of a product that needs a change of the Product Code Property

During major upgrades following actions detect, migrate, and remove previous versions of the product.

·         FindRelatedProducts

·         MigrateFeatureStates

·         RemoveExistingProducts

The FindRelatedProducts action searches for products using criteria based upon the Upgrade Code, Product Language, and Product Version. These criteria are specified in the Upgrade table.

How to start working on Major Updates

Steps to Create Major Upgrade with InstallShild

Major upgrade generally uninstalls the earlier version and installs a new version

Step1: change version

Go to General Information->Product Properties->Version Field->Update the new version (Ex 1.0 to 2.0)

Step2: change Product Code

Go to General Information->Product code->Generate GUID

Step3: change Package Code

Go to Summery information->Package code->Generate GUID

Step 4: Upgrade View

Go to Media->Upgrade->Add automatic Upgrade Items->Add major Upgrade Item->Name it

We can do several configuration as per the need in this section

(Default Setting Style Complete Uninstall and Install)

This step adds an entry in UPGRADE Table which can be edited later and discussed further.

Step 5:

Make the new configuration/changes in project.

Step 6:

Build/save the project.

NOTE: Before installing major upgrade earlier version must be present on target build.

UPGRADE Table

The Upgrade table contains the columns shown in the following table.

Columns of Upgrade Table are as follows

Upgrade Code

The Upgrade Code property in this column specifies the upgrade code of the products that are to be detected by the FindRelatedProducts action.

VersionMin

Lower boundary of the range of product versions detected by FindRelatedProducts.

If VersionMin equals an empty string ("") it is evaluated the same as 0.

If VersionMin is null, FindRelatedProducts detects all previous versions.

VersionMin and VersionMax must not both be null.

Note that Windows Installer uses only the first three fields of the product version. If you include a fourth field in your product version, the installer ignores the fourth field.

Language

The set of languages detected by FindRelatedProducts.

Enter a list of numeric language identifiers (LANGID) separated by commas.

If Language is null or an empty string (""), FindRelatedProducts detects all languages.

Remove

The installer sets the REMOVE property to features specified in this column.

The Formatted string entered in this field must evaluate to a comma-delimited list of feature names.

For example: [Feature1], [Feature2], [Feature3].

No features are removed if the field contains formatted text that evaluates to an empty string ("").

The installer sets REMOVE=ALL only if the Remove field is empty.

Action Property

When the FindRelatedProducts action detects a related product installed on the system, it appends the product code to the property specified in this field.

The property specified in this column must be a public property and the package author must add the property to the SecureCustomProperties property.

Each row in the Upgrade table must have a unique Action Property value.

Attributes

This column contains bit flags specifying attributes of the Upgrade table.

Custom Action Responsible for Upgrade

1. FindRelatedProducts.

The FindRelatedProducts action runs through each record of the Upgrade table in sequence and compares the upgrade code, product version, and language in each row to products installed on the system.

When FindRelatedProducts detects a correspondence between the upgrade information and an installed product, it appends the product code to the property specified in the Action Property column of the Upgrade Table.

2. MigrateFeatureStates. 

This action is used during upgrading and when installing a new application over a related application.

MigrateFeatureStates reads the feature states in the existing application and then sets these feature states in the pending installation.

The method is only useful when the new feature tree has not greatly changed from the original.

MigrateFeatureStates action runs through each record of the Upgrade table in sequence and compares the upgrade code, product version, and language in each row to all products installed on the system.

If MigrateFeatureStates action detects a correspondence, and if the msidbUpgradeAttributesMigrateFeatures bit flag is set in the Attributes column of the Upgrade table, the installer queries the existing feature states for the product and sets these states for the same features in the new application.

3. RemoveExistingProducts.

This action goes through the product codes listed in the Action Property column of the Upgrade table and removes the products in sequence by invoking nested installations.

If the Remove field in Upgrade Table is blank, its value defaults to ALL and the installer removes the entire product.

NOTE:

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.

Some common scenarios which help us to decide which type of update/upgrade is to be used during packaging

Refer below table

Requirement for the Upgrade	Use a Major Upgrade?	Use a Minor Upgrade?	Use a Small Update?	Notes
Change the name of the .msi package	Yes	No	No	The default file name is taken from the Product Name property, provided the .msi file is not compressed in a Setup.exe installation launcher.
Enable end users to install earlier versions and the latest version on the same machine	Yes	No	No
Add a new sub feature	Yes	In some cases	In some cases	If the new sub feature consists of new components only, you can use a small update, a minor upgrade, or a major upgrade. If the new sub feature consists of existing components, you must use a major upgrade.
Move or delete a feature in the product tree	Yes	No	No
Add a new component to a new feature	Yes	Yes	Yes
Add a new component to an existing feature	Yes	Yes, if the version of Windows Installer is 2.0 or later	Yes, if the version of Windows Installer is 2.0 or later	Windows Installer 1.x requires new components in an upgrade package to be placed in new features for minor upgrades and small updates; it also requires special command-line handling.
Move or delete a component in the product tree	Yes	No	No
Change the component code of an existing component	Yes	No	No
Change the key file of a component	Yes	No	No
Add, remove, or modify any of the following: files, registry keys, or shortcuts	Yes	Yes	Yes	If the file, registry key, or shortcut is in more than one component and the component is shared by two or more features, a major upgrade must be used.

Determining the Best Packaging Option for Our Upgrade

Solution includes a table that we can review to determine what type of packing option we should use to update an earlier version of our product.

In some cases, a standard patch or a Quick Patch may be seem to be the ideal mechanism for packaging our upgrade. However, under certain conditions, we should package our upgrade as a full installation instead of a patch.

For example, if the target image was created with Windows Installer 1.2 or earlier, and the upgraded image is created with Windows Installer 2.0 or later, we should package our upgrade as a full installation, but not as a patch.

Creating patches for packages that span this schema inflection point can be problematic.

If we want our upgrade to move one or more files on the target system from one location to another, we should package our upgrade as a full installation, but not as a patch. If our end users install a patch for an upgrade that moves files on the target system, problems may occur.

For example, the patch may not work, a repair to the target system may not work, a subsequent patch may not work, or end users may not be able to uninstall the product. As a workaround, we can create our patch so that it deletes the files in the old location and adds the files to the new location.

If we want to change our installation from compressed to uncompressed, or vice versa, we should package our upgrade as a full installation, but not as a patch. If we use a patch in this scenario, a repair to the target system may not work, a subsequent patch may not work, or the end user may not be able to uninstall the product.

If we need to move files from one .cab file to another, or if we need to change the order of files in a .cab file, we should package our upgrade as a full installation, but not as a patch.

If our original installation had more than 32,767 files but our latest installation has fewer than 32,767 files, a patch will fail. Similarly, if our original installation had fewer than 32,767 files but our latest installation has more than 32,767 files, a patch will fail. In either case, we should package our upgrade as a full installation.

Note that if both the original installation and the latest installation have more than 32,767 (or both have fewer than 32,767 files), we can package our upgrade as a patch.

Patches cannot be created for major upgrades of InstallScript MSI projects. Therefore, if we need to distribute a major upgrade for an InstallScript MSI project, we should package it as a full installation.

PATCH

A Windows Installer patch (.msp file) is a file used to deliver updates to Windows Installer applications. The patch is a self-contained package that contains all the information required to update the application.

The patch file will contain only the bits that are different between two application files as opposed to copying over the complete file itself. When the patch is applied to the earlier application file, it is turned into the newer application file, changing out those bits that are different between the two files. The major advantage of using a patch file over re-installing a full setup program is that the patch file is very small.

Command line for patch

Installation:

        1) Already installed product:

                Msiexec /p <PatchName.msp> /qb        

        2) By Admin Image:

               a) Create admin image:

                Msiexec /a <MSIname.msi> TARGETDIR="c:\TEMP\MSI"

                b) Apply patch to admin image which was created in above step:

Msiexec /a "Path of admin image msi <MSIName.msi>" /p "Path and name of msp file<MSPName.msp>"

Uninstallation:

Msiexec /I PRODUCTCODE MSIPATCHREMOVE=PATCHCODE /qb              OR

Msiexec /package PRODUCTCODE /uninstall Patch CODE /qb

Multiple Patch Installation:

                Msiexec /I <MSIName>.msi Patch= Patch1.msp;Patch2.msp /qb

Multiple patches can be applied to a product in a constant order, regardless of the order that the patches are provided to the system.

Windows Installer 2.0:  Not supported. Windows Installer versions earlier than 3.0 install patches in order that they are provided to the system.

Windows Installer 3.0 and later:  The installer can use the information provided in the MsiPatchSequence table to determine which patches are applicable to the Windows Installer package and in which order the patches should be applied.

When the patch package does not have an MsiPatchSequence table, the installer always applies the patches in the order that they are provided to the system.

A Windows Installer package can install NO more than 127 patches when installing or updating an application.

Patch Sequence Table view

Patch Family	Product Code	Sequence	Attributes
AppPatch	{18A9233C-0B34-4127-A966-C257386270BC}	1.1.0

PATCH VS SMALL Upgrade

Patches enable us to distribute just the bits and portions of the database necessary to update our application’s files to a specific version, possibly resulting in a much smaller package than an upgrade packaged as a full installation. This enables us to deploy our upgrades using much less bandwidth than that required to deploy a full-installation package.

NOTE:

A patch is not a type of upgrade. Patching is simply a mechanism for distributing a major upgrade, a minor upgrade, or a small update with a small footprint. In fact, creating a patch involves first designing the upgrade and then packaging it as a patch. Before we create a patch, it is recommended that we test the upgrade as a full-installation package.

Thank you!