Patch Authoring for MSI 3

Windows® Installer sample patching

The samples in this folder assist developers in the development of file patches and updates that can be used with Windows® Installer installation packages. The bin directory of your SDK has useful patch creation utilities and sample patch creation files (PCP files) used to create a Windows® installer patch package. A PCP file may be used with the Msimsp.exe and Patchwiz.dll utilities to generate a Windows® Installer patch package (.msp extension). Neither the sample PCP files provided in this folder, nor the patch creation tools provided in the bin directory are supported by Microsoft® Corporation. They are provided "as is" because we believe they may be useful to you.

Template.pcp

It is an empty patch creation properties file (PCP file). The PCP file is a binary database file with the same format as a Windows® Installer database (an MSI file) but uses a different database schema. Authors may create a PCP file by using a table editor such Orca to enter their information into the blank PCP database provided template.pcp. An example of the procedure is discussed in the help file "A Small Update Patching Example" in the SDK documentation. For more information about patch creation properties files see the help file "Patchwiz.dll" in the SDK documentation.

Example.pcp

This file is an example of a populated patch creation properties file (PCP file). An example of the procedure is discussed in the help file "A Small Update Patching Example" in the SDK documentation. For more information about patch creation properties files see the help file "Patchwiz.dll" in the SDK documentation.

Makecab.exe

This is a data compression tool that developers can use to make compressed cabinet files for use with Windows® Installer installations. For more information about makecab.exe see the help file "MakeCAB: A Compression and Disk Layout Tool" in the Platform SDK documentation. Windows® Installer developers must take care to properly author their installation database to match up with the files in their cabinets. For more information about how to use cabinet files with the Windows® Installer you should see the help file "Using Cabinets and Compressed Sources" in the SDK documentation. Type makcab.exe /? on a command line to display makecab.exe syntax and options.

Apatch.exe

This is a command line tool used to apply an ordinary patch file to a file. This utility is intended for use with ordinary patch files and will not work with Windows® Installer patch packages (.msp files). The utility is provided merely as an aid to development. Type apatch.exe /? on a command line to display apatch.exe syntax.

Mpatch.exe

This is a command line tool that calls mspatchc.dll to generate a regular patch file. This utility is intended for use with ordinary patch files and will not work with Windows® Installer patch packages (.msp files). The utility is provided merely as an aid to development. Type mpatch.exe /? on a command line to display apatch.exe syntax.

Mspatchc.dll

This DLL is used by mpatch.exe.

Msimsp.exe

This tool calls PatchWiz.dll to generate a Windows® Installer patch package (MSP file) by passing in a patch creation properties file (PCP file) and the path to the patch package being created. The tool can also be used to create a log file and to specify a temporary folder in which the transforms, cabinets and files used to create the patch package are saved. Msimsp.exe is the recommended method of generating a Windows® Installer patch package. For more information sees the help files "Patching" and "Msimsp.exe" in the SDK documentation. Type msimsp.exe /? on a command line to display msimsp.exe syntax and options.

Patchwiz.dll

This DLL is used by msimsp.exe. Patchwiz.dll called by msimsp.exe is the recommended method for generating Windows® Installer patch packages (.msi files). For more information see the help files "Patching" and "Patchwiz.dll" in the SDK documentation. Starting with Windows® Installer 3.0 SDK, PatchWiz helps patch authors generate sequencing information for Windows® Installer 3.0 patches. The following sections describe this new functionality of PatchWiz.

PATCHWIZ: Patch Sequencing Information Generation

Automatically Generating Sequencing Information

The sequencing information will be generated automatically and an MsiPatchSequence table will be added to the patch by default for all patches that are created using the PATCHWIZ released with Windows® Installer 3.0 SDK. To suppress the automatic population of sequencing information the property SEQUENCE_DATA_GENERATION_DISABLED should be set to 1 in the PCP file’s Properties table. In the absence of this property sequencing information is generated automatically.

Automatically Generating the PatchFamily

All unique target product codes listed in the target images of the PCP file will serve as PatchFamily values. A new row is created for each unique target product code that the target image listed in the TargetImages table corresponds to. Each of these new rows has a PatchFamily that corresponds to the unique target product code of each of the target images.

Automatically Generating the Sequence Numbers

Sequence numbers will be generated based on the highest product version that the patch targets and the UTC time when the patch was generated. This ensures an optimal behavior with applicability testing API. Note that product versions are of the format: <Product Major Version>.<Product Minor Version>.<Build Major Number>.<Build Minor Number> and a product with a version number 2.1.0.0 is higher version than a product with version number 1.2.0.0.

The sequence number will be <Product Minor Version>.<Build Major Number>.<Time Stamp 1>.<Time Stamp 2>; in other words the first field of the sequence number is the product version of the highest version of the product that the patch targets. Simlarly, the second field is the build major number of the highest version of the product that the patch targets. The two time stamp fields account for the 32 bit time stamp needed to count the seconds in UTC.

Automatically Generating the Attributes

By default, QFE (small update) patches will NOT have the msidbPatchSequenceSupersedeEarlier attribute set; whereas SP (minor update) patches will have the msidbPatchSequenceSupersedeEarlier attribute set. The assumption here is that SP will always contain fixes brought in by all the QFE that were released prior to it. If the patch authors feel otherwise, they will have the ability to control this behavior using the SEQUENCE_DATA_SUPERSEDENCE property. Patch authors can set the value of this property to 0 or 1. By setting this property in the PCP file, patch authors instruct PATCHWIZ to generate a patch that has all the rows in the MsiPatchSequence table to have the attributes column’s supersedence value set to the value specified by the SEQUENCE_DATA_SUPERSEDENCE property. Patch authors will have to manually generate the sequencing information if they want a finer control on the attributes column.

Note that the Target column will be left blank while generating sequencing information automatically.

Manually Generating Sequencing Information

MsiPatchSequence table can be populated based on the information provided in the PatchSequence table of the PCP file. If the PCP file contains the PatchSequence table, then the SEQUENCE_DATA_GENERATION_DISABLED property is not considered.

PatchSequence Table

The PatchSequence table is a new table that only PATCHWIZ shipped with Windows® Installer 3.0 SDK can recognize. It is used to generate the MsiPatchSequence table in the created patch.

Column Name | Key | Type | Nullable
PatchFamily | Yes | Identifier | No
Target | Yes | Text | Yes
Sequence | No | Version | Yes
Supersede | No | Integer | Yes

Columns

PatchFamily

The identifier which indicates one of the sequence families to which this patch belongs to. Together with the Target value, the PatchFamily value defines the primary key of the table. A patch which belongs to multiple sequence families or has different sequence behavior based on target product code will have one row for each distinct pairing. This value is used to populate the PatchFamily column of the MsiPatchSequence table in the patch.

Target

The Target column is used to determine the product code filtering for the PatchFamily. A NULL value in this column indicates that this PatchFamily applies to all targets of the patch. If the column contains a foreign key to TargetImages table, the product code of the specified image is automatically retrieved and used to populate the product code value of the MsiPatchSequence row. If the value is a GUID, the specified GUID is used in the MsiPatchSequence row. If the data does not meet any of the above criteria, the patch creation will fail.

Sequence

The value in the Sequence column is used to populate the Sequence column of the MsiPatchSequence table in the new patch file. If the value is NULL, a sequence number is automatically generated the same way while generating automatic sequencing information.

Supersede

A non-NULL value indicates that this patch supersedes earlier QFE patches in this family. This value is used to set the Attributes column of the row in the MsiPatchSequence table of the new patch file.