WiX 3.6: A Developer''''s Guide to Windows Installer XML doc

www.it-ebooks.info
WiX 3.6: A Developer's Guide
to Windows Installer XML
An in-and-out, to-the-point introduction to Windows
Installer XML
Nick Ramirez
BIRMINGHAM - MUMBAI
www.it-ebooks.info
WiX 3.6: A Developer's Guide to Windows Installer XML
Copyright © 2012 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
Second edition: December 2012
Production Reference: 1051212
Published by Packt Publishing Ltd.
Livery Place
35 Livery Street
Birmingham B3 2PB, UK.
ISBN 978-1-78216-042-7
www.packtpub.com

Cover Image by Abhishek Pandey ()
www.it-ebooks.info
Credits
Author
Nick Ramirez
Reviewers
Neil Sleightholm
Martin Oberhammer
Paul Michniewicz
Roel van Bueren
ENG. Nir Bar
Acquisition Editor
Usha Iyer
Lead Technical Editor
Dayan Hyames
Technical Editor
Jalasha D'costa
Project Coordinator
Arshad Sopariwala
Proofreader
Maria Gould
Indexer
Rekha Nair
Production Coordinator
Arvindkumar Gupta
Cover Work
Arvindkumar Gupta
www.it-ebooks.info
About the Author
Nick Ramirez is a software developer living in Columbus, Ohio. As a believer that

deployment shouldn't be a moment of terror, he has become a big fan of technologies
such as WiX. Other related interests include build automation, software architecture,
and playing Portal 2. Nick lives with his wife and two cats.
I would like to thank the hard-working folks at Packt Publishing.
Their organization and planning make all the difference! I would
also like to thank the dedicated people of the WiX community, who
tirelessly volunteer their time to answer questions. Finally, I would
like to thank the developers who contribute source code to the WiX
project. Their expertise and commitment have gone towards making
the best Windows deployment tool on the market.
www.it-ebooks.info
About the Reviewers
Neil Sleightholm is an IT consultant working in the UK. He has an engineering
background with experience in software development, application architecture,
electronics development, and mechanical engineering.
His current focus is on conguration management, build automation, installation
development, and deployment.
Neil has worked with most of the Microsoft platform technologies and has
programmed in C, C++, C#, Visual Basic, .NET, SQL, ASP.NET, and ASP. In the
build and source control eld he has experience with NAnt, MSBuild, TeamBuild,
Subversion (SVN), TFS, VSS, Mercurial, and CVS. He has written installation systems
using Windows Installer, Windows Installer XML (WiX), Windows Installer Custom
Actions (using DTF), dotNetInstaller, InnoSetup, and Wise Installation System.
Neil has worked with open source projects and has been a contributor to
Windows Installer XML (WiX), dotNetInstaller, and the AlienBBC plugin
for Logitech Squeezebox.
In his spare time he is a petrol head and keen motorcyclist.
If you want to know more about him, you can check out his LinkedIn prole at:
/>Martin Oberhammer currently works as a Software Engineer at Sophos in
Vancouver, BC.

He studied computer science at the Johannes Kepler University in Linz, Austria,
where he graduated in 2002. His rst job in software deployment was at Utimaco
Safeguard AG. In 2008, he moved to the USA and then to Canada, where he now
resides. Nick and Martin where at one point colleagues and created a software
installer using WiX technology.
www.it-ebooks.info
Paul Michniewicz is a software developer and educational consultant with
diverse experiences in academia, government, and industry.
As a developer, Paul has spent more than 12 years in software development and
testing. Much of that time was spent in conguration management where he has
managed source control systems, developed build and test automation strategies,
and authored several installers in the enterprise space for companies such as
JetForm and Adobe.
As an educational consultant, Paul has developed and delivered introductory
Java courses to professionals and students. He currently runs a tutoring business
where he teaches mathematics, physical sciences, and software development to
students of all ages. Paul has a special interest in working with students who have
developmental needs.
Paul lives in Ottawa, Canada with his wife Anne and two children Zygmunt
and Moira. He is currently a stay-at-home dad and homeschools his son. To know
more about Paul, you can check out his LinkedIn prole at
ca.linkedin.com/in/
pmichnie
.
Roel van Bueren works as senior consultant, trainer, and developer for
ROVABU NetWorks BV and ROVABU Software BV. Roel is specialized in Software
Packaging using Windows Installer and Flexera AdminStudio, Application and
Desktop Management by using Microsoft System Center Conguration Manager and
Novell ZENworks Conguration Management, Desktop Deployment of Microsoft
Windows XP, Windows 7, and Windows 8 by using Microsoft SCCM/MDT, Novell

ZENworks Conguration Management, ENGL Imaging Toolkit, and also Microsoft
.NET/C# development and application virtualization.
His latest projects involve "Bundle Commander" for Novell ZENworks
Conguration Management and "Setup Commander" for Microsoft System Center
Conguration Manager 2012, Microsoft Deployment Toolkit, and other deployment
solutions such as Dell KACE and RES Automation Manager, for which customized
transform les are needed to deploy MSI packages or silent switches to deploy
legacy setups.
www.it-ebooks.info
ENG. Nir Bar is a computer engineer, and graduate of Technion – Israel Institute
of Technology.
Nir Bar has over 13 years experience in software and hardware development.
He has worked with RAFAEL – Advanced Defense Systems, Marvell Technology
Group, Agilent Technologies, Applied Materials, McKesson, and other leading high
tech companies. He has worked in the Microsoft platform technologies and has
programmed in C, C++, C# .NET, and SQL Server.
In the Linux platform, Nir Bar has programmed in C, C++, and PERL.
He is also experienced in pre-Silicon verication methodologies and tools.
Currently, Nir is an independent software consultant, developer, and tutor.
He consults and develops software products from the idea stage through
analysis, design, development stages, and to ready-to-market products.
Nir Bar tutors Windows Installer technology to Israeli software companies.
To contact Nir Bar you can drop an e-mail to:

To my wife Sarit and to my sons Itay and Yehonathan for their love,
support, and encouragement.
www.it-ebooks.info
www.PacktPub.com
Support les, eBooks, discount offers and more
You might want to visit www.PacktPub.com for support les and downloads related

to your book.
Did you know that Packt offers eBook versions of every book published, with PDF
and ePub les available? You can upgrade to the eBook version at
www.PacktPub.
com
and as a print book customer, you are entitled to a discount on the eBook copy.
Get in touch with us at for more details.
At
www.PacktPub.com, you can also read a collection of free technical articles, sign
up for a range of free newsletters and receive exclusive discounts and offers on Packt
books and eBooks.

Do you need instant solutions to your IT questions? PacktLib is Packt's online
digital book library. Here, you can access, read and search across Packt's entire
library of books.
Why Subscribe?
• Fully searchable across every book published by Packt
• Copy and paste, print and bookmark content
• On demand and accessible via web browser
Free Access for Packt account holders
If you have an account with Packt at www.PacktPub.com, you can use this to access
PacktLib today and view nine entirely free books. Simply use your login credentials
for immediate access.
www.it-ebooks.info
www.it-ebooks.info
www.it-ebooks.info
To my wife, Heidi, for her patience while I disappeared into research and writing.
www.it-ebooks.info
www.it-ebooks.info
Table of Contents

Preface 1
Chapter 1: Getting Started 7
Introducing Windows Installer XML 8
What is WiX? 8
Is WiX for you? 9
Where can I get it? 10
Visual Studio package (Votive) 13
A word about GUIDs 16
Your rst WiX project 16
XML declaration and Wix element 17
The Product element 18
The Package element 20
The MediaTemplate element 21
The Media element 22
The Directory element 23
The Component element 27
The File element 29
The Feature element 30
Start menu shortcuts 33
Putting it all together 37
Adding a user interface 40
Viewing the MSI database 41
Orca.exe 41
Turning logging on during installation 42
Other resources 43
Summary 43
www.it-ebooks.info
Table of Contents
[ ii ]
Chapter 2: Creating Files and Directories 45

The File element 45
The DirectoryRef element 48
The ComponentGroup element 49
The Fragment element 51
Harvesting les with heat.exe 55
Copying and moving les 61
Copying les you install 61
Copying existing les 63
Moving existing les 64
Installing special-case les 64
Adding assembly les to the GAC 65
Installing a TrueType font 66
Installing 64-bit les 67
Creating an empty folder 69
Setting le permissions 70
Speeding up le installations 74
Summary 75
Chapter 3: Putting Properties and AppSearch to Work 77
Custom properties 77
Declaring and setting properties 78
Referencing properties 79
Property visibility and scope 80
Secure properties 82
Property data types 84
Predened Windows Installer properties 86
Implied properties 87
Cited properties 88
AppSearch 90
DirectorySearch 91
FileSearch 94

ComponentSearch 95
RegistrySearch 97
IniFileSearch 100
Summary 103
Chapter 4: Improving Control with Launch
Conditions and Installed States 105
The syntax of conditions 105
Condition syntax 106
Launch conditions 107
www.it-ebooks.info
Table of Contents
[ iii ]
Feature conditions 113
Component conditions 116
Action state 119
Installed state 121
Summary 122
Chapter 5: Understanding the Installation Sequence 123
InstallUISequence 123
UI standard actions 125
FindRelatedProducts 125
AppSearch 125
LaunchConditions 125
ValidateProductID 125
CostInitialize 125
FileCost 126
CostFinalize 126
MigrateFeatureStates 126
ExecuteAction 126
InstallExecuteSequence 126

Execute standard actions 128
InstallValidate 128
InstallInitialize 128
ProcessComponents 128
UnpublishFeatures 128
RemoveRegistryValues 128
RemoveShortcuts 129
RemoveFiles 129
InstallFiles 129
CreateShortcuts 129
WriteRegistryValues 129
RegisterUser 129
RegisterProduct 129
PublishFeatures 130
PublishProduct 130
InstallFinalize 130
Immediate versus deferred 130
Custom actions 131
Setting a Windows Installer property 133
Setting the location of an installed directory 134
Running embedded VBScript or JScript 135
Calling an external VBScript or JScript le 137
Calling a function from a dynamic-link library 138
Triggering an executable 140
Sending an error that stops the installation 142
Rollback custom actions 143
Accessing properties in a deferred action 144
www.it-ebooks.info
Table of Contents
[ iv ]

Adding conditions to custom actions 146
Deployment Tools Foundation 147
The session object 147
Getting and setting properties 148
Logging 148
Showing a message box 149
Accessing feature and component states 150
Querying the MSI database 151
Inserting rows into the MSI database 151
Summary 153
Chapter 6: Adding a User Interface 155
WiX standard dialog sets 155
WixUI_Advanced 156
WixUI_FeatureTree 158
WixUI_InstallDir 159
WixUI_Mondo 160
Customizing a standard dialog set 161
Creating your own dialogs 163
ICE20 errors 163
Adding dialog les 164
The Dialog element 165
Scheduling dialogs 166
Adding TextStyle elements 167
Adding a tabbable control 169
Adding a progress dialog 172
Modal windows 175
ICE20 revisited 177
FilesInUse 177
Error 179
FatalError 181

UserExit 182
Exit 183
Summary 185
Chapter 7: Using UI Controls 187
Attributes common to all controls 187
Specic control syntax 189
PushButton 189
Text 192
ScrollableText 193
Line 194
www.it-ebooks.info
Table of Contents
[ v ]
GroupBox 195
Bitmap 195
Icon 197
Edit 197
MaskedEdit 199
PathEdit 201
CheckBox 202
RadioButtonGroup 203
ComboBox 205
ListBox 206
ListView 207
DirectoryList 208
DirectoryCombo 211
SelectionTree 212
VolumeCostList 215
VolumeSelectCombo 216
Billboard 218

ProgressBar 222
Summary 226
Chapter 8: Tapping into Control Events 227
Publishing control events 227
Subscribing to control events 231
Publish events 232
DoAction 233
EndDialog 234
NewDialog 235
AddLocal 236
Publishing a property 239
Subscribe events 239
ScriptInProgress 240
SelectionAction 242
TimeRemaining 243
Summary 246
Chapter 9: Working from the Command Line 247
Candle.exe 247
Response les 249
.wixobj les 250
Command-line arguments (compiling) 250
-arch 251
-d 251
-ext 251
www.it-ebooks.info
Table of Contents
[ vi ]
-ps 251
-I 251
-nologo 252

-o 252
-p 252
-pedantic 252
-sfdvital 252
-ss 252
-sw 253
-trace 253
-v 253
-wx 253
Compile-time variables 253
Custom compiler variables 253
Environment variables 254
System variables 255
Conditional statements and iterations 255
if elseif else 255
ifdef 256
ifndef 256
Iterations 257
Errors and warnings 258
Preprocessor extensions 258
Light.exe 264
Command-line arguments (linking) 265
-b 265
-bf 265
-binder 265
-cultures 266
-d 266
-dut 266
-ext 266
-loc 266

-nologo 266
-notidy 267
-o[ut] 267
-pedantic 267
-sadmin 267
-sadv 267
-sloc 267
-sma 267
-ss 268
-sts 268
-sui 268
-sv 268
-sw[N] 268
-usf <output.xml> 269
www.it-ebooks.info
Table of Contents
[ vii ]
-v 269
-wx[N] 269
-xo 269
Command-line arguments (binding) 269
-bcgg 269
-cc <path> 270
-ct <N> 270
-cub <le.cub> 270
-dcl:level 270
-eav 270
-fv 270
-ice <ICE> 271
-pdbout <output.wixpdb> 271

-reusecab 271
-sa 271
-sacl 271
-sf 272
-sh 272
-sice: <ICE> 272
-sl 272
-spdb 272
-sval 272
Link-time variables 273
Localization variables 273
Binder variables 273
Custom linker variables 275
Building an installer without Visual Studio 276
Summary 278
Chapter 10: Accessing the Windows Registry 279
Reading from the registry 280
Writing to the registry 282
Writing a single value 283
Writing multiple values 284
Setting NeverOverwrite 287
Removing registry values 287
Remove all keys recursively 287
Removing a single value 288
Copying registry values 289
Registry permissions 290
Summary 292
Chapter 11: Controlling Windows Services 293
Creating a simple Windows service 293
Using sc.exe 296

Using WiX to install a service 298
www.it-ebooks.info
Table of Contents
[ viii ]
Starting, stopping, and uninstalling a service 300
Setting the service's user account 303
Adding service dependencies 307
Service recovery with Util:ServiceCong 310
Summary 313
Chapter 12: Localizing Your Installer 315
WiX localization les 315
The role of Light.exe 319
Setting language and code page attributes 321
The Package element 322
The Product element 325
Localizing the UI 326
Error messages 326
Progress bar messages 329
EULA 332
Resizing controls 334
Creating a multi-language MSI 336
Summary 339
Chapter 13: Upgrading and Patching 341
Planning for updates 341
Choosing an update type 342
Per-user or per-machine 343
Preparing a major upgrade 343
The minor upgrade 350
Authoring a .wixmsp le 350
Creating a patch from .wixpdb les 353

Creating a patch from .wixout les 356
The small update 358
Summary 358
Chapter 14: Extending WiX 359
Building a custom WiX extension 359
Setting the stage 360
Extending the CompilerExtension class 360
Adding an XML schema 362
Parsing custom elements 365
Creating a new MSI table 370
Extending the WixExtension class 372
Using the extension in a WiX project 374
Tying a custom action to the custom element 376
Summary 383
www.it-ebooks.info
Table of Contents
[ ix ]
Chapter 15: Bootstrapping Prerequisites with Burn 385
Using the Bootstrapper Project template 386
Describing the Bundle element 387
Restricting the install by the operating system 389
UpgradeCode and detecting related bundles 391
Updating existing bundles 391
Finding other related bundles 396
Where the packages are cached 397
Chaining packages 398
The Chain element 398
The MsiPackage element 400
The ExePackage element 402
The MspPackage element 405

The MsuPackage element 406
Downloading packages 407
Counting package references 410
Rollback boundaries 412
PackageGroups 413
The Standard Bootstrapper UI 415
The RtfLicense user interface 415
The HyperlinkLicense user interface 416
Summary 418
Chapter 16: Customizing the Burn UI 419
Burn extension points 419
Creating the class library 420
Extending the BootstrapperApplication class 422
Dening the model 425
Implementing the viewmodel 427
Declaring the properties and elds 432
Dening the constructor 434
Setting up the event handlers 435
Helper methods 438
Marking up the view 439
Referencing the UI in a Burn bundle 441
Passing user input to a bundled MSI 442
Displaying progress 444
Downloading packages 446
Collecting command-line arguments 447
Summary 448
Index 449
www.it-ebooks.info
www.it-ebooks.info
Preface

Since Rob Mensching offered up the WiX toolset as the rst open source project
from Microsoft in 2004, it has been quietly gaining momentum and followers.
Today, thousands use it to build Window 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 sufciently easy
to use. Best of all, it has the bells and whistles you want, including functionality to
add user interface wizards, Start menu shortcuts, control Windows services, and
read and write to the registry.
This new edition, WiX 3.6: A Developer's Guide to Windows Installer XML, brings
you up-to-date on the latest changes to the toolset. Whether you're new to WiX or
an established pro, you're likely to nd new insights. 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 a deeper understanding of how les
are installed and 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
les, and installing special-case les.
www.it-ebooks.info
Preface
[ 2 ]
Chapter 3, Putting Properties and AppSearch to Work, introduces you to Windows
Installer properties, including those that are dened automatically and those that are
invented by you. Afterwards, you'll check the end user's computer for specic les,
directories, registry keys, and INI le settings using AppSearch.
Chapter 4, Improving Control with Launch Conditions and Installed States, teaches you to

leverage conditional statements to set prerequisites for running your installer or to
exclude particular features or components from the install. You'll also discover how
to check the action state and installed state of your features and components.
Chapter 5, Understanding the Installation Sequence, gives you 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.
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 dialogue wizards that come with the WiX toolset, shows how to build
your own from scratch. You'll learn all of the required elements for displaying
dialogs and linking them together. You'll also see how to display common messages
such as errors and cancellation conrmations.
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. We'll get details on what each event does and
take a closer look at those you'll use on a routine basis.
Chapter 9, Working from the Command Line, emphasizes the fact that we don't
particularly need Visual Studio to compile our projects. We'll cover the commands
necessary to build an installer from the command line using Candle.exe, our
compiler, and Light.exe, our linker/binder. We will also explore how to use
preprocessor statements and how to create a custom preprocessor extension.
Chapter 10, Accessing the Windows Registry, illustrates how our installer may read
and write to the Windows Registry. We'll add and remove keys, copy values, and
set permissions.
Chapter 11, Controlling Windows Services, provides some solid examples for installing
and interacting with Windows services. You'll see how to set the service's user
account, add service dependencies, and set failure recovery.
Chapter 12, Localizing Your Installer, tackles how to render your UI for different

languages and how Light.exe, the WiX linker, plays a role. You'll then get involved
in making a single multi-language installer.
www.it-ebooks.info