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.