Learning WiX from ground up

Summary: Reference guide for beginners.

This is post #3 of the six-part Learning WiX series. For other topics, see:

Table of contents

1. Background (why WiX?)
2. Introduction (answers to common questions)
3. Getting started (references and tutorials)
4. How-to's and missing links
5. Slides and demo projects
6. Improved demo projects (32- and 64-bit installers)

So you decided to create your first setup package using Window Installer XML (WiX). Where do you start? And how much do you need to know about WiX and Windows Installer (MSI) to build a working deployment package?

The answer to the second question is: it depends. Well... sort of. Before you begin, you definitely need to know the fundamentals of the Windows Installer (MSI) technology, such as:

• The overall structure of an MSI package (MSI database)
• The difference between packages, features, components, and deployment items (files, registry keys, shortcuts, etc)
• Custom actions (CAs) and how they are used
• Upgrade types (minor vs. major upgrade)
• Merge modules

You don't need the in-depth knowledge, but at the very least, you need to understand the terminology (check the Wikipedia overview and MSI Basics). You may need to learn more to implement such complex features as program shortcuts (yes, shortcuts are complex in Windows Installer), but you will be able to learn additional concepts as you go.

To get started, install the current version of WiX Toolset from:

• Wix Toolset Codeplex Distribution

You can download a beta version of the upcoming release or an older version of WiX Toolset from SourceForge.

I assume that you will be using Visual Studio to develop setup programs. WiX Toolset includes a Visual Studio add-on, Votive, that enables WiX integration with the Visual Studio IDE. After installing WiX Toolset, make sure that WiX project templates appear in the New Project dialog box:

At this point, you can create a WiX project, but when you open the auto-generated WiX source file, you'll realize that you have no idea what to do with it. This is where a tutorial can help.

The WiX Toolset's help file is a good place to start (by default, the help file is installed to C:\Program Files\Windows Installer XML v3\doc\wix.chm; you can find a shortcut to the help document under the WiX program group in the Start menu; the help file can be also viewed online). You don't need to read it all; the first few chapters and how-to articles give you a basic idea of what you need to do to get a functional setup project.

To get more in-depth understanding of WiX, check out more advanced tutorials. The ones I found most helpful include:

• WiX Tutorial by Gábor DEÁK JAHN, Tramontána (official WiX tutorial; a lot of good info, but can be overwhelming)
• Yet Another WiX Tutorial by Rennie Petersen (addresses fewer topics, but in more depth)
• From MSI to WiX by Alex Shevchuk (excellent information helping understand both MSI and WiX)
• WiX Tutorial by r0k0t (awkward format, but great info presented as lessons)
• WiX Wiki (I din't use it much, but noticed a few articles that could be helpful)
• WiX tricks and tips (wiki post at StackOverflow with many good suggestions)
• Creating an installer using Wix v3.0, Votive, and Visual Studio 2005/2008 (simple demo; see also Part 2: the GUI)

There is also a very insightful presentation by Jeffrey Sharp (with slides and video):

• Talk: Setup With Windows Installer and WiX

The following MSDN article by Ibrahim Hashimi is a bit out-of-date and has a slightly different focus (build automation), but it still offers a pretty decent overview of WiX:

• Automate Releases With MSBuild And Windows Installer XML

Nick Ramirez just published an excellent book that covers a lot of WiX and Windows Installer (MSI) topics (see my Amazon review):

• WiX: A Developer's Guide to Windows Installer XML
  

You can read the Getting Started and Adding a User Interface chapters online.

And here is a list of tools that you may want to check out:

• SharpSetup creates bootstrapper and GUI for your WiX installer in C# and WinForms.
• Wix# (WiXSharp) builds MSI packages or WiX source code from C# code.
• IsWix (Industrial Strength Windows Installer XML) is a document editor that enables non-setup developers to collaborate with setup developers using WiX projects.
• WixEdit is an editor for XML source files for the Windows Installer XML (WiX) toolset to build MSI and MSM setup packages.

After you feel more comfortable with WiX basics (deploying files, etc), your next challenge will be implementing slightly less obvious operations (registering COM objects, creating shortcuts, using custom actions, etc) that are either not covered in the help file and popular tutorials or covered incompletely. In the next post, I will include the list of references to the how-to articles that I found most helpful.