CodeGuru content and product recommendations are editorially independent. We may make money when you click on links to our partners. Learn More.
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.
