Using WiX to build Windows installers

All Windows applications need to be installed. Sure, you can just wrap your binaries and assets in a zip file and leave installation as an exercise for your users, but that means they’re unlikely to ever come back. That’s where the various Windows packaging and installer tools come in, giving you a way to build executables that place all the various elements of your code in the right place in a Windows install, ensuring that all the necessary dependencies are installed, and icons and shortcuts are in the start menu, ready to go.

How do you go about building an installer? Many of the tools out there take advantage of the standard Windows Installer packaging tools, but getting that configuration right can be hard, especially when you’re making packaging the final part of a CI/CD (continuous integration and continuous delivery) build process. When your code, artifacts, and dependencies change from build to build, you need a scriptable configuration environment that can be managed by your build tools, integrated into your development environment and your code repository.

The first Microsoft open source tool was for developers

That’s where WiX, the Windows Installer XML toolset, comes into play. It’s been used inside Microsoft for a long time and made history as its first open source release in 2004 using the Common Public License, eventually being managed by the Outercurve Foundation before being transferred to the .NET Foundation. Development has continued through that period, with the project leads founding FireGiant to provide commercial support and additional tools.

At its heart, WiX is XML that’s used as declarative code that’s treated as source for building installers. You can install the WiX tools in Visual Studio and write an installer alongside your application, using the same source control and build tools to ship an installable package. It’s able to do more than the basic Windows Installer, with support for application and Windows configuration and the capability to work with server tools such as IIS and SQL Server. Additionally, it can create complex setup bundles that handle dependencies and prerequisites, ensuring that your code has everything it needs to run once installed.

The current stable release of WiX is Version 3.11.2, which has been available since 2019. That gap is due to the development team focusing on a new version with a new architecture. A preview of WiX 4.0 is now available and is well worth investigating. Built on modern .NET, it’s more suitable for use in a modern CI/CD environment. Everything is run from the .NET command line, allowing you to quickly build it into scripts and actions; it works as part of an Azure DevOps pipeline or in a GitHub Action. Push a new pull request to a branch and get a ready-to-run installer.

Downloading and installing WiX

 You can download the current release of the WiX toolset from GitHub, which is where most development occurs. There are repositories for the toolset, the Visual Studio extension, and core tools that ship as part of the platform. It’s a reasonably active set of repositories, with most of the current tools in maintenance mode while much of the work goes into the upcoming WiX 4.

WiX is a .NET application, written in C#. It currently uses the .NET Framework, with the under-development WiX 4 migrating to the new .NET platform, requiring a minimum of .NET Core v3.1. The new release also brings the various WiX tools, like candle and light, into a single command-line utility. It now installs from the .NET command line as a .NET tool.

Building an installer description in WiX

For now, you’re likely to be using WiX 3.x. It’s a good way to get familiar with the underlying XML syntax used to build installers. Although there is some change between versions, using the stable release will give you an appropriate grounding and a set of installer files that can be upgraded when the new release arrives.

WiX uses XML to define the structure of an installed application, using the definitions expected by the Windows Installer. You need to start by defining the directories used by your application, working with the default Windows Program Files structure. You can create a hierarchy of directories for the files packaged with your application here, setting names as well as indicating how directories are created on disk.

Once you’ve defined your target directory, you can create an XML list of your application assets. Each file needs its own component reference, along with a GUID. GUIDs are important, as WiX uses them to manage updates. Executable components can be stored along with a checksum, which will validate files on install.

Windows Installer is designed to work with a lot of files, so you will eventually need to create a long list of components. In practice, you’ll have to automate this, either using the WiX extension in Visual Studio or having a component registry application that can generate the appropriate XML for you. This can be as simple as an Excel spreadsheet with its built-in XML tools.

Other XML elements are used to define and write registry keys, defining a root and a key, with appropriate values. Registry entries are treated as components, so they need a GUID along with their contents.

Working with the WiX Visual Studio extension

Using the Visual Studio extension can save a lot of time. You can create a new project in your solution for the installer XML. You can start with something as simple as adding a reference to an application and one line of code in your WiX project. Once built, it will create your installer, ready for use. WiX’s Visual Studio tool supports a selection of different variables that can pre-populate installer XML. Alternatively, you can use it to build your own custom tools.

One useful feature of WiX is its decompiler that can be used with any Windows Installer package. This takes your installer and produces WiX code that can then be compiled and tested. It’s a good tool to have as it can bring existing installers built from other tools into your WiX environment, ready to be used for updates and new releases.

Tools like WiX show that Microsoft and the open source community can work together to build tools that everyone can use. Obviously, there are still internal WiX versions to deal with the scale of Microsoft projects like Windows, but the public tools vastly simplify building and managing an installer. New command line–driven tools in WiX 4 (and a move to cross-platform and cross-processor .NET tools) should make it a lot easier to automate working with installers, making them the default end of a Windows application CI/CD pipeline.