WiX: Integrating into the continuous build

I've been working on a WiX installer recently and I was asked to integrate it into the project's continuous build process.  This turned out to be surprisingly easy.

Early on in the development, I decided to use WiX version 3.  It is nicely integrated with Visual Studio and has some great property windows for controlling compiler and linker behaviour.  So my development environment for WiX looks like this and I can create my MSI directly from the Build menu (or Ctrl-Shift-B, as I prefer):


The other benefit of WiX 3 is that the main project file (xxx.wixproj) is now actually an MSBuild script (this is a change to prior versions). 

Now our continuous build has CruiseControl.Net calling an MSBuild script (similar to the setup I described in a previous post). This means that once you got the latest binaries and files into the correct folders, getting the WiX project to build is as simple as:

<MSBuild Projects="$(InstallerDirectory)\Installer.wixproj" Targets="Build"/>

How cool is that?

WiX: A not-quite-so-gentle introduction

Previously I gave a high-level introduction to the WiX and MSI technologies.  I'm going to dig a little bit deeper here and get a bit closer to the nuts of bolts of these technologies.  Note that I'm not intending to give you an introduction to the details of writing WiX installers, the tutorial I linked to previously (which is also linked in from the main WiX site) does that quite well enough.  I do think that there is some context you will need before you start that tutorial and that's what I'm aiming to give you here.

Features and Components

We are all used to seeing screens like this during an installation:


These are features, in MSI (and WiX) terminology.  A feature consists of a number of components and very little else.  Components can be used by more than one feature.

A component is uniquely identified by a GUID and consists of a number of resources that get installed (or uninstalled) together.  The list of resources that Windows Installer can deal with natively is:

Files and folders Registry keys   Environment variables
Entries in an INI file ODBC drivers and data sources   Windows services
Shortcuts Assemblies  

This is clearly a limited list - missing resource types include X.509 certificates, web sites, SQL databases, etc, etc.  Fortunately Windows Installer offers an extensibility mechanism.

Custom Actions

Custom actions are the way that Windows Installer let's MSIs do things other than just installing the above resource types.  There are a variety of types of custom actions and these all need to be explicitly ordered and scheduled by the MSI developer.  The main custom actions that I've used consist of running an executable, running some code in-process (i.e. via a DLL which is embedded in the MSI) and do some manipulation of properties.

Somebody authoring an MSI package is most likely using some environment or other (e.g. WiX) and this environment will typically provide some custom actions.  Cleverly, some of these custom actions look like additional resource types to the MSI developer.  For instance, WiX itself provides facilities to install and uninstall the following:

COM and DCOM components X.509 certificates Device drivers
Event logs File shares SQL databases
SQL scripts Users and groups IIS web sites
IIS virtual directories Entries in XML files Visual Studio help files
COM+ applications MSMQ queues  

Custom actions are not intrinsically linked to components or features.  This means that you don't have a convenient event to hook into so that, say, you can run a particular executable once some files have been installed.  Instead, all custom actions can have conditions attached to them which detail whether or not the custom action should execute.

So if you want an executable to run once some files have been copied, you need to set a condition on the custom action which runs the executable.  This condition would ensure that the custom action executed only when the particular component (or feature) containing the files was being installed.  You would also need to schedule the custom action so that it occurred after the installation of the files.

Note that it's rare that you will author just one custom action to modify system state.  Once you have done this, you need to give some thought to rolling back the action if the install fails, as well as uninstalling the action (strictly speaking you should also worry about rolling back the uninstall!).  So you'll usually write them in pairs or triples.


Properties are just variables within your MSI package.  They can have a default value or a value can be supplied on the command line by the user.  Initial values can also be obtained by scanning the file system (e.g. to look for a particular file or directory), by using environment variables or by scanning the registry.  You can also build up property values from other properties, but you need to use a custom action to do this.

November 15 2006

WiX: A gentle introduction

Currently I'm doing work using the WiX toolset.  There doesn't seem to be a lot of documentation around the web, so I thought I post my various travails in getting it to do what I want.  But first an introduction to it and some links to useful resources:

What is WiX?

WiX stands for Windows Installer XML (don't ask me why they use a small i).  It was the first open source project released by Microsoft.  The main site is at http://wix.sourceforge.net/ and to quote from that:

The Windows Installer XML (WiX) is a toolset that builds Windows installation packages from XML source code.

So it's basically an open source way of building MSI files.

What's an MSI file?

MSI stands for Microsoft Installer (they used a big i this time), but the question really isn't as silly as you may think.  You see, an MSI file is not a program.  That really is worth repeating.  An MSI file is not an executable, it is a database.  It has tables with particular schemas (as well as your own custom tables) and Windows Installer uses the information in these tables to drive the installation of an application.  The list of MSI tables can be found at http://msdn.microsoft.com/library/en-us/msi/setup/database_tables.asp and if you're very interested you can download the Windows Platform SDK, get a tool called Orca  (part of the Windows Installer SDK).  This allows you to view and edit the contents of any MSI file and it looks like this:


It's worth stressing that this database includes all the dialog windows that drive the installation process, the files for the actual installation, instructions on what to put where and many other things. 

So what does WiX do then?

In a nutshell, WiX converts XML files into MSI databases.

So the XML must be quite complicated then ...

Well I don't find it very intuitive.  Things are getting easier as the WiX toolset matures (version 3.0 includes some quite nifty Visual Studio integration, for example).  There is also the WixEdit project on Sourceforge, which offers GUI screens for editing the WiX XML file - I discovered this a bit too late to use it for my current work, but it looks worthwhile.

Where can I find more information?

Try the following:

November 10 2006
Older Posts