WiX: A Developer's Guide to Windows Installer XML

Table of Contents

WiX: A Developer's Guide to Windows Installer XML

Credits

About the Author

About the Reviewer

Preface

What this book covers

What you need for this book

Who this book is for

Conventions

Reader feedback

Customer support

Errata

Piracy

Questions

1. Getting Started

Introducing Windows Installer XML

What is WiX?

Is WiX for you?

Where can I get it?

Votive

A word about GUIDs

Your first WiX project

XML declaration and Wix element

Product element

Package element

Media element

Directories

Components

Files

Features

Start Menu shortcuts

Putting it all together

Adding a User Interface

Viewing the MSI database

Orca.exe

Turning logging on during installation

Other resources

Summary

2. Creating Files and Directories

File element

DirectoryRef element

ComponentGroup element

Fragment element

Harvesting files with heat.exe

Copying and moving files

Copying files you install

Copying existing files

Moving existing files

Installing special-case files

Adding assembly files to the GAC

Installing a TrueType font

Creating an empty folder

Setting file permissions

Speeding up file installations

Summary

3. Putting Properties and AppSearch to Work

Custom properties

Declaring and setting properties

Referencing properties

Property visibility and scope

Secure properties

Property datatypes

Predefined Windows Installer properties

Implied properties

Cited properties

AppSearch

DirectorySearch

FileSearch

ComponentSearch

RegistrySearch

IniFileSearch

Summary

4. Improving Control with Launch Conditions and Installed States

Conditions

Condition syntax

Launch conditions

Feature conditions

Component conditions

Action state

Installed state

Summary

5. Understanding the Installation Sequence

InstallUISequence

UI standard actions

AppSearch

LaunchConditions

ValidateProductID

CostInitialize

FileCost

CostFinalize

ExecuteAction

InstallExecuteSequence

Execute standard actions

InstallValidate

InstallInitialize

ProcessComponents

UnpublishFeatures

RemoveRegistryValues

RemoveShortcuts

RemoveFiles

InstallFiles

CreateShortcuts

WriteRegistryValues

RegisterUser

RegisterProduct

PublishFeatures

PublishProduct

InstallFinalize

Immediate vs. deferred

Custom actions

Set a Windows Installer Property

Set the location of an Installed Directory

Run embedded VBScript or JScript

Call an external VBScript or JScript file

Call a function from a dynamic-link library

Trigger an executable

Send an error that stops the installation

Rollback custom actions

Accessing properties in a deferred action

Adding conditions to custom actions

Deployment Tools Foundation

Session object

Getting and setting properties

Logging

Showing a MessageBox

Accessing feature and component states

Querying the MSI database

Inserting rows into the MSI database

Summary

6. Adding a User Interface

WiX standard dialog sets

WixUI_Advanced

WixUI_FeatureTree

WixUI_InstallDir

WixUI_Mondo

Customizing a standard dialog set

Creating your own dialogs

ICE20 errors

Adding dialog files

Scheduling dialogs

Dialog element

Adding TextStyle elements

Adding a tabbable control

Adding a progress dialog

Modal windows

ICE20 revisited

FilesInUse

Error

FatalError

UserExit

Exit

Summary

7. Using UI Controls

Controls

PushButton

Text

ScrollableText

Line

GroupBox

Bitmap

Icon

Edit

MaskedEdit

PathEdit

CheckBox

RadioButtonGroup

ComboBox

ListBox

ListView

DirectoryList

DirectoryCombo

SelectionTree

VolumeCostList

VolumeSelectCombo

Billboard

ProgressBar

Summary

8. Tapping into Control Events

Publish element

Subscribe element

Publish events

AddLocal

DoAction

EndDialog

NewDialog

Publishing a property

Subscribe events

ScriptInProgress

SelectionAction

TimeRemaining

Summary

9. Working from the Command Line

Candle.exe

Command-line arguments (compiling)

-arch

-d

-ext

-fips

-I

-nologo

-o

-p

-pedantic

-sfdvital

-ss

-sw

-trace

-v

-wx

Response files

.wixobj files

Compile-time variables

Environment variables

System variables

Custom variables

Preprocessor extensions

Conditional statements and iterations

if...elseif...else

ifdef

ifndef

Iterations

Errors and warnings

Light.exe

Command-line arguments (linking)

-ai

-b

-bf

-binder

-cultures

-d

-dut

-ext

-loc

-nologo

-notidy

-o[ut]

-pedantic

-sadmin

-sadv

-sloc

-sma

-ss

-sts

-sui

-sv

-sw[N]

-usf

-v

-wx[N]

-xo

Command-line arguments (binding)

-bcgg

-cc

-ct

-cub

-dcl:level

-eav

-fv

-ice

-pdbout

-reusecab

-sa

-sacl

-sf

-sh

-sice:

-sl

-spdb

-sval

Link-time variables

Localization variables

Binder variables

Custom variables

Building an installer without Visual Studio

Summary

10. Accessing the Windows Registry

Reading from the Registry

Writing to the Registry

RegistryValue

RegistryKey

Setting NeverOverwrite

Removing Registry values

RemoveRegistryKey

RemoveRegistryValue

Copying Registry values

Registry permissions

Summary

11. Controlling Windows Services

Creating a simple Windows service

Using sc.exe

Using WiX to install a service

Starting, stopping, and uninstalling a service

Setting the service's user account

Adding service dependencies

Service recovery with Util:ServiceConfig

Summary

12. Localizing Your Installer

Setting language and code page attributes

Package element

Product element

WiX localization files

The role of Light.exe

Localizing error messages

Localizing the EULA

Creating a multi-language MSI

Summary

13. Upgrading and Patching

Planning for updates

Choosing an update type

Per-user or per-machine

Major upgrade

Minor upgrade

Authoring a patch file

Building the patch on the command line

Small update

Summary

WiX: A Developer's Guide to Windows Installer XML

WiX: A Developer's Guide to Windows Installer XML

Copyright © 2010 Packt Publishing

All rights reserved. No part of this book may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, without the prior written permission of the publisher, except in the case of brief quotations embedded in critical articles or reviews.

Every effort has been made in the preparation of this book to ensure the accuracy of the information presented. However, the information contained in this book is sold without warranty, either express or implied. Neither the author, nor Packt Publishing, and its dealers and distributors will be held liable for any damages caused or alleged to be caused directly or indirectly by this book.

Packt Publishing has endeavored to provide trademark information about all of the companies and products mentioned in this book by the appropriate use of capitals. However, Packt Publishing cannot guarantee the accuracy of this information.

First published: October 2010

Production Reference: 1131010

Published by Packt Publishing Ltd.

32 Lincoln Road

Olton

Birmingham, B27 6PA, UK.

ISBN 978-1-849513-72-2

www.packtpub.com

Cover Image by Asher Wishkerman ( <a.wishkerman@mpic.de >)

Credits

Author

Nick Ramirez

Reviewer

Martin Oberhammer

Acquisition Editor

Eleanor Duffy

Development Editor

Dhiraj Chandiramani

Technical Editors

Vanjeet D'souza

Kavita Iyer

Harshit Shah

Indexer

Tejal Daruwale

Editorial Team Leader

Akshara Aware

Project Team Leader

Priya Mukherji

Project Coordinator

Jovita Pinto

Proofreader

Lynda Sliwoski

Production Coordinator

Melwyn D'sa

Cover Work

Melwyn D'sa

About the Author

Nick Ramirez is a software engineer working at Sophos in Columbus, Ohio. He previously worked with open source solutions like Linux and PHP before moving to C#, WiX, and other Windows technologies. As a member of the engineering team, he has helped to develop install code for the company's enterprise software.

I would like to thank especially my fiancée, Heidi, for her patience while I worked on this book. I'd also like to thank the Packt team for their hard work and guidance along the way. Another big thanks to Martin Oberhammer and Neil Sleightholm for their WiX expertise and help in filling in the gaps

About the Reviewer

Martin Oberhammer was born on December 25, 1975 in Italy. In 1995 he moved to Linz in Austria, where he studied computer science at the Johannes Kepler University and graduated in October 2002.

Martin worked at the Ars Electronica Center in Linz during his study. Together with artists, he created virtual realities for the CAVE. In May 2003 he started working for Utimaco Safeguard AG in Linz and developed advanced authentication techniques, like smart cards, for Microsoft Windows systems. He also made his first experiences in deploying software. The company transferred him to Foxboro, MA in USA in August 2008. Among other things he created setups using WiX technology. He moved to Columbus, OH in October 2009 and started working for Sophos Inc., where he continues creating setups.

Preface

Since Rob Mensching offered up the WiX toolset as the first open source project from Microsoft in 2004, it has been quietly gaining momentum and followers. Today, thousands use it to build Windows Installer packages from simple XML elements. Gone are the days when you would have had to pay for software to build an installer for you. Now, you can do it yourself for cheap.

Not only that, but WiX has matured into a fairly slick product that's sufficiently easy to use. Best of all, it has all of the bells and whistles you want including the functionality to add user interface wizards, Start Menu shortcuts, control Windows services, and read and write to the Registry.

WiX: A Developer's Guide to Windows Installer XML gives you the knowledge to start building sophisticated installers right away, even if you have no prior experience doing so. Each chapter gets straight to the point, giving you hands on experience, so you'll master the technology quickly.

What this book covers

Chapter 1, Getting Started, explains how after downloading and installing the WiX toolset, you'll start using it right away to create a simple installer. Then, you'll see how to add a basic user interface to it, install it with logging turned on, and view its internal database.

Chapter 2, Creating Files and Directories, gives you deeper understanding of how files are installed and what is the best way to organize them in your project. You'll then use the tool heat.exe to generate WiX markup. Last, you'll learn about copying and moving files, and installing special-case files.

Chapter 3, Putting Properties and AppSearch to Work, gets you introduced to Windows Installer properties as you create your own and use those that are built in. Later, you'll check the end user's computer for specific files, directories, Registry keys, and INI file settings using AppSearch.

Chapter 4, Improving Control with Launch Conditions and Installed States, allows you to leverage conditional statements to set prerequisites for running your installer and to exclude particular features or components from the install. You'll also discover how to check the action and installed state of your features and components.

Chapter 5, Understanding the Install Sequence, allows you to get a clear picture of how the whole installation process works as you examine the order and meaning of installer actions. You will then create custom actions and add them to this built-in sequence to extend the functionality. Then, you'll learn the basics of using the Deployment Tools Foundation library for writing custom action code in C#.

Chapter 6, Adding a User Interface, after giving you a quick introduction to the standard dialog wizards that come with the WiX toolset, allows you to start building your own from scratch. You'll learn all of the required elements to display dialogs and to link them together. You'll also see how to build dialogs for displaying errors and user exits.

Chapter 7, Using UI Controls, gives you hands on experience with each type of UI control including buttons, textboxes, and progress bars.

Chapter 8, Tapping into Control Events, breathes life into your UI controls by having them publish and subscribe to events.

Chapter 9, Working from the Command Line, compiles your code from the command line and then links and binds object files into an MSI. You'll learn to use preprocessor variables and conditional statements and how to create custom preprocessor extensions.

Chapter 10, Accessing the Windows Registry,allows you to read from the Windows Registry and add keys and values to it at install time. You'll also learn how to remove existing keys, copy values, and set permissions.

Chapter 11, Controlling Windows Services, installs Windows services and issues start, stop, and remove commands to them. You'll learn to set the service's user account, add service dependencies, and set failure recovery.

Chapter 12, Localizing Your Installer, creates localized installers for different languages and teaches how light.exe, the WiX linker, plays a role. You'll then learn how to make a single multi-language installer.

Chapter 13, Upgrading and Patching, allows you to learn how to plan for and implement a major upgrade of your product and how to make small updates using patch files.

What you need for this book

In order to both write and run the code demonstrated in this book, you will need the following:

Visual Studio 2005 or newer (Standard edition or higher)

The WiX toolset, which can be downloaded from http://wix.codeplex.com/

Who this book is for

If you are a developer and want to create installers for software targeting the Windows platform, then this book is for you. You'll be using a lot of XML so that you get accustomed to the basics of writing well-formed documents, using XML namespaces and the dos and don'ts of structuring elements and attributes. You should know your way around Visual Studio, at least enough to compile projects, add project references, and tweak project properties. No prior knowledge of Windows Installer or WiX is assumed.

Conventions

In this book, you will find a number of styles of text that distinguish between different kinds of information. Here are some examples of these styles, and an explanation of their meaning.

Code words in text are shown as follows: We can include other contexts through the use of the include directive.

A block of code is set as follows:

CMP_MyProgramEXE

          Guid=E8A58B7B-F031-4548-9BDD-7A6796C8460D>

  FILE_MyProgramEXE

        Source=MyProgram.exe

        Name=NewName.exe

        KeyPath=yes />

When we wish to draw your attention to a particular part of a code block, the relevant lines or items are set in bold:

File Id=FILE_MyProgramEXE     Source=$(var.FilesPath)MyProgram.exe

    KeyPath=yes />

Any command-line input or output is written as follows:

Light.exe -loc en-us.wxl -loc en-us2.wxl -loc de-de.wxl -cultures:en-us *.wixobj -out myInstaller.msi

New terms and important words are shown in bold. Words that you see on the screen, in menus or dialog boxes for example, appear in the text like this: Use the Add Reference option in your Solution Explorer.

Note

Warnings or important notes appear in a box like this.

Tip

Tips and tricks appear like this.

Reader feedback

Feedback from our readers is always welcome. Let us know what you think about this book—what you liked or may have disliked. Reader feedback is important for us to develop titles that you really get the most out of.

To send us general feedback, simply send an e-mail to <feedback@packtpub.com>, and mention the book title via the subject of your message.

If there is a book that you need and would like to see us publish, please send us a note in the SUGGEST A TITLE form on www.packtpub.com or e-mail .

If there is a topic that you have expertise in and you are interested in either writing or contributing to a book, see our author guide on www.packtpub.com/authors.

Customer support

Now that you are the proud owner of a Packt book, we have a number of things to help you to get the most from your purchase.

Tip

Downloading the example code for this book

You can download the example code files for all Packt books you have purchased from your account at http://www.PacktPub.com. If you purchased this book elsewhere, you can visit http://www.PacktPub.com/support and register to have the files e-mailed directly to you.

Errata

Although we have taken every care to ensure the accuracy of our content, mistakes do happen. If you find a mistake in one of our books—maybe a mistake in the text or the code—we would be grateful if you would report this to us. By doing so, you can save other readers from frustration and help us improve subsequent versions of this book. If you find any errata, please report them by visiting http://www.packtpub.com/support, selecting your book, clicking on the errata submission form link, and entering the details of your errata. Once your errata are verified, your submission will be accepted and the errata will be uploaded on our website, or added to any list of existing errata, under the Errata section of that title. Any existing errata can be viewed by selecting your title from http://www.packtpub.com/support.

Piracy

Piracy of copyrighted material on the Internet is an ongoing problem across all media. At Packt, we take the protection of our copyright and licenses very seriously. If you come across any illegal copies of our works, in any form, on the Internet, please provide us with the location address or website name immediately so that we can pursue a remedy.

Please contact us at <copyright@packtpub.com> with a link to the suspected pirated material.

We appreciate your help in protecting our authors, and our ability to bring you valuable content.

Questions

You can contact us at <questions@packtpub.com> if you are having a problem with any aspect of the book, and we will do our best to address it.

Chapter 1. Getting Started

Windows Installer XML (WiX) is a free XML markup from Microsoft that is used to author installation packages for Windows-based software. The underlying technology is Windows Installer, which is the established standard for installing desktop-based applications to any Windows operating system. It is used by countless companies around the world. Microsoft uses it to deploy its own software including Microsoft Office and Visual Studio. In fact, Microsoft uses WiX for these products.

Windows Installer has many features, but how do you leverage them? How do you even know what they are? This book will help you by making you more familiar with the wide range of capabilities that are available. WiX makes many of the arcane and difficult to understand aspects of Windows Installer technology simple to use. This book will teach you the WiX syntax so that you can create a professional-grade installer that's right for you.

In this chapter, we will cover the following:

Getting WiX and using it with Visual Studio

Creating your first WiX installer

Examining an installer database with Orca

Logging an installation process

Adding a simple user interface

Introducing Windows Installer XML

In this section, we'll dive right in and talk about what WiX is, where to get it, and why you'd want to use it when building an installation package for your software. We'll follow up with a quick description of the WiX tools and the new project types made available in Visual Studio.

What is WiX?

Although it's the standard technology and has been around for years, creating a Windows Installer, or MSI package, has always been a challenging task. The package is actually a relational database that describes how the various components of an application should be unpacked and copied to the end user's computer.

In the past you had two options:

You could try to author the database yourself—a path that requires a thorough knowledge of the Windows Installer API.

You could buy a commercial product like InstallShield to do it for you. These software products will take care of the details, but you'll forever be dependent on them. There will always be parts of the process that are hidden from you.

WiX is relatively new to the scene, offering a route that exists somewhere in the middle. Abstracting away the low-level function calls while still allowing you to write much of the code by hand, WiX is an architecture for building an installer in ways that mere mortals can grasp. Best of all, it's free. As an open source product, it has quickly garnered a wide user base and a dedicated community of developers. Much of this has to do not only with its price tag but also with its simplicity. It can be authored in a simple text editor (such as Notepad) and compiled with the tools provided by WiX. As it's a flavor of XML, it can be read by humans, edited without expensive software, and lends itself to being stored in source control where it can be easily merged and compared.

The examples in this first chapter will show how to create a simple installer with WiX using Visual Studio. However, later chapters will show how you can build your project from the command line using the compiler and linker from the WiX toolset. The WiX source code is available for download, so you can be assured that nothing about the process will be hidden if you truly need to know.

Is WiX for you?

To answer the question Is WiX for you? we have to answer "What can WiX do for you?" It's fairly simple to copy files to an end user's computer. If that's all your product needs, then the Windows Installer technology might be overkill. However, there are many benefits to creating an installable package for your customers, some of which might be overlooked. Following is a list of features that you get when you author a Windows Installer package with WiX:

All of your executable files can be packaged into one convenient bundle, simplifying deployment.

Your software is automatically registered with Add/Remove Programs.

Windows takes care of uninstalling all of the components that make up your product when the user chooses to do so.

If files for your software are accidently removed, they can be replaced by right-clicking on the MSI file and selecting Repair.

You can create different versions of your installer and detect which version has been installed.

You can create patches to update only specific areas of your application.

If something goes wrong while installing your software, the end user's computer can be rolled back to a previous state.

You can create Wizard-style dialogs to guide the user through the installation.

Many people today simply expect that your installer will have these features. Not having them could be seen as a real deficit. For example, what is a user supposed to do when they want to uninstall your product but can't find it in the Add/Remove Programs list and there isn't an uninstall shortcut? They're likely to remove files haphazardly and wonder why you didn't make things easy for them.

Maybe you've already figured that Windows Installer is the way to go, but why WiX? One of my favorite reasons is that it gives you greater control over how things work. You get a much finer level of control over the development process. Commercial software that does this for you also produces an MSI file, but hides the details about how it was done. It's analogous to crafting a web site. You get much more control when you write the HTML yourself as opposed to using WYSIWYG software.

Even though WiX gives you more control, it doesn't make things overly complex. You'll find that making a simple installer is very straightforward. For more complex projects, the parts can be split up into multiple XML source files to make it easier to work with. Going further, if your product is made up of multiple products that will be installed together as a suite, you can compile the different chunks into libraries that can be merged together into a single MSI. This allows each team to isolate and manage their part of the installation package.

WiX is a stable technology, having been first released to the public in 2004, so you don't have to worry about it disappearing. It's also had a steady progression of version releases. The most current version is updated for Windows Installer 4.5 and the next release will include changes for Windows Installer 5.0, which is the version that comes preinstalled with Windows 7. These are just some of the reasons why you might choose to use WiX.

Where can I get it?

You can download WiX from the Codeplex site, http://wix.codeplex.com/, which has both stable releases and source code. The current release is version 3.0. Once you've downloaded the WiX installer package, double-click it to install it to your local hard drive.

This installs all of the necessary files needed to build WiX projects. You'll also get the WiX SDK documentation and the settings for Visual Studio IntelliSense, highlighting and project templates. Version 3 supports Visual Studio 2005 and Visual Studio 2008, Standard edition or higher.

WiX comes with the following tools:

In order to use some of the functionality in WiX, you may need to download a more recent version of Windows Installer. You can check your current version by viewing the help file for msiexec.exe, which is the Windows Installer service. Go to your Start Menu and select Run, type cmd and then type msiexec /? at the prompt. This should bring up a window like the following:

If you'd like to install a newer version of Windows Installer, you can get one from the Microsoft Download Center website. Go to:

http://www.microsoft.com/downloads/en/default.aspx

Search for Windows Installer. The