Creating Installer Patches with MSI 3.0

Summary

Today, in the world of software development, it is common to have patch releases due to various reasons. This article intends to make this process easier by explaining the steps that would be needed to create a patch using MSI 3.0. The complete example is available in the downloadable MSIPatchExample.zip file.

Introduction

It's not uncommon for development teams to request a patch release immediately after a major release. In large development environments, immediately after a major release there could be an immediate fix for a problem that might have arisen in the code already in production environment. But, this does not need a major release because the changes are minor but critical for the application. This is when a patch release is needed. The process of creating a patch with MSI 3.0 is pretty complicated and not well documented. Additionally, VS.NET does not support the creating of these patches. Therefore, this article goes through the steps of creating a patch release.

MSI 3.0

You would need platform SDK. If you don't have platform SDK, you can install it from this location http://www.microsoft.com/msdownload/platformsdk/sdkupdate/. This download contains MSI 3.0. If you have an older version of the SDK, you would need MSI 3.0.

MSI 3.0 is an application installation and configuration tool that aids in creating a Windows installer. MSI 3.0 and can be downloaded from here.

Process

To create the patch, there are several steps to be followed. This article walks you through the step of creating it by using an example. First, create a Windows forms application using VS.NET as shown in Figure 1.

Figure 1: Application screen in the first release

The screen is a simple screen where users have to enter their name and then search for information related to the user. Create a Windows installer for this application and call it UserInfoSetup. The properties of UserInfoSetup would look as shown in Figure 2. Remember the Package files option should be "As loose uncompressed file" as shown in Figure 2. Now, build the application and install it. Run the application; you should be able to see your screen as seen in Figure 1.

Figure 2: Properties of the installer.

Now, save everything in this release folder to a new folder called FirstRelease. It's time for the patch because the users have requested to change the label name to "Enter Last Name" instead of "Enter Name" as shown in Figure 3. So, change the name and release the application as a patch release.

Figure 3: Application screen after the requested changes.

Before creating the patch release, you would need to modify the properties of the setup project. Change the version to 1.1.0 as shown in Figure 4.

Figure 4: Properties of the setup folder as seen in VS.NET.

On changing the version, you would be prompted to change the product code and package code. These guids need to be changed when creating a patch; otherwise, an error would be thrown stating the GUID is not unique while creating the patch. The changed property would look as shown in Figure 5. Build the solution and copy the upgraded setup to a new folder and call it SecondRelease. For this example, also create a patch folder.

Figure 5: Properties of the setup folder after the change.

Before you create the patch, make sure MSI 3.0 is downloaded and installed on the machine. You would also need ORCA.exe, which is available with the installation of Platform SDK. On installation of Platform SDK, ORCA.msi is available. Install this one to the machine.

After the MSI 3.0 is installed, go to C:\Program Files\Microsoft SDK\Samples\sysmgmt\msi\Patching on your machine. This folder contains all the necessary tools to create a patch. Copy the TEMPLATE.PCP to the newly created patch folder. The Template.pcp file is given primarily for the purpose of using as a starting point for creating a patch. Rename it to MyNewPatch.pcp. Now, open this MyNewPatch.pcp with ORCA as shown in Figure 6.

Figure 6: Tables as seen in ORCA.

This shows a series of tables that would need to be filled. Go through each table and fill the properties. The first table that you see is ExternalFiles. Add a row to this table. There are several properties of the table that need to be filled. The first property is the family. It's the table key. Provide the table key name as LastName.

Another property is the FilePath. This is the actual location of the application file. In the example, it's located in the folder called SecondRelease. The FTK property can be any string and the order property can be 1.

Next, look at the Properties table where the patchGuid can be changed if you need and is the recommended approach whenever a new patch is created. The patchOutputPath is where the patch would be created. In the example, it's in the patch folder. Create a new property called MinimumRequiredMsiVersion in the table and set its value to 200. Setting this to 200 makes it mandatory to have MSI installer 2.0 and above on the machine. This also makes it easier in creating the patch process by avoiding some of the entries in the ImageFamilies table. Leave all other properties to the default.

The next table is the TargetImages. Here, the first property is Target; this can be any string. The next is the MsiPath, the location of the first msi. It can also be a relative position to the PCP file. In the example, this location would be the FirstRelease folder. The Upgraded property can be any string; call it "FirstUpgrade". Order is 1 and IgnoreMissingSrcFile is 0. Now, you can fill the UpgradedImages table. The upgraded row should have the same value as the upgraded property in the TargetImages table. In this example, it's "FirstUpgrade". The MSIPath property contains the path to the new upgraded MSI. In the sample, it would be the SecondRelease folder. The next property is the family; it should be the same as the value of the property for family in the ExternalFiles table. In the example, it is "LastName".

Another table that needs to be filled is the ImageFamilies table where the Family property is the same as the previous table.

MyNewPatch.pcp tables are populated with the minimal required values. Save this file to the patch folder and run the following on the command line.

MsiMsp.exe -s MyNewPatch.PCP
           -p UserInformationPatch.msp
           -l MyNewPatch.log

The MSP file would be the MSI patch file created. This also creates the log file that would show the success or failure and the error that occurred in creating the patch.

This creates the patch and can be installed as an upgrade to the previous release. Now, on running the application, you would see the changes as requested.

Conclusion

Creating the patch is not an easy process, but once created, a patch release can be done; this was not available earlier. This makes it easier on the development teams as well as release managers if they need to make a hot fix immediately after a release.



Downloads

Comments

  • Working perfect , just need to add a step between

    Posted by sonawane.lalit on 01/17/2012 12:02pm

    I just add two steps and it will work fine , 1) change the assembly version of application code. 2)In setup property pages click configuration manager and check all check boxes (by default only setup project is checked

    Reply
  • Patch Creation Failed

    Posted by etprakash on 03/09/2011 12:57am

    ***** Log starting: 2011-03-09 10:27:53 *****
    
      INFO: Using Pcp Path: E:\TestPatch\Patch\TestPatchFile.PCP.
      INFO: Using Temporary Directory: C:\DOCUME~1\ADMINI~1.CIS\LOCALS~1\Temp\~pcw_tmp.tmp.
      INFO: Passed all of the main control parameter validation to PatchWiz, now calling the next 5 phases.
      INFO: Phase I:	Entered validation and processing phase.
      INFO: 		Validation of Pcp.
      INFO: 		MinimumRequiredMsiVersion is 200.
      INFO: 		SEQUENCE_DATA_GENERATION_DISABLED is 0.
      INFO: 		ListOfPatchGUIDsToReplace is .
      INFO: 		ListOfTargetProductCodes is *.
      INFO: 		MsiFileToUseToCreatePatchTables is .
      INFO: 		PatchGUID is {999D5586-6DBA-430E-BAE9-FE2E0920DEF7}.
      INFO: 		PatchOutputPath is E:\TestPatch\Patch\TestPatchFile.msp.
      INFO: 		PatchSourceList is PatchSourceList.
      INFO: 		PATCH_CACHE_DIR is .
      INFO: 		AllowDualPatch is 0.
      INFO: 		AllowProductCodeMismatches is 1.
      INFO: 		AllowProductVersionMajorMismatches is 1.
      INFO: 		ApiPatchingSymbolFlags is 0.
      INFO: 		DontRemoveTempFolderWhenFinished is 1.
      INFO: 		IncludeWholeFilesOnly is 0.
      INFO: 		PATCH_CACHE_ENABLED is 0.
      INFO: 		OptimizePatchSizeForLargeFiles is 0.
      INFO: 		META_DATA_GENERATION_DISABLED is 0.
      INFO: 		TrustMsi is 0.
      INFO: 		AllowLaxValidationFlags is 0.
      ERROR: UpgradedImages.MsiPath 'E:\TestPatch\SecondRelease' does not exist.
      ERROR: 	The Last Error Received is: 0
      ERROR: Internal PatchWiz Error occurred.
      ERROR: 	The Last Error Received is: -1072803564

    Reply
  • Patch Creation Failed

    Posted by etprakash on 03/09/2011 12:13am

    ***** Log starting: 2011-03-08 17:00:13 *****
    
      INFO: Using Pcp Path: E:\TP\Others\MyNewPatch.pcp.
      INFO: Using Temporary Directory: C:\DOCUME~1\C152~1.CIN\LOCALS~1\Temp\~pcw_tmp.tmp.
      INFO: Passed all of the main control parameter validation to PatchWiz, now calling the next 5 phases.
      INFO: Phase I:	Entered validation and processing phase.
      INFO: 		Validation of Pcp.
      INFO: 		MinimumRequiredMsiVersion is 100.
      INFO: 		SEQUENCE_DATA_GENERATION_DISABLED is 0.
      INFO: 		ListOfPatchGUIDsToReplace is .
      INFO: 		ListOfTargetProductCodes is *.
      INFO: 		MsiFileToUseToCreatePatchTables is .
      INFO: 		PatchGUID is {00000001-0003-0000-0000-123456789ABC}.
      INFO: 		PatchOutputPath is E:\TP\Others\UserInformationPatch.msp.
      INFO: 		PatchSourceList is PatchSourceList.
      INFO: 		PATCH_CACHE_DIR is .
      INFO: 		AllowDualPatch is 0.
      INFO: 		AllowProductCodeMismatches is 1.
      INFO: 		AllowProductVersionMajorMismatches is 1.
      INFO: 		ApiPatchingSymbolFlags is 0.
      INFO: 		DontRemoveTempFolderWhenFinished is 1.
      INFO: 		IncludeWholeFilesOnly is 0.
      INFO: 		PATCH_CACHE_ENABLED is 0.
      INFO: 		OptimizePatchSizeForLargeFiles is 0.
      INFO: 		META_DATA_GENERATION_DISABLED is 0.
      INFO: 		TrustMsi is 0.
      INFO: 		AllowLaxValidationFlags is 0.
      ERROR: Since MSI 3.0 will block installation of major upgrade patches with sequencing information, creation of such patches is blocked.
      ERROR: 	The Last Error Received is: 0
      ERROR: Internal PatchWiz Error occurred.
      ERROR: 	The Last Error Received is: -1072803454

    Reply
  • Patch not overwriting already installed exe

    Posted by SandeepV on 11/30/2006 07:05am

    I tried to install the first release and then patch as given in the attached zip file and follwed the procedure as explained. But the patch is not overwriting the already installed "UserInformation.exe" of first release. But if i tried to install "UserInformation.exe" on to some other location other than where it is already installed through patch it is installing the new "UserInformation.exe" correctly. Please suggest where I am going wrong. Thanks. Sandeep sandeepv@infotechsw.com

    Reply
  • Automatic tool to do this process - found one

    Posted by ebola on 06/13/2006 08:09am

    Found one. In case anyone else is interested: htt://www.msipatchbuilder.com

    Reply
  • Automatic tool to do this process

    Posted by ebola on 06/12/2006 11:30am

    Excellent article and clearly explained. Are their any tools to automatic this process as it takes quite a long time to do manually and errors occur?

    Reply
  • failed to create patch

    Posted by haninaya on 08/29/2005 06:05am

    Hello, I followed your steps to create a patch, but a the last step, in the ImageFamilies table of my orca, three properties are required : MediaDiskId, MediaSrcPropName, FileSequenceStart. What does these properties represent ? Thx

    Reply
Leave a Comment
  • Your email address will not be published. All fields are required.

Top White Papers and Webcasts

  • Live Event Date: May 7, 2014 @ 1:00 p.m. ET / 10:00 a.m. PT This eSeminar will explore three popular games engines and how they empower developers to create exciting, graphically rich, and high-performance games for Android® on Intel® Architecture. Join us for a deep dive as experts describe the features, tools, and common challenges using Marmalade, App Game Kit, and Havok game engines, as well as a discussion of the pros and cons of each engine and how they fit into your development …

  • Instead of only managing projects organizations do need to manage value! "Doing the right things" and "doing things right" are the essential ingredients for successful software and systems delivery. Unfortunately, with distributed delivery spanning multiple disciplines, geographies and time zones, many organizations struggle with teams working in silos, broken lines of communication, lack of collaboration, inadequate traceability, and poor project visibility. This often results in organizations "doing the …

Most Popular Programming Stories

More for Developers

Latest Developer Headlines

RSS Feeds