Skip to Content

WixUI extensibility

Posted on

There’s been an increase lately in the number of questions on the wix-users mailing list and elsewhere about extending the WixUI dialog library.

WixUI extensibility past

In WiX v2, WixUI is a simple .wixlib of UI authoring fragments. Navigation between pages of the wizard is handled by properties that contain the previous and next dialog names for each dialog. You can extend the stock dialog sets by inserting custom dialogs into the wizard sequence; set the back and next properties for the dialogs before and after the one you’re inserting. To customize one of the stock dialogs always requires you to copy that dialog’s source file and modify it. You also need to copy the fragment containing the properties for the dialog set; otherwise you’d end up with duplicate properties.

WixUI extensibility present

In WiX v3, WixUI is built as an extension. All the standard dialog fragments, bitmaps, and custom action DLL (to print the EULA) are embedded in it. WixUI v3 takes advantage of several features added to WiX v3:

  • WiX variables to point to bitmaps and the license RTF file, to override those included in the extension.
  • “Floating” Publish elements move dialog behavior out of the dialog fragments and into the dialog set fragment. That makes it easier to reuse a dialog and still give it different behavior.

Adding a dialog into the wizard sequence means copying the dialog set fragment and changing the floating Publish elements for the existing dialogs and adding new ones for the new dialog.

It’s possible to more easily re-use the stock dialogs but still not possible to modify their appearance. That still requires copying the dialog into your own project. You can still refer to the dialogs you don’t modify from their copies in WixUIExtension.dll and the linker will find them there.

Compare and contrast

If you’ve used one of several “name-brand setup authoring tools” (hereinafter NBSATs), you’ve seen a very different approach:

  1. Create a new project.
  2. See shiny, happy dialogs listed in your NBSAT IDE.
  3. Edit the aforementioned dialogs to your heart’s content.

In general, what’s happening is that the NBSAT is copying its set of dialogs directly into your NBSAT project file. As the NBSAT IDE is the preferred (or only) way of seeing the project, it can hide all those dialogs until you need to edit them.

The WixUI model is different: You don’t get copies of the WixUI dialogs; when you build your project with a UIRef element to a WixUI dialog set, the WiX linker is pulling those dialogs directly from the .wixlib (that in WiX v3 is embedded in WixUIExtension.dll).

WiX could offer the same always-copy model NBSATs use (via a Votive template, for example). The downside is that you’d have all this UI code in your project. Lacking (for the moment) a WiX IDE, there’s no way to hide any code in your project file: It’s always visible in all its XML angle-bracket glory. Keeping the UI authoring in a library keeps it hidden, at the cost of more painful customization.

WixUI extensibility future

That’s another article, coming soon.