InstallAware for Windows Installer Header Image Windows Installer without Rocket Science
InstallAware for Windows Installer
 

Patching

After you have deployed a project, you may want to issue patch updates to it. Patches have the advantage of including only the changed parts of your setup since the last time you built them, and therefore both the installation process and the size of the installation package are extremely streamlined.

When you build a patch, the output folder of the patch will be as follows:

  • <BUILD Folder>\patch

A patch is always built against a collection of Patch References. Each patch reference is simply an older version of your setup which you will be patching against. You may add multiple patch references to your project as necessary.

The patch will be created according to the settings specified in the Build Settings section of the Project Options dialog.

Patch Requirements

For a patch to work successfully, you must correctly specify product, upgrade, and revision codes that are used in the original project and the patch project.

  • The patch references and the patch project must share the same upgrade code. Having the same upgrade code qualifies your patch to Windows Installer as being an update for the products you will be patching.
  • The patch references and the patch project must share the same product code. Having the same product code qualifies your patch to Windows Installer as being a patch for the products you will be patching.
  • The patch references and the path project must have a different revision code. Having a different revision code helps Windows Installer recognize that you are updating the products you will be patching.

To view and update the product, upgrade, and revision codes, use the Project Settings window.

When you create a new project in the InstallAware IDE, it will have its unique set of product, upgrade and revision codes. As you build versions of this setup, the revision code will be automatically changed, as long as the Change Revision Code Automatically Upon Rebuild option remains enabled in the Build Settings window. If these default settings are preserved, you will not need to manually manage your product, upgrade, and revision codes when creating patches.

Additionally, when working with patches, you may want to set the pre-defined compiler variable #NOHARDLINKS# to TRUE. This ensures that during each build, a full copy of each source file going into your setup is created. While this is not a concern for compressed or web build types, it can potentially create a problem with uncompressed builds as follows:

  1. When #NOHARDLINKS# is FALSE (the default value), the uncompressed build process creates hard links to your application files to improve build speeds on supported NTFS systems, instead of creating full copies of those files.
  2. When you update your application files, these changes are also reflected in the "already built" setup files which are just hard links to your original application files.
  3. When building a patch, the patching mechanism cannot detect any changes between old and new file versions, because they all contain the same data - in fact, they are all hard links pointing to the same file.

This is not a concern for compressed or web builds, because while hard links may still be utilized to improve build times, the compression process does store a full copy of your original application files, in their exact state during build time, inside the compressed setup package. Therefore, upon extraction, a full "old" copy of your original application files are created - allowing the patching mechanism to successfully detect any changes to files - instead of hard links that point back to your original application files, as would be the case with uncompressed builds.

When Not to Use a Patch

The following additional considerations apply for patches to work successfully:

  • The patch references and the patch project must have the same product name.
  • The patch references and the patch project must install into the same target directory.
  • The patch references and the patch project, on overall, must follow the same execution logic.

Do not try to build a patch for an old version that has a different product name, installs completely different sets of files, installs files to a different folder, or has a radically different MSIcode script (such that the order of installation commands and/or their execution logic is different from the latest version). Even if your patch builds successfully, the runtime application may yield unexpected results, such as being unable to resolve the patch source folder, and orphaning files installed by the old version.

Adding and removing files and registry keys in a patch is permissible, as long as these changes do not affect the overall structure of your MSIcode script. Significant changes to the MSIcode script will lower Windows Installer's ability to match your old patch reference data with your latest version, and may yield unexpected results. Please note that only Windows Installer commands and Flow Control commands are subject to these limitations. The remainder of your commands are not subject to these limitations, as they fall outside of the scope of Windows Installer's patching mechanism.

In cases where patching is inapplicable or does not produce the expected results, use a full version installer instead. Your full installer is automatically capable of uninstalling the old version before installing the new version, and is not subject to any of the above patching constraints.

Patch Source Resolution

When a patch runs on the target system, it requires access to the source media that was part of the original setup. Locating source media varies according to the build type of the original setup. In addition, a hard-coded path to the original setup sources may be specified on the command line. These options are described in detail below.

Source Resolution for Uncompressed Builds

When the setup runs, it will prompt for the original source media. At this point, if the uncompressed build was distributed on a CD or DVD (as would be typical for most uncompressed builds), the user will need to insert the physical media into the drive and choose the drive letter in the source media browser. If the uncompressed build resides on a hard disk folder, the user will need to choose that folder in the source media browser.

Source Resolution for Compressed Builds

When the setup runs, it will prompt for the original source media. At this point, the user will need to run the self extracting .EXE file that comprises the compressed build. When this file is running, as part of the setup initialization routine, it will extract its contents to a subfolder of the system temporary folder. The user will have to navigate into the system temporary folder, determine which subfolder contains the setup sources (by trial and error if necessary), and choose that in the source media browser.

Because this is a largely inconvenient way for end-users to apply a patch, Compressed Builds are not recommended as the targets of patches.

Source Resolution for Web Builds

When the setup runs, it will not prompt for original source media. It will automatically locate the source media for the setup on the target system. If required web media blocks are missing, they will be downloaded automatically. No source media browser will be shown at any time, and the patch will be applied immediately.

Because this provides the easiest way for users to apply a patch onto, Web Builds are the recommended targets of patches.

Forced Setup Source Caching

The default setup source caching behavior for each build type as described above may be overriden when setting the build type of your setup project using the Always Cache Setup Sources check-box. Even for uncompressed or compressed builds, you may force setup source caching. Alternately, you may force setup source deletion for web builds. If setup sources are forcibly cached, patch source resolution will be automatic. If setup sources are forcibly deleted, patch source resolution will always need to be manually performed as described above, or from the command line as described below.

Source Resolution from the Command Line

To prevent the original source media browser window from being shown, if a particular folder contains the source files of the original setup, you may use command line parameters to point the setup program to that particular folder so as to automate the source resolution process for patching.

<setup.exe> /p=<path to original setup sources>\data

You may specify any accessible folder, including a network location. This especially makes locating sources for patches on corporate networks very convenient. Please remember to specify the data subfolder inside the original setup source folder. This subfolder exists as part of all InstallAware uncompressed builds.