WiX Tutorial (2/7)


Properties are the variables used to store data needed during an installation. There are several built-in properties and more can be declared by the developer in his WiX source files.

Element References

Some of the elements defined in a WiX source file can be referenced from other parts of the source file by using the corresponding reference element. For instance in our first example, we used the ComponentRef element to reference a Component element. Other examples are UI and UIRef, Directory and DirectoryRef and Property and PropertyRef.


References are particularly useful when used in conjunction with fragments. The Fragment element is a container in which other elements can be defined. These elements can then be referenced using the corresponding Ref element. This technique can be used to better organize large installers by splitting the source into several files for instance.

Looking at the WiX schema [1] you can see that the <Wix> element in a WiX source file can contain an optional <Product> element followed by any number of <Fragment> elements. This means that you can have files containing only fragments whose contents can then be referenced in other Wix source files. This should come as no surprise as the WiX build process follows the same principles as the compilation and linking stage of some programming languages like C. Note that there is no concept of "header files" as in C or C++ and that you don't need to include a file to use its elements, the WiX toolchain will look for the referenced elements in all the .wixobj files that are passed to light.exe.

We have rewritten our previous example, SingleFileInstallation1, to use a <Fragment> element that we have out in a separate file. Both files are reproduced below. The full example is available from our Codeplex repository at WiX/Basics/Fragments1.

File: Fragments1.wxs
<?xml version="1.0" encoding="UTF-8"?>
<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">

    <Product Id="0C6F4EF7-7B03-49FA-9FF6-BAAFCFCBCF4A" Name="Fragments1" Language="1033" 
        Version="" Manufacturer="Needful Software" UpgradeCode="2B7E0978-680A-43A5-A0D0-98CF921EE4E5">

        <Package InstallerVersion="200" Compressed="yes" InstallScope="perMachine" />
        <MediaTemplate EmbedCab="yes" />

        <Feature Id="MainProduct" Title="Fragments 1" Level="1">
            <ComponentRef Id="HelloWorldComponent" />


File: Files.wxs
<?xml version="1.0" encoding="UTF-8"?>
<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">


    <Directory Id="TARGETDIR" Name="SourceDir">
      <Directory Id="ProgramFilesFolder">
        <Directory Id="NeedfulSoftwareDir" Name="Needful Software">
          <Directory Id="Fragments1Dir" Name="Fragments 1">

            <Component Id="HelloWorldComponent" Guid="118B788F-0D94-4F07-B845-6AB70224C3FB">
              <File Id="HelloWorldFile" Source="HelloWorld.txt" KeyPath="yes" />




We now have two source files so we need to pass them both to candle.exe and light.exe as shown below. We also have to use the -o option with light.exe to specify the name of the output file.

Command line
C:\WiX\Examples\Fragments1>candle.exe Fragments1.wxs Files.wxs
Windows Installer XML Toolset Compiler version 3.8.1128.0
Copyright (c) Outercurve Foundation. All rights reserved.


C:\WiX\Examples\Fragments1>light.exe Fragments1.wixobj Files.wixobj -o Fragments.msi
Windows Installer XML Toolset Linker version 3.8.1128.0
Copyright (c) Outercurve Foundation. All rights reserved.



  1. WiX Toolset: Wix Element

blog comments powered by Disqus

Copyright(c) 2006-2017 Xavier Leclercq | Privacy policy

Contact Us