Merlinia logo
Yet Another WiX Tutorial - Part 0 - Introduction

Introduction to this tutorial

These notes describe how to create simple MSI packages using WiX 2.0 and SharpDevelop 2.1. The level of sophistication of these MSI packages is very low - no really advanced topics are covered in this tutorial.

The basis for this tutorial was a real-life project, the creation of new distribution files for the Merlinia Assistance product. (For more information see here: http://www.merlinia.com/enu/Assistance.htm)

We had previously used Wise for Windows Installer for this. Switching to WiX gave us a more hands-on feeling, a feeling that we were more in control of the MSI packages we produced. It also allowed us to modify the user interface (UI) and create our own dialog boxes, and made it easy to completely localize the installation experience for our customers. (Localization is important for us as a European company.)

 

Three MSI packages

The Merlinia Assistance product consists of three "subproducts": The Server, the Client (and Screensaver), and the Admin program.

(In this tutorial I use the word "subproduct" to talk about the part of our product that is packaged as a single MSI file. I.e., one subproduct = one MSI file.)

In this tutorial we will start with the Admin subproduct, as it is a very simple installation scenario. Then we will move on to the Client installation, which is more complicated, making use of the "features" facility. Finally, a few notes about the Server installation, which is very simple, but somewhat different from typical programs.

 

Further reading

For more information see the very comprehensive WiX tutorial that can be found on the Internet at this address:
http://www.tramontana.co.hu/wix/

There is also a tutorial about creating WiX projects under SharpDevelop here:
http://community.SharpDevelop.net/blogs/mattward/archive/2007/01/08/CreatingAnInstallerWithSharpDevelop.aspx

(Some parts of this tutorial are based on the above two tutorials. In other words, I stole some of this material from those two authors. :-)

If you've installed SharpDevelop in the standard way there is a WiX Help file here:
C:\Program Files\SharpDevelop\2.1\bin\Tools\Wix\doc\Wix.chm

Alternatively, if you've installed WiX 2.0 itself in the standard way the Help file is here:
C:\Program Files\Windows Installer XML\doc\WiX.chm

There is an official "WiX Wiki" here: http://www.wixwiki.com/

Another Wiki about WiX: http://www.mindcapers.com/wiki/WiX

A possible place to find answers about WiX is the user's forum:
http://www.nabble.com/wix-users-f4470.html

WiX is based on the Microsoft Windows Installer, which is documented here:
http://msdn2.microsoft.com/en-us/library/aa372866.aspx

(This material is very comprehensive and not particularly user-friendly. Unfortunately, it is very important to understand how Windows Installer works to properly use WiX - or any other install product based on Windows Installer.)

 

Creating WiX projects

All input to WiX is in XML format. (Except for the program-related files, of course.)

The primary input file is a WXS file, for example "Assistance Admin.wxs".

It is possible to create these files in Notepad or, via an interface called Votive, in Visual Studio 2005. But I've chosen to use SharpDevelop 2.1 which has some WiX integration built in.

The advantage of using SharpDevelop is that it's easy to run WiX, which is a set of command-line programs, without having to constantly switch between the editor and the command-line environment.

For the time being I've decided to keep the WiX projects separate from the product build projects. Later it may turn out to be smarter to have C# and WiX projects combined within the same "solution", so the WiX project is more closely integrated with the program development. (This integration, and the idea of getting the developers of the program code to also develop the setup project, is recommended by those who apparently know what is best.)

NB. Note that WiX input is case-sensitive. Tag names start with capitals, i.e., <Component>, not <component>.

 

The product codes (GUID codes)

My understanding of product codes or Globally Unique Identifiers (GUIDs) is still quite limited, despite my attempts to learn more about this subject.

There is more information about these codes and why they are important here:
http://www.tramontana.co.hu/wix/lesson4.php
http://msdn2.microsoft.com/en-us/library/aa370579.aspx

My recommendation is that if you are switching from a previous install product (InstallShield, Wise, etc.) to WiX, then the simplest strategy is to advise your customers that they should manually uninstall the previous version of your program before installing the new MSI made with WiX.

Alternatively, you can make your new version look like a "major upgrade" by specifying the same UpgradeCode as was found in the previous install package. You can find this UpgradeCode by looking in an old MSI, for example with Orca.

Product codes and UpgradeCodes become more important later when you are preparing new MSIs that your existing customers will be installing as "small updates", "minor upgrades" and "major upgrades". This tutorial does not get into this subject.

To generate a GUID in SharpDevelop just select Edit - Insert - Insert new GUID.

(To generate a GUID in Visual Studio just select Tools - Create GUID, select Registry Format, and click on Copy.)

(If things go wrong on a specific PC with installation of MSIs with conflicting product codes then it may be possible to recover from these Windows Installer mix-ups with Microsoft's Msicuu and Msizap utilities.)

 

Obtaining Orca

When working with MSIs it is a great advantage to have the Microsoft Orca tool. Orca allows you to examine the tables in an MSI, and even to modify them. It also contains some validation tools.

Orca is part of the free Windows Installer SDK, which in turn is part of the free Windows Platform SDK. After obtaining the Windows Platform SDK you should find and double-click on Orca.msi.

 

-- To be continued, in "Part 1 - Installing with no UI"

 

Rennie Petersen, March-May 2007

Expand all       Collapse all Copyright 2007 Merlinia - All rights reserved - Terms and conditions