Creating and troubleshooting patches

Products

• Symantec Products

Issue/Introduction

 

Resolution

Question
How do I create and troubleshoot patches?

Answer

Do you want to make a change to your installation? If it’s a small change, consider creating a patch. A patch is a small file that contains only the differences between the old and new versions of an installation. An advantage to patches is that because of their size, they install more quickly than full application installations.

A patch updates an application previously installed with Microsoft Windows* Installer. Patches do not install full applications; they require that a previous version of the application be installed on the destination computer. If you have significant differences between the previously installed application and the new version, use an upgrade rather than a patch.

You can create three types of upgrades: a small update, a minor upgrade, and a major upgrade. Use a small update when you make minimal changes to the installation. An update does not cause the version of the application to change. When you add new files, make several minor changes, or fix bugs that cause changes, use a minor upgrade. With these types of changes, change the minor version number of the product. For significant changes to the installation, use a major upgrade. Major upgrades cause a full version change to the product. The table below shows installation changes with each type of upgrade. Typically, you create a patch for a small update or minor upgrade. For a major upgrade, it is recommended to create the upgrade using the Upgrades page in the Installation Expert rather than creating a patch.

Note: Minor upgrades can ony be deployed through the command line by using the following command line. The Minor upgrade is recached and repaired, so it can be installed over the previous version without changing the Product code but only though the following command line:

msiexec /fv <FullPathToMSI>

	Version Number	Product Code	Package Code	Upgrade Code
Small Update	No change	No change	Change	No change
Minor Upgrade	Change	No change	Change	No change
Major Upgrade	Change	Change	Change	No change

Now that you know what a patch is, when to use it, and what changes it makes in your installation, you can create a patch for your installation.

Create a patch

1. Start Wise for Windows Installer, Wise Installation Express/Studio, or Wise Package Studio. If you are using Wise Package Studio, start the Windows Installer Editor tool.
2. Open the previous version of your .wsi.
3. Make changes to your installation. For example, update existing files. 
   
   Note: If you plan to deploy your software to machines that do not have Windows Installer 2.0 pre-installed, any new component you add to your installation must be added to a new feature.
4. For a minor upgrade, if necessary, modify the Product Version in the Product Details page of the Installation Expert. Changing the Version field on the Product Details page causes the package code to update automatically. After you compile your installation, a new package code is generated for the installation.
5. For a small update that does not require you to change the product version, you will need to update the package code.
   • In Setup Editor, click the Product tab.
   • Select Summary.
   • In the right pane, double-click Package Code. The Summary Details dialog appears.
   • Click the Generate button. A warning dialog may appear which asks if you want to change the Upgrade code. Click the No button.
   • Click OK to save the updated package code.
6. Select Save As from the File menu then save the .wsi in a different location or with a different name.
7. Click the Compile button to compile the new installation in an .msi.
8. Click the Run button to run your new .msi and verify that it installs properly before creating the patch.
9. Run the UpgradeSync tool to check for any differences or problems with the packages that might prevent you from being able to create a patch.
10. In Wise for Windows Installer and Wise for Visual Studio .NET, start and run the Patch Wizard to create your patch. In Wise Package Studio, start and run the Patch Creation to create your patch. If you need help using this tool, press F1.
    
    The Patch Wizard/Patch Creation tool generates an .msp file, which is the patch. Before applying the .msp file to your installation, you must confirm the previous version of the application is installed.
11. Double-click the .msp file to run it and update your application.

Troubleshooting Common Issues with Patches

Sometimes implementing a patch creates a problem with your application. The problem can be caused by the .msp file itself, can exist in the previous version of the application, or can be a combination of items created by applying the patch. This section identifies the most common troubleshooting issues you might encounter and explains how to solve them.

Files are not being updated as expected

There are two explanations why your files might not update successfully. Like new installations, patches follow specific file versioning rules to determine if a file should be updated or remain as is on the destination computer. These versioning rules can create issues when patching.

• If you have versioned files, the highest version is always installed on the destination machine. The highest version either installs as part of the patch file or remains on the destination machine if the patch attempts to install a lower version than what currently exists on the destination machine. For example, if the original file on the destination computer is version 1.0 and the patch file is version 1.1, then the file is updated. But if your original file is version 1.1 and you attempt to patch it with version 1.0, the file is not updated.
• If your file is non-versioned and the modified date is later than the create date, the patch does not install the file because it would delete user customizations. For the complete set of file versioning rules, see the topic titled File Versioning Rules in the Microsoft Windows Installer SDK Help.

All files that are in both the original and upgraded .msi files must be in their original components and have matching component GUIDs. If the component GUID is not identical between the two .msi files, the patch does not install properly. This typically occurs when you remove an older version of a file from the installation and add a newer version. To solve this, modify the source path of the file rather than removing it.

Files are not being removed as expected

Files you remove during an upgrade reappear in the patch installation since they were not removed from the original installation. To remove a file during an upgrade, add an entry to the RemoveFile table. For information about populating the columns of the RemoveFile table, see the topic titled RemoveFile Table in the Windows Installer SDK Help.

You get an error message indicating the upgrade patch cannot be installed by the Windows Installer service.

This message appears if you don’t have a previous version of the software installed on the destination computer. Since .msp files only contain the differences between your current version and your previous version, key files the service needs to apply the patch are missing. To resolve this error, install the previous version of the software on the computer before applying the patch.

The message can also appear if you do not have the correct previous software version installed on your machine. When you create a patch with the Patch Wizard/Patch Creation tool, you need to specify all previous versions that the current patch can update. If you do not have one of the specified versions of the software on your machine, the patch cannot install. Verify the .msi files you selected for your previous software versions by looking at the Specify Previous version dialog in the Patch Wizard/Patch Creation tool. Select an .msi and click the Details button to verify which previous versions the patch will update.

Use the tips in this article to successfully create and apply a patch to your installation. Troubleshoot problems that arise when applying a patch by reviewing the issues and solutions listed in this article, reviewing the log file the Patch Wizard/Patch Creation tool creates, and running UpgradeSync. For additional information about updating an application using a patch, see the topic titled Patching and Upgrades in the Windows Installer SDK Help.