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

i/tI open &

[p/Vf
I I I
I \Km* 1^ I
source
community experience distilled

PUBLISHING

BIRMINGHAM -
MUMBAI
 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 first 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
Table of Contents

Chapter 2: Creating Files and Directories 45

The File element 45
The DirectoryRef element 48
The ComponentGroup element 49
The Fragment element 51

Harvesting files with heatexe 55

Copying and moving files 61

Copying files you install 61

Copying existing files 63

Moving existing files 64

Installing special-case files 64

Adding assembly files to the GAC 65

Installing a TrueType font 66

Installing 64-bit files 67

Creating an empty folder 69

Setting file permissions 70

Speeding up file 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

Predefined Windows Installer properties 86

Implied properties 87
Citedproperties 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
 Table of Contents

Feature conditions 113

Component conditions 116
Action state 119
Installed state 121
Summary 122

Chapter 5: Understanding the Installation Sequence 123

InstallUISequence 123
Ul standard actions 125
FindRelatedProducts 125
AppSearch 125
LaunchConditions 125
ValidateProductID 125
Costlnitialize 125
FileCost 126
CostFinalize 126
MigrateFeatureStates 126
ExecuteAction 126
InstallExecuteSequence 126
Execute standard actions 128
InstallValidate 128
Installlnitialize 128
ProcessComponents 128
UnpublishFeatures 128
RemoveRegistryValues 128
RemoveShortcuts 129
RemoveFiles 129
InstallFiles 129
CreateShortcuts 129
WriteRegistry Values 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 file 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
Table of Contents

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
WixUIJnstallDir 159

WixUI_Mondo 160
Customizing a standard dialog set 161

Creating your own dialogs 163

ICE20 errors 163

Adding dialog files 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
FileslnUse 177
Error 179
FatalError 181
UserExit 182
Exit 183

Summary 185

Chapter 7: Using Ul Controls 187

Attributes common to all controls 187
Specific control syntax 189
PushButton 189
Text 192
ScrollableText 193
Line 194
 Table of Contents

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
ScriptlnProgress 240
SelectionAction 242
TimeRemaining 243
Summary 246

Chapter 9: Working from the Command Line 247

Candle.exe 247
Response files 249

.wixobj files 250

Command-line arguments (compiling) 250
-arch 251
-d 251
-ext 251
Table of Contents

-ftps 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

Ligntexe 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
-sloe 267
-sma 267
-ss 268
-sts 268
-sui 268
-sv 268
-sw[N] 268
-usf <output.xml> 269
 Table of Contents

-v 269
-wx[N] 269
-xo 269
Command-line arguments (binding) 269
-bcgg 269
-cc <path> 270
-ct <N> 270
-cub <file.cub> 270
-dcklevel 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
-si 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 simple
a Windows service 293
Using sc.exe 296
Using WiX to install a service 298
Table of Contents

Starting, stopping, and uninstalling a service 300

Setting the service's user account 303
Adding service dependencies 307
Service recovery with UtihServiceConfig 310

Summary 313

Chapter 12: Localizing Your Installer 315

WiX localization files 315
The role ofLightexe 319

Setting language and code page attributes 321

The Package element 322
The Product element 325
Localizing the Ul 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 per-machine
or 343
Preparing major upgrade
a 343
The minor upgrade 350
Authoring a .wixmsp file 350
Creating a patch from .wixpdb files 353
Creating a patch from .wixout files 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
 Table of Contents

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 Ul 415
The RtfLicense user interface 415
The HyperlinkLicense user interface 416
Summary 418
Chapter 16: Customizing the Burn Ul 419
Burn extension points 419
Creating the class library 420
Extending the BootstrapperApplication class 422
Defining the model 425
Implementing the viewmodel 427
Declaring the properties and fields 432
Defining the constructor
434
Setting up the event handlers 435
Helper methods 438
Marking up the view 439
Referencing the Ul 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