Quick-Start Guide to Creating a Windows Installer

It’s one thing to develop and test a Windows application; it’s quite another to bundle it up into a nice executable that installs correctly on all the different Windows versions that you need to support. I’d like to guide you through the process that I wish I had when I was creating my first installer.

Step 1 – Use your bare hands.

Start by taking your target directory (the one containing your compiled .exe and a bunch of .dll files) and plopping the whole thing onto a Windows machine. Then, manually install any prerequisites, like the particular version of the .NET framework that the app requires. It’s helpful to perform this step on an older platform that’s more likely to contain compatibility issues, e.g. Windows XP.

Now run the executable directly, and make sure it works. If there are problems, the machine may still be missing prerequisites. Double-check that the platform (x86 vs. x64) and .NET framework target of your build match up with the configuration of the machine you’re testing on. An installer won’t fix problems encountered here, so be sure to fix any issues before moving on.

Step 2 – Build it.

Next, we create an actual installer. Visual Studio lets us do this in two easy steps:

  1. Add a new “Visual Studio Installer/Setup Project” to your current solution.
  2. View the file system settings of the new project. Add a new Project Output to the Application Folder, and set it to be the Primary Output of your main project.

That alone is sufficient to build an MSI installer that will copy your project’s output onto the target machine. Other useful settings include adding shortcuts to the Start Menu/desktop, customizing registry settings, and configuring whether the installation applies to all users or not.

Caveat: Visual Studio versions after 2010 seem to build MSIs that choke on Windows XP. No matter the configuration, my installer failed for me on XP with an “installation interrupted” message. The unfortunate workaround involves copying a dll from a Visual Studio 2010 installation over to the newer version’s directory.

An alternative to Visual Studio is the highly configurable WiX Toolset. With WiX, you specify filenames, registry keys, and other installation information through XML. WiX’s candle and light tools then compile and link that information into an MSI file.

One difficulty I had was that WiX requires every file involved in the installation to be individually specified in the XML. It’s not possible to simply include the entire directory. This is by design. It is possible, however, to automatically generate the XML for a large number of files using another WiX tool called heat.

Step 3 – Bundle it all together.

At this point, we have an MSI that installs our application. In order to have a seamless user experience, we need to bundle that installer along with all of its prerequisites. It’s not possible to add everything to a single MSI file, but with WiX we can write a bootstrapper that chains multiple installation packages together.

In Visual Studio, we can first install the “WiX Toolset” extension and then add a new project to our solution of type “Windows Installer XML/Bootstrapper Project”. Inside the new project, we need to add our chained packages to the auto-generated Bundle.wxs file:

https://gist.github.com/benash/4ec9599c4f00e744f131

The easiest way to add installation items to our chain is to download the needed .msi/.exe files to our project and link to them statically. The downside of this approach is that the resulting bootstrapper may be enormous.

Caveat: For some reason, Windows 7 requires .NET to be installed by enabling it as a “Windows feature”. Running a .NET MSI on Windows 7 will fail. To work around the issue, we can enable the feature by using Wix to execute dism.exe.

Automatically downloading packages

The other option is to configure our bootstrapper to download and install its own packages. To do this, we need to define our own package group. WiX documents this element thoroughly, but here’s a summary of the information that we’ll need to add:

  • the remote filename and download URL
  • the hash and certificate details of the remote payload (This can be easily generated using the heat tool.)
  • when to install the package, e.g. for a 64-bit package, only if the machine is 64-bit

If we need our bootstrapper to download and install .NET 4.0 or 4.5, we can save some work by using the WixNetfxExtension, which contains some predefined package groups. E.g. adding <PackageGroupRef Id="NetFx40Web"/> to our chain will bundle .NET 4.0.

After some work, we might come up with this for .NET 2.0:

https://gist.github.com/benash/d5b49d71b0e264cfdcc2