Windows Installer XML (WiX) - Documentation & Help

Transcription

Introduction to Windows InstallerXML (WiX) toolsetWhat is WiX?WiX is a set of tools that allows you to create Windows Installer-baseddeployment packages for your application. The WiX toolset is based on adeclarative XML authoring model. You can use WiX on the command lineby using the WiX tools or MSBuild. In addition, there is also a WiX VisualStudio plug-in that supports VS2005, VS2008, and VS2010. The WiXtoolset supports building the following types of Windows Installer files:Installer (.msi)Patches (.msp)Merge Modules (.msm)Transforms (.mst)WiX supports a board spectrum of Windows Installer features. Inaddition, WiX also offers a set of built-in custom actions that can be usedand incorporated in Windows Installer packages. The custom actions areoffered in a set of WiX extensions. Some common WiX extensionsinclude support for Internet Information System (IIS), Structured QueryLanguage (SQL), the .NET Framework, Visual Studio, and Windows etc.

How does WiX work?The WiX source code is written in XML format with a .wxs file extension.The WiX tools follow the traditional compile and link model used to createexecutables from source code. At build time, the WiX source files arevalidated against the core WiX schema, then processed by apreprocessor, compiler, and linker to create the final result. There are aset of WiX tools that can be used to produce different output types. For acomplete list of file types and tools in WiX, see the File Types and the Listof Tools sections.Using WiX on the Command LineUsing WiX in Visual StudioUsing WiX with MSBuildUsing WiX with NAntHow To GuidesWiX Schema ReferenceAdvanced WiX TopicsDeveloping for WiXAdditional Resources

Getting StartedThere are several options available to get started learning how to useWiX.

Basic WalkthroughTo get started, you can go to the Creating Installation Packages sectionwhich includes a step-by-step walkthrough to create a simple packageusing WiX.

How To GuidesThis help file includes a set of How To Guides that explain how toaccomplish common Windows Installer tasks using WiX.

TutorialsIf you prefer to learn from a tutorial, the following options are available:Using the WiX Toolset to Integrate Setup into Your DevelopmentProcesshttp://www.tramontana.co.hu/wix/ Note that this tutorial is currentlytargeted at WiX 2.0. This tutorial is a great way to ramp up on theWiX toolset if you are new to WiX or are looking for answers tocommon authoring questions.If you prefer to learn from audio-visual presentations, the followingoptions are available:Blog introduction with videoVideo on Channel 9MSDN Radio broadcast

CommunityIf you prefer to learn by interacting with the community, there is a WiXusers mailing list at sers.

Integrated Development EnvironmentIf you prefer to learn by using an integrated development environment,there is an overview of WiX editors WiX-editors.aspx.

Reverse EngineeringIf you prefer to learn by working backward from a Windows Installerpackage you have already created, you can run the WiX decompiler(Dark) to convert your package into WiX authoring and then recompile itusing the WiX compiler (Candle) and WiX linker (Light).

Reading Source CodeIf you prefer to learn by reading code, WiX is an open source project, andyou can look at the source code by reviewing the How to be a WindowsInstaller XML Developer topic.

Fix a Bug, Write a FeatureIf you prefer to learn by writing code, you can review the following WiXissue trackers:Bugs - http://sourceforge.net/tracker/?group id 105970&atid 642714Features - http://sourceforge.net/tracker/?group id 105970&atid 642717For WiX development assistance, there is a WiX developer mailing list um name wix-devs.

Getting HelpPlease see http://wix.sourceforge.net/ for more information about the WiXtoolset. This site includes the following information:1. Links to download weekly releases of the WiX toolset.2. The WiX bug database where you can report new bugs or check thestatus of existing bugs.3. Mailing lists to ask questions, make suggestions or discuss the WiXtoolset with other users and the WiX developers.4. Links to blogs maintained by the WiX developers.

Tools and ConceptsThe WiX toolset is tightly coupled with the Windows Installer technology.In order to fully utilize the features in WiX, you must be familiar with theWindows Installer concepts. This section assumes you have a workingknowledge of the Windows Installer database format. For information onWindows Installer, see Useful Windows Installer Information.

WiX File TypesThere is a set of tools that WiX offers to fulfill the needs of buildingWindows Installer-based packages. Each tool outputs a type of file thatcan be consumed as inputs of another tool. After processing through theappropriate tools, the final installer is produced.To get familiar with the WiX file types, see File Types.

WiX ToolsOnce you are familiar with the file types, see how the file types areproduced by what WiX tools by visiting List of Tools. For a graphical viewof the WiX tools and how they interact with each other, see WiX ToolsetDiagram.

WiX SchemaThe core WiX schema is a close mirror with the MSI tables. For helpfulhints on how the WiX schema maps to MSI tables, see MSI Tables toWiX Schema.

File TypesThere are many file types in WiX that are generated from different tools inthe toolset. At the highest level, all input files and intermediate files forWiX are XML files. The final output is in the form of standard WindowsInstaller database files.For example, to build an MSI or MSP, the compiler processes the sourcefiles (.wxs and .wxi) and produces object files (.wixobj). These objectsfiles are then consumed by the linker, which produces Windows Installerdatabase files (.msi or .msm). This is analogous to the C model ofcompiling source code to object files, then linking to produceexecutables.

List of file typesThe following list describes the supported file types in WiX:Extension TypeDescription.wxiWiXA .wxi file is analogous to .h files for C . TheInclude File root element of this file is Include . Everythingunder the root element will be inserted inlinewhen this file is included in another source orinclude file.wxlWiXA .wxl file contains a set of strings used forLocalization localizing a product into a specified culture. TheFileroot element of this file is WixLocalization .The culture is specified by setting the Cultureattribute on the WixLocalization element.wxsWiX Source A .wxs file is analogous to a .cpp file for C .FileThe Root element of this file is Wix . For moredetail, see Additional Information below.wixobjWiX Object A .wixobj file is created by the compiler for eachFilesource file compiled. The .wixobj file containsone or more sections that, in turn, containsymbols and references to other symbols. Formore detail, see Additional Information below.wixoutWiX XML A .wixout file is created by the linker whichOutput File represents the result of linking a set of objectfiles. The .wixout is an XML representation ofthe final output.wixlibWiX Library A .wixlib file is a library of setup functionalityFilethat can be easily shared across different WiX-

based packages by including it when linking thesetup package.wixpdbWiX Debug A .wixpdb file is created by the linker for eachFilefinal output. It contains the debugginginformation.wixmspWiX XMLPatch FileA .wixmsp file is the XML output generated bylinking object files in a patch build.wixmstWiXTransformFileA .wixmst file is an XML representation of thedifference between a pair of final outputs orXML outputs.msiWindowsAn installation package file (.msi) is the basicInstallerunit of installation for the Windows ergeModuleA merge module file (.msm) is used to sharesetup logic across different .msi packages. Amerge module can be created by onedevelopment team, then merged into anotherdevelopment team's .msi package.mstWindowsInstallerTransformA transform file (.mst) is used to apply changesto an .msi file.pcpWindowsInstallerPatchCreationProcessA patch creation properties file (.pcp) is used asan input to the patch building tools provided inthe Windows Installer SDK.

Additional InformationStructure of .wxs filesAll .wxs files are well-formed XML documents that contain a single rootelement named Wix/ . The rest of the source file may or may notadhere to the WiX schema before preprocessing. However, after beingpreprocessed all source files must conform to the WiX schema or theywill fail to compile.The root Wix element can contain at most one of the followingelements as children: Product , Module , and Patch . However,there can be an unbounded number Fragment elements as children ofthe root Wix element. When a source file is compiled into an object file,each instance of these elements creates a new section in the object file.Therefore, these three elements are often referred to as sectionelements.It is important to note, that there can be only one Product or Module or Patch section element per source file because they are compiledinto special sections called entry sections. Entry sections are used asstarting points in the linking process. Sections, entry sections, and theentire linking process are described in greater detail later in thisdocument.The children of the section elements define the contents of the WindowsInstaller database. You’ll recognize Property elements that map toentries in the Property table and a hierarchy of Directory elements thatbuild up the Directory table. Most elements contain an “Id” attribute thatwill act as the primary key for the resulting row in the Windows Installerdatabase. In most cases, the “Id” attribute also defines a symbol whenthe source file is compiled into an object file.Symbols and referencesEvery symbol in an object file is composed of the element name plus theunique identifier from the “Id” attribute. Symbols are important becausethey can be referenced by other sections from any source file. For

example, a Directory structure can be defined in a Fragment in onesource file and a Component can be defined under a different sourcefile’s Fragment . By making the DirectoryRef element a parent of the Component an explicit reference is created that references the symboldefined by a Directory in the first source file. The linker is thenresponsible for stitching the symbol and the reference together in a singleWindows Installer database. In some cases, implicit references aregenerated by the compiler while processing a source file. These implicitreferences behave identically to explicit references.In addition to the simple references described above, WiX supportsspecific complex references. Complex references are used in caseswhere the linker must generate extra information to link the symbol andreference together. The perfect example of a complex reference is in theWindows Installer’s Feature/Component relationship. When a Component is referenced explicitly by a Feature through a ComponentRef element, the linker must take the Feature ’s symboland the Component ’s symbol and add an entry to theFeatureComponents table.This Feature/Component relationship is even more complex becausecertain elements in a Component , for example Shortcut , havereferences back to the primary Feature associated with the Component.These references from a child element of a Component are calledreverse references or sometimes feature backlinks. Processing complexreferences and reverse references is probably the most difficult work thelinker has to do.Structure of the .wixobj fileA .wixobj file is created by the compiler for each source file compiled. The.wixobj file is an XML document that follows the objects.xsd schemadefined in the WiX project. As stated above the .wixobj file contains oneor more sections that, in turn, contain symbols and references to othersymbols.While the symbols and references are arguably the most importantpieces of data in the .wixobj file, they are rarely the bulk of theinformation. Instead, most .wixobj files are composed of table , row and field elements that provide the raw data to be placed in theWindows Installer database. In many cases, the linker will not only

process the symbols and references but also use and update the rawdata from the .wixobj file. It is interesting to note that the object fileschema, objects.xsd, uses camel casing where the source file schema,wix.xsd, uses Pascal casing. This was a conscious choice to indicate thatthe object files are not intended to be edited by the user. In fact, allschemas that define data to be processed only by the WiX tools usecamel casing.

List of ToolsTo view the usage information of the tools, run /? on the tool via thecommand line.NameDescriptionCandle Preprocesses and compiles WiX source files into object files(.wixobj). For more information on compiling, see Compiler. Formore information on preprocessing, see Preprocessor.LightLinks and binds one or more .wixobj files and creates aWindows Installer database (.msi or .msm). When necessary,Light will also create cabinets and embed streams into theWindows Installer database it creates. For more information onlinking, see Linker.LitCombines multiple .wixobj files into libraries that can beconsumed by Light.DarkConverts a Windows Installer database into a set of WiX sourcefiles. This tool is very useful for getting all your authoring into aWiX source file when you have an existing Windows Installerdatabase. However, you will then need to tweak this file toaccomodate different languages and breaking things intofragments.HeatGenerates WiX authoring from various input formats. It is usedfor harvesting files, Visual Studio projects and InternetInformation Server web sites, "harvesting" these files intocomponents and generating Windows Installer XML Sourcefiles (.wxs). Heat is good to use when you begin authoring yourfirst Windows Installer package for a product.Insignia Inscribes an installer database with information about the digitalcertificates its external cabs are signed with. For more

information, see Insignia.MeltConverts an .msm into a component group in a WiX source file.TorchPerforms a diff to generate a transform (.wixmst or .mst) forXML outputs (.wixout or .wixpdb) or .msi files.Smoke Runs validation checks on .msi or .msm files.PyroTakes an XML output patch file (.wixmsp) and one or more XMLtransform files (.wixmst) and produces an .msp file.WixCop Enforces standards on WiX source files. WixCop can also beused to assist in converting a set of WiX source files createdusing an older version of WiX to the latest version of WiX. Formore information, see WixCop.WixUnit Runs validations on a set of XML files and the expected outputfile. Takes a set of WiX source files and an expected MSI as theinput and outputs Pass/Fail.

Response filesAll WiX command-line tools support response files, which are text filesthat contain command-line switches and arguments. Anything you canput on a WiX tool command line can instead go into a response file.Response files are useful when you have command lines that are toolong for your command shell. For example, you might want to generate aresponse file that contains command-line switches and the files that youwant to compile with candle.exe:-nologo -wx1.wxs2.wxs3.wxsand issue a command like:candle @listOfFiles.txtSpecify a response file with the @ character, followed immediately by thepathname of the response file, with no whitespace in-between. Responsefiles can appear at the beginning, in the middle, or at the end ofcommand line arguments.

WiX Toolset DiagramBelow is a diagram showing the relationship of all of the WiX tools andthe output that they generate.

PreprocessorOften you will need to add different pieces of your setup during build timedepending on many factors such as the SKU being built. This is done byusing conditional statements that will filter the xml before it is sent to theWiX compiler (candle). If the statement evaluates to true, the block of xmlwill be sent to candle. If the statement evaluates to false, candle willnever see that section of xml.The conditional statements are Boolean expressions based onenvironment variables, variables defined in the xml, literal values, andmore.ExampleLet’s start with an example. Say you want to include a file if you’rebuilding the “Enterprise SKU.” Your build uses an environment variable%MySku% Enterprise to specify this sku.When you build the enterprise sku, this file will be included in the xmlpassed on to candle. When you build a different sku, the xml fromEnterpriseFeature.wxs will be ignored. ?if (env.MySku) Enterprise ? ?include EnterpriseFeature.wxs ? ?endif ?

Include Files ?include? As shown in the example above, files can be included by using theinclude tag. The filename referenced in the tag will be processed as if itwere part of this file.The root element of the include file must be Include . There are noother requirements beyond the expected wix schema. For example, Include Feature Id 'MyFeature' Title 'My 1st Feature' Level '1' ComponentRef Id 'MyComponent' / /Feature /Include

VariablesAny variable can be tested for its value or simply its existence. Customvariables can also be defined in your xml.Three types of variables are supported: (env. NtPostBld)Gets the environment variable % NtPostBld% (sys.CURRENTDIR)Gets the system variable for the current directory (var.A)Gets the variable A that was defined in this xmlThe preprocessor evaluates variables throughout the entire document,including in ?if? expressions and attribute values.Environment VariablesAny environment variable can be referenced with the syntax (env.VarName). For example, if you want to retrieve the environmentvariable % BuildArch%, you would use (env. BuildArch). Environmentvariable names are case-insensitive.System VariablesWiX has some built-in variables. They are referenced with the syntax (sys.VARNAME) and are always in upper case.CURRENTDIR - the current directory where the build process isrunningSOURCEFILEPATH – the full path to the file being processedSOURCEFILEDIR – the directory containing the file being processedPLATFORM – the platform (Intel, x64, Intel64) this package iscompiled for (set by the Package element's Platform attribute)NOTE: All built-in directory variables are “\” terminated.

Custom variables ? define ? If you want to define custom variables, you can use the ?define? statement. You can also define variables on the command line usingcandle.exe using the -d switch. Later, the variables are referred to in the ?if? statements with the syntax (var.VarName). Variable names arecase-sensitive.How to define the existence of a variable: ?define MyVariable ? How to define the value of a variable (note: quotes are required if thevalue or the expansion of other variables in the value contain spaces): ?define MyVariable “Hello World” ? ?define MyVariable “ (var.otherVariableContainingSpaces)” ? The right side of the definition can also refer to another variable: ?define MyVariable (var.BuildPath)\x86\bin\ ? How to undefine a variable: ?undef MyVariable ? To define variables on the command line, you can type a commandsimilar to the following:candle.exe -dMyVariable "Hello World" .You can refer to variables in your source that are defined only on thecommand line, but candle.exe will err when preprocessing your sourcecode if you do not define those variables on the command line.

Conditional StatementsThere are several conditional statements, they include: ?if ? ?ifdef ? ?ifndef ? ?else? ?elseif ? ?endif? The purpose of the conditional statement is to allow you to include orexclude a se

The WiX source code is written in XML format with a .wxs file extension. The WiX tools follow the traditional compile and link model used to create executables from source code. At build time, the WiX source files are validated against the core WiX schema, then processed by a preprocessor, c