39,59 €
Mehr erfahren.
- Herausgeber: Packt Publishing
- Kategorie: Wissenschaft und neue Technologien
- Sprache: Englisch
The cryptic science of Windows Installer can seem far off from the practical task of simply getting something installed. Luckily, we have WiX to simplify the matter. WiX is an XML markup, distributed with an open-source compiler and linker, used to produce a Windows Installer package. It is used by Microsoft and by countless other companies around the world to simplify deployments.
"WiX 3.6: A Developer's Guide to Windows Installer XML" promises a friendly welcome into the world of Windows Installer. Starting off with a simple, practical example and continuing on with increasingly advanced scenarios, the reader will have a well-rounded education by book's end.
With the help of this book, you'll understand your installer better, create it in less time, and save money in the process. No one really wants to devote a lifetime to understanding how to create a hassle-free installer. Learn to build a sophisticated deployment solution targeting the Windows platform in no time with this hands-on practical guide. Here we speed you through the basics and zoom right into the advanced. You'll get comfortable with components, features, conditions and actions. By the end, you'll be boasting your latest deployment victories at the local pub.
Once you've finished "WiX 3.6: A Developer's Guide to Windows Installer XML", you'll realize just how powerful and awesome an installer can really be.
Das E-Book können Sie in Legimi-Apps oder einer beliebigen App lesen, die das folgende Format unterstützen:
Seitenzahl: 524
Veröffentlichungsjahr: 2012
Ähnliche
Table of Contents
WiX 3.6: A Developer's Guide to Windows Installer XML
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 (<[email protected]>)
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
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.
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 configuration 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 field 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 profile at: http://www.linkedin.com/in/neilsleightholm.
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 first 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.
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 configuration 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 profile 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 Configuration Manager and Novell ZENworks Configuration Management, Desktop Deployment of Microsoft Windows XP, Windows 7, and Windows 8 by using Microsoft SCCM/MDT, Novell ZENworks Configuration Management, ENGL Imaging Toolkit, and also Microsoft .NET/C# development and application virtualization.
His latest projects involve "Bundle Commander" for Novell ZENworks Configuration Management and "Setup Commander" for Microsoft System Center Configuration Manager 2012, Microsoft Deployment Toolkit, and other deployment solutions such as Dell KACE and RES Automation Manager, for which customized transform files are needed to deploy MSI packages or silent switches to deploy legacy setups.
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 verification 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: <[email protected]>.
To my wife Sarit and to my sons Itay and Yehonathan for their love, support, and encouragement.
www.PacktPub.com
Support files, eBooks, discount offers and more
You might want to visit www.PacktPub.com for support files and downloads related to your book.
Did you know that Packt offers eBook versions of every book published, with PDF and ePub files 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 <[email protected]> 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.
http://PacktLib.PacktPub.com
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?
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.
To my wife, Heidi, for her patience while I disappeared into research and writing.
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 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 sufficiently 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 find 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 files 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 files, and installing special-case files.
Chapter 3, Putting Properties and AppSearch to Work, introduces you to Windows Installer properties, including those that are defined automatically and those that are invented by you. Afterwards, 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, 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 confirmations.
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.
Chapter 13, Upgrading and Patching, covers the all-so-important topic of upgrading and patching. You'll get the low down on major upgrades, minor upgrades, and small updates.
Chapter 14, Extending WiX, jumps into adding new, custom XML elements for extending the core functionality of WiX. We'll write a library, using C#, that takes our installer to places it's never been.
Chapter 15, Bootstrapping Prerequisites with Burn, discusses the new bootstrapping functionality called Burn. We'll create a single executable that installs all necessary prerequisites for our software.
Chapter 16, Customizing the Burn UI, solves the problem of customizing our Burn user interface by crafting a new one using C# and WPF. We'll discover the places where we can hook into the bootstrapper engine and how best to pass information from the user to our installation packages.
What you need for this book
In order to both write and run the code demonstrated in this book, you will need the following:
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. Those new to WiX and Windows Installer should feel right at home as we start with the basics and gradually work up to more complex subjects. Others with more experience will benefit as we catalog the new features in WiX 3.6. If you're coming from an earlier version of WiX, you'll be happy to know that for the most part, things that used to work will still work. However, several tasks, such as implementing a major upgrade, have been simplified. We'll highlight the big changes, but keep an eye on familiar elements as some subtle changes have been made.
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 <[email protected]>, and mention the book title through the subject of your message.
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.
Downloading the example code
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 erratasubmissionform link, and entering the details of your errata. Once your errata are verified, your submission will be accepted and the errata will be uploaded to our website, or added to any list of existing errata, under the Errata section of that title.
Piracy
Piracy of copyright 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 <[email protected]> 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 <[email protected]> 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, open source XML markup that's used to author installation packages for Windows-based software. The underlying technology is called Windows Installer, which is the established standard for installing to any Windows operating system. Until recently, WiX was a Microsoft offering, but is now supported by the non-profit Outercurve Foundation. 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. The good news is that WiX makes many of the arcane and difficult-to-understand aspects of the 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 topics:
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?
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:
WiX offers 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 a framework 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 more about it.
Is WiX 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. The following is a list of features that you get when you author a Windows Installer package with WiX:
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 Programs and Features list and there isn't an uninstall shortcut? They're likely to remove files in a haphazard manner 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 website. You get much more control when you write the HTML yourself as opposed to using a 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 complicated 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 applications 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 file. This allows each team to isolate and manage its 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. These are just some of the reasons why you might choose to use WiX.
Where can I get it?
You can find the latest version of WiX at http://wixtoolset.org/, which has both stable releases and weekly builds. The current release is Version 3.6. Once you've downloaded the WiX installer package, double-click on it to launch it. It relies on having an Internet connection to download the .NET 4.0 platform, if it's not already installed.
If you want to install on a computer that isn't connected to the Internet, first download the installer on a computer that is and then open a command prompt and run the WiX executable with the following command wix36.exe /layout LayoutDirectory. The layout option takes the name of a target directory where the WiX files will be downloaded to. You can then take these files (which include a new installer) to the computer that doesn't have an Internet connection and use them there.
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 and project templates. Version 3.6 supports Visual Studio versions 2005 through 2012, although not the Express editions.
WiX comes with the tools outlined in the following table:
Tool
What it does
Candle.exe
Compiles WiX source files (.wxs) into intermediate object files (.wixobj)
Light.exe
Links and binds .wixobj files to create a final .msi file. Also creates cabinet files and embeds streams in an MSI database
Lit.exe
Creates WiX libraries (.wixlib) that can be linked together by Light
Dark.exe
Decompiles an MSI file into WiX code
Heat.exe
Creates a WiX source file that specifies components from various inputs
Insignia.exe
Inscribes an MSI with the digital signatures that its external CAB files are signed with
Melt.exe
Converts a merge module (.msm) into a component group in a WiX source file
Torch.exe
Generates a transform file used to apply changes to an in-progress installation or to create a patch file
Shine
Creates a DGML diagram from an MSI
Smoke.exe
Runs validation checks on an MSI or MSM file
Pyro.exe
Creates a patch file (.msp) from .wixmsp and .wixmst files
WixCop.exe
Converts Version 2 WiX files to Version 3
WixUnit.exe
Validates WiX source files
Lux.exe and Nit.exe
Authors and runs unit tests on custom actions
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. Open a Windows command prompt and then type msiexec /? to bring up a window, as shown in the following screenshot:
If you'd like to install a newer version of Windows Installer, you can get it from the Microsoft Download Center website. Go to:
http://www.microsoft.com/downloads/en/default.aspx
Search for Windows Installer. The current version for Windows XP, Vista, Server 2003, and Server 2008 is 4.5. Windows 7, Windows Server 2008 R2, and Windows 8 can support Version 5.0. Each new version is backwards compatible and includes the features from earlier editions.
Visual Studio package (Votive)
The WiX toolset provides files that update Visual Studio to provide new WiX IntelliSense and project templates. Together these features, which are installed for you along with the other WiX tools, are called Votive. You must have Visual Studio 2005 or newer. Votive won't work on the Express versions. Refer to the WiX site for more information:
http://wix.sourceforge.net/votive.html
After you've installed WiX, you should see a new category of project types in Visual Studio labeled under the title Windows Installer XML, as shown in the following screenshot:
There are seven new project templates:
Using these templates is certainly easier than creating the files on your own with a text editor. To start creating your own MSI installer, select the template Setup Project. This will create a new .wxs (WiX source file) for you to add XML markup to. Once we've added the necessary markup, you'll be able to build the solution by selecting Build Solution from the Build menu or by right-clicking on the project in the Solution Explorer and selecting Build. Visual Studio will take care of calling candle.exe and light.exe to compile and link your project files.
If you right-click on your WiX project in Solution Explorer and select Properties, you'll see several screens where you can tweak the build process. One thing you'll want to do is set the amount of information that you'd like to see when compiling and linking the project, and how non-critical messages are treated. Refer to the following screenshot:
Here we're selecting the level of messages that we'd like to see. To see all warnings and messages, set Warning Level to Pedantic. You can also check the Verbose output checkbox to get even more information. Checking Treat warnings as errors will cause warning messages that normally would not stop the build to be treated as fatal errors.
You can also choose to suppress certain warnings. You'll need to know the specific warning message number though. If you get a build-time warning, you'll see the warning message, but not the number. One way to get it is to open the WiX source code (available at http://wix.codeplex.com/releases/view/93929) and view the messages.xmlfile in the src\wix\Data folder. Search the file for the warning and from there you'll see its number. Note that you can suppress warnings but not errors.
Another feature of WiX is its ability to run validity checks on the MSI package. Windows Installer uses a suite of tests called Internal Consistency Evaluators (ICEs) for this. These checks ensure that the database as a whole makes sense and that the keys on each table join correctly. Through Votive, you can choose to suppress specific ICE tests. Use the Tools Setting page of the project's properties as shown in the following screenshot:
In this example, ICE test 102 is being suppressed. You can specify more than one test by separating them with semicolons. To find a full list of ICE tests, go to MSDN's ICE Reference web page at:
http://msdn.microsoft.com/en-us/library/aa369206%28VS.85%29.aspx
The Tool Settings screen also gives you the ability to add compiler or linker command-line flags. Simply add them to the textboxes at the bottom of the screen. We will discuss command-line arguments for Candle and Light later in the book.
A word about GUIDs
In various places throughout WiX, you'll be asked to provide a GUID, which is a Globally Unique Identifier. This is so that when your product is installed on the end user's computer, references to it can be stored in the Windows Registry without the chance of having name conflicts. By using GUIDs, Windows Installer can be sure that every software application, and even every component of that software, has a unique identity on the system.
Each GUID that you create on your computer is guaranteed to be different from a GUID that someone else would make. Using this, even if two pieces of software, both called "Amazing Software", are installed on the same computer, Windows will be able to tell them apart.
Visual Studio 2010 provides a way to create a GUID. Go to Tools | Create GUID and copy a new GUID using Registry Format. WiX can accept a GUID with or without curly brackets around it, as 01234567-89AB-CDEF-0123-456789ABCDEF or {01234567-89AB-CDEF-0123-456789ABCDEF}. In this book, I'll display real GUIDs, but you should not re-use them as then your components will not be guaranteed to be unique.
Your first WiX project
To get started, download the WiX toolset. It can be found at:
http://wixtoolset.org/
Once you've downloaded and installed it, open Visual Studio and select New Project | Windows Installer XML | Setup Project. This will create a project with a single .wxs (WiX source) file. Visual Studio will usually call this file Product.wxs, but the name could be anything as long as it ends with .wxs.
Even the most minimal installer must have the following XML elements:
XML declaration and Wix element
Every WiX project begins with an XML declaration and a Wix element:
Tip
Downloading the example code
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.
The xmlns, or XML namespace, just brings the core WiX elements into the local scope of your document. At the bottom of the file you'll have to close the Wix element, of course. Otherwise, it's not valid XML. The Wix element is the root element of the document. It comes first and last. All other elements will be nested inside of it.
Note
For the most part, knowing only the basic rules of writing a well-formed XML document will be enough to get you up and running using WiX. The major points are as follows, as recommended by the W3C:
At this point, you could also add the RequiredVersion attribute to the Wix element. Given a WiX toolset version number, such as "3.6.3303.0", it won't let anyone compile the .wxs file unless they have that version or higher installed. If, on the other hand, you're the only one compiling your project, then it's no big deal.
The Product element
Next, add a Product element.
This is where you define the characteristics of the software you're installing: its name, language, version, and manufacturer. The end user will be able to see these properties by right-clicking on your MSI file, selecting Properties, and viewing the Summary tab. Most of the time, these values will stay the same from one build of your project to the next. The exception is when you want to increment the software's version to indicate that it's an upgrade of a previous installation. In that case, you need to only change the Version attribute, and sometimes the Id attribute. We'll talk more about upgrading previous installations later on in the book.
The Product element's Id attribute represents the so-called ProductCode of your software. It's always a unique number—a GUID—that Windows will use to uniquely identify your software (and tell if it's already installed on the computer). You can either hardcode it, like here, or just put an asterisk. That way, WiX will pick a new GUID for you each time you compile the project.
The Name attribute defines the name of the software. In addition to being displayed in the MSI file's Properties page, it will also be shown in various places throughout the user interface of your installer—that is, once you've added a user interface, which we'll touch on at the end of this chapter.
The Language attribute is used to display error messages and progress information in the specified language to the user. It's a decimal language ID (LCID). A full list can be found on Microsoft's LCID page at:
http://msdn.microsoft.com/en-us/goglobal/bb964664.aspx
The previous example used "1033", which stands for "English-United States". If your installer uses characters not found in the ASCII character set, you'll also need to add a Codepage attribute set to the code page that contains those characters. Don't worry too much about this now. We'll cover languages and code pages later in the book when we talk about localization.
The Version attribute is used to set the version number of your software. It can accept up to four numbers separated by periods. Typically, when you make a big enough change to the existing software, you'll increment the number. Companies often use the [MajorVersion].[MinorVersion].[Build].[Revision] format, but you're free to use any numbering system you like.
Note
During upgrade scenarios, the fourth digit in the Version attribute is ignored and won't make a difference when detecting previously installed software.
The Manufacturer attribute tells the user who this software is from and usually contains the name of your company. This is another bit of information that's available via the MSI file's Properties page.
The final attribute to consider is UpgradeCode. This should be set to a GUID and will identify your product across releases. It remains constant for a product line, even among different product versions. Think: Microsoft Office 2007 and Office 2010. Both would have the same UpgradeCode. Therefore, it should stay the same even when the ProductCode and Version change.
Windows will use this number in its efforts to keep track of all the software installed on the machine. WiX has the ability to search for previously installed versions of not only your own software, but also those created by others and it uses UpgradeCode to do it. Although, technically, this is an optional attribute, you should always supply it.
The Package element
Once you've defined your Product element, the next step is to nest a Package element inside. An example is shown as follows:
Of the attributes shown in this example, only Compressed is really required. By setting Compressed to yes, you're telling the installer to package all of the MSI's resources into CAB files. Later, you'll define these CAB files with Media elements or a MediaTemplate element.
Technically, an Id attribute is also required, but by omitting it you're letting WiX create one for you. You'd have to create a new one anyway since every time you change your software or the installer in any way, the package (the MSI file) has changed and so the package's ID must change. This really, in itself, emphasizes what the Package element is. Unlike the Product element, which describes the software that's in the installer, the Package element describes the installer itself. Once you've built it, you'll be able to right-click on the MSI and select Properties to see the attributes you've set here.
The InstallerVersion attribute can be set to require a specific version of msiexec.exe (the Windows Installer service that installs the MSI when you double-click on it) to be installed on the end user's computer. If they have an older version, Windows Installer will display a dialog telling them that they need to upgrade. It will also prevent you from compiling the project unless you also have this version installed on your own computer. The value can be found by multiplying the major version by 100 and adding the minor version. So, for Version 4.5 of msiexec.exe, you'd set InstallerVersion to 405.
The InstallScope attribute can be set to either perMachine or perUser. The former means that your software will be installed in the "All Users" context, meaning that all users will be able to access your application. As such, the person performing the install will need elevated privileges on a UAC enabled system such as Windows 7 to continue the installation. The latter means that it will be installed only for the current user. Behind the scenes this is setting a WiX property called ALLUSERS that we'll cover in more detail later when we discuss properties.
The rest of the attributes shown provide additional information for the MSI file's Properties window. Manufacturer is displayed in the Author text field, Description is shown as Subject, Keywords show up as Keywords, and Comments show as Comments. It's usually a good idea to provide at least some of this information, if just to help you distinguish one MSI package from another.
The MediaTemplate element
The files that you intend to install are compressed into CAB files and shipped along with the installer. You decide whether to embed them inside the MSI or provide them visibly alongside it. In WiX 3.6, a single MediaTemplate element handles all the details for you, intelligently splitting your files into the prescribed number of CAB files. Add it after the Package element, as shown in the following code snippet:
The EmbedCab attribute is optional and sets whether the CAB files will be embedded inside the MSI, the default being to not embed them. Either way, WiX will create up to 999 CAB files, each holding a maximum of 200 MB of data. You can change that limit with the MaximumUncompressedMediaSize attribute, set to a size in megabytes. If a single file is bigger than the maximum, it will be placed into its own CAB file with enough space to accommodate it.
If you want to split your installation up into several physical disks—conjure up images of "Please insert disk 2"—you want to use the Media element instead.
The Media element
The Media element is an older element that was replaced by MediaTemplate and if you use one you can't use the other. However, in some cases, the Media element is the only thing for the job. For each Media element that you add to your WiX markup, a new CAB file will be created.
Each Media element gets a unique Id attribute to distinguish it in the MSI Media table. It must be a positive integer. If the files that you add to your installation package don't explicitly state which CAB file they wish to be packaged into, they'll default to using a Media element with an Id value of 1. Therefore, your first Media element should always use an Id value of 1.
The Cabinet attribute sets the name of the CAB file. You won't actually see this unless you set EmbedCab to no, in which case the file will be shipped alongside the MSI. This is atypical, but might be done to split the installation files onto several disks.
If you do choose to split the installation up into several physical disks (or even virtual ISO images), you'll want to add the DiskPrompt and VolumeLabel attributes. In the following example, I've added two Media elements instead of one. I've also added a Property element above them, which defines a variable called DiskPrompt with a value of Amazing Software - [1].
The Property element will be used as the text in the message box the end user sees, prompting them to insert the next disk. The text in the DiskPrompt attribute is combined with the text in the property's value, switched with [1], to change the message for each subsequent disk. Make sure you give this property an Id value of DiskPrompt.
So that Windows will know when the correct disk is inserted, the VolumeLabel attribute must match the "Volume Label" of the actual disk, which you'll set with whichever CD or DVD burning program you use. Once you've built your project, include the MSI file and the first CAB file on the first disk. The second CAB file should then be written to a second disk.
Although we haven't described the File element yet, it's used to add a file to the installation package. To include one in a specific CAB file, add the DiskId attribute, set to the Id attribute of the corresponding Media element. The following example includes a text file called myFile.txt in the media2.cab file:
We'll discuss the File element in more detail later on in the chapter. If you're only using one Media element, you won't need to specify the DiskId attribute on your File elements.
The Directory element
So, now we've defined the identity of the product, set up its package properties, and told the installer to create a CAB file to package up the things that we'll eventually install. Then, how do you decide where your product will get installed to on the end user's computer? How do we set the default install path, for example, to some folder under Program Files?
When you want to install to C:\ProgramFiles, you can use a sort of shorthand. There are several directory properties provided by Windows Installer that will be translated to their true paths at install time. For example, ProgramFilesFolder usually translates to C:\ProgramFiles. The following is a list of these built-in directory properties:
Directory property
Actual path
AdminToolsFolder
Full path to directory containing administrative tools
AppDataFolder
Full path to roaming folder for current user
CommonAppDataFolder
Full path to application data for all users
CommonFiles64Folder
Full path to the 64-bit Common Files folder
CommonFilesFolder
Full path to the Common Files folder for current user
DesktopFolder
Full path to the Desktop folder
FavoritesFolder
Full path to the Favorites folder for current user
FontsFolder
Full path to the Fonts folder
LocalAppDataFolder
Full path to folder containing local (non-roaming) applications
MyPicturesFolder
Full path to the Pictures folder
NetHoodFolder
Full path to the NetHood folder
PersonalFolder
Full path to the Documents folder for current user
PrintHoodFolder
Full path to the PrintHood folder
ProgramFiles64Folder
Full path to the 64-bit Program Files folder
ProgramFilesFolder
Full path to 32-bit Program Files folder
ProgramMenuFolder
Full path to Program Menu folder
RecentFolder
Full path to Recent folder
SendToFolder
Full path to the SendTo folder for current user
StartMenuFolder
Full path to the Start Menu folder
StartupFolder
Full path to the Startup folder
System16Folder
Full path to the 16-bit system DLLs folder
System64Folder
Full path to the System64 folder
SystemFolder
Full path to the System folder for current user
TempFolder
Full path to the Temp folder
TemplateFolder
Full path to the Template folder for current user
WindowsFolder
Full path to the Windows folder
Tip
This list can also be found at:
http://msdn.microsoft.com/en-us/library/windows/desktop/aa370905(v=vs.85).aspx
The easiest way to add your own directories is to nest them inside one of the predefined ones. For example, to create a new directory called InstallPractice inside the ProgramFiles folder, you could add it as a child to ProgramFilesFolder. To define your directory structure in WiX, use Directory elements:
One thing to know is that you must start your Directory elements hierarchy with a Directory element with an Id attribute of TARGETDIR and a Name value of SourceDir. This sets up the "root" directory of your installation. Therefore, be sure to always create it first and nest all other Directory elements inside.
By default, Windows Installer sets TARGETDIR to the local hard drive with the most free space—in most cases, the C: drive. However, you can set TARGETDIR to another drive letter during installation. You might, for example, set it with a VolumeSelectCombo user interface control. We'll talk about setting properties and UI controls later in the book.
A Directory element always has an Id attribute that will serve as a primary key on the Directory table. If you're using a predefined name, such as ProgramFilesFolder, use that for Id. Otherwise, you can make one up yourself. The previous example creates a new directory called InstallPractice, inside the ProgramFiles folder. Id, MyProgramDir, is an arbitrary value.
When creating your own directory, you must provide the Name attribute. This sets the name of the new folder. Without it, the directory won't be created and any files that were meant to go inside it will instead be placed in the parent directory—in this case, ProgramFiles. Note that you do not need to provide a Name attribute for predefined directories.
You can nest more subdirectories inside your folders by adding more Directory elements. The following is an example:
Here, a subdirectory called Subdirectory1 is placed inside the InstallPractice folder. A second subdirectory, called Subdirectory2, is then placed inside Subdirectory1, giving us two levels of nested directories under InstallPractice.
Note
If you've been following along using the Visual Studio Setup Project template, you'll notice that it places its boilerplate Directory elements inside of a Fragment element. We will discuss Fragment in the next chapter.
Before jumping into how to add files to your new directories, we should cover the elements that define the files themselves. The next section covers how to create components, which are the containers for the files you want to install.
The Component element
Once you've mapped out the directories that you want to target or create during the installation, the next step is to copy files into them. To really explain things, we'll need something to install. So let's create a simple text file and add it to our project's directory. We'll call it InstallMe.txt. For our purposes, it doesn't really matter what's in the text file. We just need something for testing.
Windows Installer expects every file to be wrapped up in a component before it's installed. It doesn't matter what type of file it is either. Each gets its own Component element.
Components, which always have a unique GUID, allow Windows to track every file that gets installed on the end user's computer. During an installation, this information is stored away in the registry. This lets Windows find every piece of your product during an uninstall so that your software can be completely removed. It also uses it to replace missing files during a repair, which you can trigger by right-clicking on an MSI file and selecting Repair.
Each Component element gets a unique GUID via its Guid attribute. To create a GUID in Visual Studio, go to Tools | Create GUID and copy a new GUID using the registry format. The component's Id attribute is up to you. It will serve as the primary key for the component in the MSI database, so each one must also be unique:
In the preceding code snippet, I've created a new component called CMP_InstallMeTXT. I've started it with CMP_ to label it as a component, which is just a convention that I like to use. Although it isn't required, it helps to prefix components in this way so that it's always clear what sort of element it refers to.
The File element inside the component references the file that's going to be installed. Here, it's the InstallMe.txt file located in the current directory (which is the same directory as your WiX source file). You can specify a relative or absolute path with the Source attribute.
You should always mark a File element as the KeyPath file and you should only ever include one File inside a component. A KeyPath file will be replaced if it's missing when the user triggers a repair (Windows Installer documentation calls this resiliency). Placing more than one File element inside a single Component element, at least in most cases, is not recommended. This is because only one file can be the KeyPath file, so the other files wouldn't be covered by a repair. You would really only ever place more than one File in a component if you didn't want the extra files to be resilient.
To add a component to a directory, you have several options. The first, which is the simplest, is to add your Component elements directly inside the target Directory element, as given in the following code snippet:
In the previous code snippet, I've instructed the installer to copy the InstallMe.txt file to the %ProgramFiles%\Install Practice folder that we're creating on the end user's computer. Although this is the simplest solution, it isn't the cleanest. For one thing, if you're installing more than a handful of files, the XML file can begin to look tangled.
Another approach is to use a DirectoryRef element to reference your directories. This has the benefit of keeping the markup that defines your directories independent from the markup that adds files to those directories. The following is an example:
A third option is to group your components inside of a ComponentGroup and use its Directory attribute to set the target directory. We will cover component groups in more detail in the next chapter, but the following snippet will give you an idea:
The File element
As you've seen, the actual files inside components are declared with File elements. The File elements can represent everything from simple text files to complex DLLs and executables. Remember, you should only place one file into each component. The following example would add a file called SomeAssembly.dllto the installation package:
A File element should always get the Source attribute. Source
