Upgrades and patches

In virtually all real world situations, at some point you need to deploy an update to a product you already deployed previously. In the world of Windows Installer, there are two ways to distribute an updated version of an existing product. One way is to create a new setup package in the form of an upgrade. The other way is to create a patch.

As explained in Chapter 5, ‚“Windows Installer Inside and Out, ‚½ there are three types of upgrades: small updates, minor upgrades, and major upgrades. A small update and a minor upgrade replace files from the earlier version with updated files from the newer version. A major upgrade uninstalls the previous version of the product and installs the updated version. Wise for Windows Installer enables you to create any of these three types of update packages.

Also as explained in Chapter 5, a patch is not a different kind of update, but rather a different kind of update package. The main advantage of a patch is that it is usually much smaller than the corresponding full upgrade package would be. WfWI also enables you to create a patch package.

Windows Installer has rules governing the changes required to an MSI file in order to configure it as a small update, a minor upgrade, or a major upgrade. WfWI comes with a tool called UpgradeSync to make these changes for you. Use of the UpgradeSync tool is optional, but if you don ‚ t use it, you ‚ re on your own to make the required changes. Refer to ‚“Using UpgradeSync ‚½ in the Wise for Windows Installer Help file for more information.

Creating an upgrade

Upgrades can be created only for products where the earlier version was also installed using Windows Installer. Creating an upgrade is much easier if you have access to the MSI file from the earlier version of the product. If you do not have access to the MSI file from the earlier version of the product, you at least need to know some of the information it contains, such as the Upgrade Code and the Version number.

To create an upgrade in Wise for Windows Installer, first create a setup project for the new version of the product just as if you were going to run it as a fresh install. An easy way to do this is to open the WfWI project file for the earlier version and save it with a new name . For example, to create a project file for version 2.0.0 of the DeployFox Demo App, we can open the project file for the original version (1.0.0) of the product, which is named DEPLOYFOX DEMO APP.WSI, and save it as DEPLOYFOX DEMO APP 200.WSI.

Naturally, there are changes to make in the new project file before compiling a release. Among the most important changes for a major upgrade is to update the Version number and to generate a new Product Code GUID. You can use the UpgradeSync tool to make these changes for you, or you can make these changes manually on the Product Details page by typing in a new Version number and clicking the Generate button to insert a new Product Code field. Figure 30 shows the updated Product Details page for version 2.0.0 of the demo app. If WfWI asks you whether to also generate a new Upgrade Code GUID, reply NO. A common Upgrade Code is what enables Windows Installer to identify an existing version of the same product on the user ‚ s computer at installation time.

Figure 30. To create an upgrade, update the Version number and generate a new Product Code GUID.

After changing the Version number and Product Code on the Product Details page, step though each of the remaining pages in the Installation Expert and make whatever other changes are necessary for the updated version. At a minimum, the updated app typically includes a new version of the EXE file and maybe an updated ReadMe or Help file. Some updates of course may involve much more extensive changes.

Remember ‚  

When preparing an upgrade you should also go to the Release Details page and specify a unique MSI file name, such as DEPLOYFOX DEMO APP 200.MSI, and a unique description for the new version. Making the MSI file name unique is particularly important if the compiler output for the update is going to be written to the same location as the compiler output from the original release. Unless you use a unique name the original files will be overwritten the first time you compile the new version. Even if you don ‚ t want the original files for deployment any more, you ‚ re still going to want them as the basis for future upgrades or patches, so it ‚ s a good idea to keep them intact. See Chapter 9, ‚“Support and Ch-Ch-Changes, ‚½ for more information on this topic.

The key to making the new setup package function as an upgrade is to add one or more entries to the Upgrades page specifying the earlier version(s) of the product the new version is designed to replace. The Upgrades page is found in the Installation Expert ‚ s Distribution group . This page is initially empty. To add a new entry, click the Add button to the right of the page detail area.

The first step in creating an upgrade entry is to select the MSI file of the earlier release of the product. WfWI prompts you to do this as soon as you click the Add button on the Upgrades page. In the case of the demo app, the MSI file for the earlier version of the product is the file DEPLOYFOX DEMO APP.MSI created when we compiled the original version of the product. On our development machine, this file is in the C:\DEPLOYFOX\WISE

SETUPS\RELEASE FILES folder. As soon as this MSI file is selected, WfWI opens the Upgrade Details dialog and populates it with information from the selected file, as shown in Figure 31 .

Figure 31. Wise for Windows Installer fills in the Upgrade Details page with information it reads from the original MSI file.

The Upgrade Code and Minimum Version values shown in Figure 31 are from the original version ‚ s MSI file. The Maximum Version value of 2.0.0 is the version number of the current project. Note the Include minimum version in range check box is selected, while the Include maximum version in range is not selected. This tells Windows Installer the current upgrade replaces all earlier versions starting with and including version 1.0.0, up to but not including version 2.0.0. Effectively, this means the current upgrade replaces all 1.x.x versions of the same product.

The Upgrade Action portion of the Upgrade Details dialog allows you to define features contained in the earlier version of the product that this upgrade is removing. By default, a major upgrade removes all features of the earlier version and installs the new ones. If you want to preserve any features from the earlier version, you must limit the removal of features to those specified in the Features to remove field. The spelling of feature names in this comma- separated list must exactly match the spelling of the feature names in the original setup. This is another good reason to keep the old installation files.

The Upgrade Action portion of this dialog also defines a Windows Installer property with a value set at installation time to the Product Code of any earlier version of the product found installed on the target computer. Custom actions can then be made conditional on the value of this property. Use of this property is optional, and custom actions are not required.

Finally, the Upgrade Actions portion of this dialog provides three check boxes you can use to further control the behavior of the upgrade at installation time. If selected, the Continue installation after a remove failure check box tells Windows Installer to go ahead with the installation of the upgrade even if the uninstallation of the earlier version fails in part or in whole. Select the Migrate feature states check box if you want the upgrade to install only those features installed with the original version of the product. Select the Do not uninstall previous version check box if you do not want the upgrade to uninstall a previous version of the product; this allows two versions of the product to co-exist on the same machine, assuming you used unique folder and file names where necessary to make this possible.

After completing the Upgrade Details page, click OK to add the entry to the Upgrades page. Now compile, test, and distribute the setup package as before.

Creating a patch

A Windows Installer patch file (MSP file) for any given product is essentially the difference between two Windows Installer setup packages (MSI files) for the same product. Like an upgrade, applying a patch to an existing version of a product on the user ‚ s machine requires the existing version to have been installed using Windows Installer. Unlike a major upgrade, a patch requires an earlier version of the product to exist on the target machine. A major upgrade functions like a fresh install if no earlier version of the product is installed.

A patch can update one or several earlier versions of a product. Creating a patch requires you have access to the MSI file for each of the earlier versions the patch is designed to update. Depending on how the earlier releases were built and whether there are previous patches, you may also need access to other files. Refer to ‚“What You Need to Create a Patch ‚½ in the Wise for Windows Installer Help file for more information.

In the previous section, we built a major upgrade package to update version 1.0.0 of the demo app to version 2.0.0. In this section we build a patch package to accomplish the same thing. The first step is to create the installation package for version 2.0.0, just as we did in the previous section. If you have not already done so, create the setup project for the updated version, compile it to generate the MSI file, and then close the project.

Now you are ready to begin the actual patch creation process. Select Tools Patch Creation from the main menu to launch the Patch Creation wizard. In the Patch Creation wizard, choose ‚“Create a new patch file. ‚½ The next step asks you to identify the MSI file(s) for the previous version(s) of the product. In the case of the demo app, there is only one earlier version. Its MSI file is the original DEPLOYFOX DEMO APP.MSI file, located in C:\DEPLOYFOX\WISE SETUPS\RELEASE FILES on our development machine. Figure 32 shows the Patch Creation wizard dialog for this step.

Figure 32. Creating a patch requires you to specify the MSI file for the original version of the product.

The Window Installer patch creation process needs to work with uncompressed base files. If the original setup contains compressed files, which is often the case in order to make the setup package as small as possible, those files need to be uncompressed for use in creating a patch. If the Patch Creation wizard detects the original MSI file contains compressed files, it offers to perform an administrative installation of the product on your machine. An administrative installation creates an uncompressed copy of the files in the setup package without actually installing the product. To create a patch, you must allow the Patch Creation wizard to perform the administrative installation of the product if it prompts you to do so. The uncompressed files are written to a temporary location on your computer.

The next step is to specify the MSI file for the new version of the product. In the case of the demo app, we select the MSI file for version 2.0.0 we built earlier, as shown in Figure 33 .

Figure 33. Creating a patch also requires you to specify the MSI file for the updated version of the product.

Because the MSI for version 2.0.0 of the demo app also contains compressed files, the Patch Creation wizard prompts you to perform an administrative installation of this version, too. As before, this is required to complete the patch creation process. The uncompressed files for version 2.0.0 are written to a different temporary location than the uncompressed files for version 1.0.0, resulting in both sets of uncompressed files being present on your machine. This is necessary because the patch creation process needs access to both sets of uncompressed files in order to create the patch file.

Note ‚  

While a patch package is smaller than a full upgrade package, the process of creating a patch package can consume significant amounts of disk space on the developer ‚ s machine. The administrative installation creates uncompressed copies of all the files in the setup package. This includes not only your application ‚ s own files but also the VFP 8 runtime files, ActiveX files, and any other files installed by your product. Even in the case of a simple product like the demo app, this amounts to over 15MB. Because there are two versions involved in this particular patch creation process, more than 30MB of disk space is required to support creation of this patch file. If the patch updates more than one earlier version of the product, uncompressed images of each of those other versions would also be required, consuming even more disk space.

The last step before compiling the patch is to specify a name and location for the patch file and to specify values for other settings that determine how the patch file is created. This is done in the Compile Patch dialog, illustrated in Figure 34 .

Figure 34. You can specify the name for the patch (MSP) file as well as choose other settings to determine how the patch file is compiled.

In Figure 34 we specified DEPLOYFOX DEMO APP 200 PATCH.MSP as the output patch file name, and indicated it should be written to the same Release Files folder as the other release files built for this app. The other settings all have their default values, which are appropriate for this and most other patches.

Clicking the Next button at this point starts the patch compilation process. This process can be somewhat time-consuming . Upon completion, and assuming no errors, the MSP file is written to the location you specified (see Figure 34). To deploy the patch, distribute the MSP file to your users. To install a patch from an MSP file, right click on the file in Explorer and choose Apply from the shortcut menu.

In addition to the MSP file, a patch creation project (PCP) file is also created. This file is a necessary intermediate file used in the patch creation process. You do not need to do anything with this file.

If the Create a log file check box was selected in the Compile Patch dialog, a log file is created with the same file name as the MSP file, but with a LOG file name extension. You can open the log file in any text editor and read the summary of the patch creation process.

In the demo app, the only difference between version 1.0.0 and version 2.0.0 app is the version number changed in the EXE file. The EXE file by itself is 603KB. The full upgrade package for version 2.0.0 of the demo app is 7.77MB, but the patch file for the same upgrade is about 98% smaller at 119KB. In a real application it ‚ s likely there would be more of a difference between the two versions, therefore resulting in a large patch file, but this example should give you some idea of the size advantage of a patch as compared to a full upgrade package.