Friday, April 27, 2007

WiX: PatchFamily patch filtering


Using the Patch system in WiX 3.0 allows you to select which differences between 2 builds you want to ship. By default, all the changes will go into a patch, but sometimes people want to ship a targeted update to fix a security issue or major customer problem. This can be done using the PatchFamily concept built into WiX.

A patch family has 2 meanings in this context, it specifies which changes you would like in any given patch, and also provides a mechanism for supercedence and dependency tracking. I'm not going to get into supercedence here other than to say that for each patch family in a patch will get an entry in the MsiPatchSequence table.

The PatchFamily element is a child of the Patch element. You can have as many PatchFamily elements in a Patch as you want. Under a PatchFamily element, there is a set of Reference elements that can be used to pull various items into your patch. Just as in your product authoring, referencing anything in a Fragment will result in that entire fragment being pulled in. WiX will handle file and media sequencing as well as the Sequence tables for you.


This PatchFamily would select the Fragment that contains the Component "MyComponent" and add it to the patch.

<PatchFamily Id="MyPatchFamily" supercede="yes">
    <ComponentRef "MyComponent" />

One thing to note is that there are rules about patch families. Once you ship a patch family, you must keep its references the same or add to it (grow it) but never remove items from it. All items in your product must be a part of only one patch family. When you change the build that you are targeting (re-baseline), patch families start over so you can change the contents and asociations at this time.

WiX: Functional Preprocessing

The preprocessor in WiX has a new feature called Functional Preprocessing. It is a way for WiX users to define functions that they can use in their authoring to dynamically fill in content.

 Most people who use WiX are familiar with preprocessor variables which look like:


 The preprocessor now has support for functions in addition to variables which look like:


While there have been no additions as of yet to the standard WiX preprocessor function library many functions have been implemented and are being used in people's preprocessor extensions. In an extension you tell the preprocessor that you would like to have all functions with a specific qualifier be handled by your extension.


Say you want to keep track of all of your component GUID's in a single file. The file has 4 pieces of data for each GUID. Id, Language, Architecture, and of course the GUID.

MyComponentId, English, Intel, 365453-34235-32525-23325345223

If you implement a preprocessor extension to handle "guid" functions and define a function called "GetGuid" that takes 3 arguments you could represent the guid in your authoring as:


This function would be replaced in your authoring with "365453-34235-32525-23325345223".
 There are a lot of possible uses of this type of functionality. I'd love to hear how other people use it.

This was originally posted here and may have additional comments.

WiX: Building a Patch using the new Patch Building System - Part I

A new patch building system has been built into WiX 3.0. The purpose of this post is to describe, at a very high level, the process of using this new system.
1. Build and ship your product using WiX v3.0. (Candle, Light)
2. Make changes to your product and build again. (Candle, Light)
4. Produce a transform based on your baseline and upgrade build. (Torch)
3. Author and build your patch. (Candle, Light, Pyro)
This system will allow you to build patches that apply to multiple products as well as multiple versions of the same product.

Building your Product (the one you ship is called your baseline)
The entire system is based on using the WiX XML representations of your product. Because of this, the process you use to build may need to change slightly. When building your product you will want to make 2 seperate calls to Light. The first call will be to link the product and create a WixMsi using the 'xo' command line option. The second call to Light will pass the WixMsi back into Light to Bind it into a Windows Installer Database.
When calling Light the first time, a set of flags are required to be passed on the command line in order to make a patchable WixMsi. 'xo', 'sdut', and 'tsa'. This tells Light to output the linked XML in WixMsi format, keep all unreal table information, and to preserve/auto-generate section id's.

Building your Upgrade 
This build represents the result you want on the target machine when your patch is applied to the Baseline build.
When you need to ship a patch or update to your customers, you need to make the changes to your product and build the product with all the changes the same way you built the baseline. This build is called your Upgrade build.

Building a Transform
To build a transform you simply need to call Torch with the two WixMsi's from your Baseline and Upgrade builds. This will produce a WixMst that represents the difference between your two builds.
When calling Torch you need to use a certain set of command line options. 'xi', 'xo', and 'p'. This means, you are giving xml inputs, you want an XML output, and you want all information preserved in the WixMst even if it hasnt changed.

Build your Patch
I will not go into all the details of how to author your patch. This is fairly well documented in the WiX.chm help file. I will also follow up on this in a later post.
The first step once your patch is authored is to build the patch using Candle and Light the same way you built your product. The result of calling Light with patch authoring is always a WixMsp.

Next, you will need to call Pyro with your WixMsp and your WixMst(s). A WixMst is passed on the pyro command line using the 't' option. The 't' option requires two inputs, the baseline identifier to tie the transform to and the path to the WixMst. The baseline identifier needs to be the same one you tied to a Media element in your Patch authoring.

 This system is fairly new and a large effort is currently being made to stabilize this system. Support for binary delta patching is also something that is coming down the road using this system. If you want to use this system in the future, the first step will be to start building your product using the process I documented above where you break the call to Light into 2 seperate steps.

This was originally posted here and may have additional comments.