WiX 3.6: A Developer's Guide to Windows Installer XML: An all-in-one introduction to Windows Installer XML from the installer and beyond

The File element, as you've seen, is used to designate each file that you plan to copy to the end user's computer. At a minimum, it should contain a Source attribute that identifies the path to the file on your development machine, as shown:

<Component Id="CMP_MyProgramEXE"
           Guid="2C34F22F-1F48-4949-B68B-939F852F8B35">
  <File Source="MyProgram.exe" />
</Component>

There are a number of optional attributes available. The Name attribute tells the installer what the file will be called after it's installed. If omitted, the file will retain its original name as specified in the Source attribute. The KeyPath attribute explicitly marks the file as the keypath for the component, although if there is only one File element in Component it will, by default, be the keypath. The Id attribute uniquely identifies the file in the MSI database's File table. The following is an example that demonstrates these attributes:

<Component Id="CMP_MyProgramEXE"
   ...

In the previous chapter, you saw that to define which directories to copy your files into, you use Directory elements. These take an Id value and, if it's a new directory that you're creating, a Name attribute. You can use any of the built-in IDs to reference one of the common Windows directories. For example, suppose we wanted to add an XML configuration file for our software to the %PROGRAMDATA% folder. We'd add a reference to it using the built-in CommonAppDataFolder property as Directory Id:

<Directory Id="TARGETDIR" Name="SourceDir">
   <Directory Id="CommonAppDataFolder">
      <Directory Id="MyCommonAppDataFolder" 
                 Name="Awesome Software" />
   </Directory>
</Directory>

Here we are placing a new folder called Awesome Software inside the %PROGRAMDATA% folder. The new folder gets a Name attribute to label it. The Id attribute is up to us and uniquely identifies the directory in the MSI database. To add a file to...

The ComponentGroup element is used to group Component elements, which is helpful as it offers a way to reference all of your components with a single element. For example, when adding components to Feature (which you must always do), you could use ComponentRef elements directly. This is the technique we used in the previous chapter:

<Feature Id="ProductFeature"
         Title="Main Product"
         Level="1">
  <ComponentRef Id="CMP_MyProgramEXE" />
  <ComponentRef Id="CMP_AnotherFileDLL" />
</Feature>

However, by creating ComponentGroup, you can reference multiple components with a single ComponentGroupRef element. This is shown in the following snippet:

<Feature Id="ProductFeature"
         Title="Main Product"
         Level="1">
  <ComponentGroupRef Id="MyComponentGroup" />
</Feature>

Try it out by adding a new CompontGroup element to your .wxs file. It can go anywhere inside the Product element. Then, you have a choice...

Up to this point, we've been adding all of our WiX elements to the Product.wxs file. When your installer packages hundreds of files, you'll find that having all of your code in one place makes reading it difficult. You can split your elements up into multiple .wxs files for better organization and readability. Whereas your main source file, Product.wxs, nests everything inside a Product element, your additional .wxs files will use Fragment elements as their roots.

The Fragment element doesn't need any attributes. It's simply a container. You can place just about anything inside of it, such as all of your Directory elements or all of your Component elements. For the next example, add a new WiX source file to your project and place the following markup inside it. Here, we're using the same ComponentGroup that we discussed earlier. You can call the file Components.wxs, and it should look something like the following code snippet:

<?xml version="1.0" encoding="UTF-8"?&gt...

When your project contains many files to install, it can be a chore to create File and Component elements for all of them. Instead, WiX can do it for you. One of the tools that ships with the toolset is called heat.exe. You can find it in the bin directory of the WiX program files. Navigate to WiX's bin directory from a command prompt and type heat.exe -? to see information about its usage.

To make things easy, consider adding the path to the WiX bin directory to your computer's PATH environment variable so that you won't have to reference the full path to the executable each time you use it. You can do this on Windows 7 by right-clicking on My Computer in your Start Menu and then going to Properties | Advanced system settings | Environment Variables. From there, you can add the WiX bin path, C:\Program Files (x86)\WiX Toolset v3.6\bin, to PATH by finding PATH in the list of system variables and clicking on Edit.

File and Component elements allow you to add new files to the end user's computer. However, WiX also provides ways to copy and move files. For these tasks, you'll use the CopyFile element. We'll discuss how to use it in the following sections.

<Directory Id="TARGETDIR"
           Name="SourceDir">
  <Directory Id="ProgramFilesFolder">
    <Directory Id="MyProgramDir"
               Name="Awesome Software">
      <Directory Id="CopiedFiles"
                 Name="Copied Files" />
    </Directory>
  </Directory>
</Directory>

In the following sections, we'll take a look at installing files that are different from other types that we've talked about so far. Specifically, we'll cover how to install an assembly file (.dll) to the Global Assembly Cache and how to install a TrueType font file.

<DirectoryRef Id="MyProgramDir">
  <Component Id="CMP_MyAssembly" 
             Guid="4D98D593-F4E0-479B-A7DA-80BBB78B54CB">
    <File Id="File_MyAssembly"
          Assembly=".net" 
          Source="MyAssembly.dll"
          KeyPath="yes" />
  </Component>
</DirectoryRef>

Let's say that you have a .NET assembly that's targeting the x64 platform and you want the installer for it to place that file into the 64-bit Program Files folder (available on 64-bit Windows operating systems). For the uninitiated: you can set the platform for the assembly using Visual Studio's Configuration Manager, as shown in the following screenshot:

The first thing to do is to open Properties for the WiX project and, on the Tools Settings tab, add –arch x64 to the Compiler parameters, as shown in the following screenshot:

Next, change the Directory element that is referencing ProgramFilesFolder to instead reference ProgramFiles64Folder, given as follows:

<Directory Id="TARGETDIR" Name="SourceDir">
  <Directory Id="ProgramFiles64Folder">
    <Directory Id="INSTALLFOLDER" Name="My Software" />
  </Directory>
</Directory>

Now your 64-bit assembly can be put into this directory. WiX detects the architecture of the .NET assemblies for...

Ordinarily, Windows Installer won't let you create empty folders. However, there is a way: Use the CreateFolder element inside an otherwise empty Component element. First, you'll define the name of your empty directory with a Directory element. Follow this example:

<Directory Id="TARGETDIR"
           Name="SourceDir">
  <Directory Id="ProgramFilesFolder">
    <Directory Id="MyProgramDir"
               Name="Awesome Software">
      <Directory Id="MyEmptyDir"
                 Name="Empty Directory" />
    </Directory>
  </Directory>
</Directory>

In the example, we've added a new Directory element named Empty Directory inside our main application folder. The next step is to add a component to this directory by using a DirectoryRef element. Notice that we've set the KeyPath attribute on the component to yes, as there will be no file to serve this purpose:

<DirectoryRef Id="MyEmptyDir">
  <Component Id="CMP_MyEmptyDir...

WiX allows you to set the permissions that Windows users and groups have to the files that you install. You can see these permissions by right-clicking on a file and selecting the Security tab. On Windows XP, you may have to configure your system so that this tab is visible. In Windows Explorer, open the folder that you want to configure and go to Tools | Folder Options | View. Then, uncheck the box that says Use simple file sharing. The following is an example of the Security tab on a file:

To set the permissions for a file that you're installing, nest a PermissionEx element inside the corresponding File element. This element, which is available from WixUtilExtension, has various attributes that can be used to define file permissions. Before you can use it, you'll need to add a reference to WixUtilExtension.dll in your project. Go to Add Reference in Solution Explorer and select the WiXUtilExtension assembly. Next, add the following namespace to your Wix element...

We haven't talked too much about how the files and directories that you author in your WiX source files are stored in the MSI database's tables. The files are stored in a table called File, the directories in a table called Directory, and the components in a table called Component. You can see this by opening the MSI package with Orca.exe.

In the following example, I have four files that are being installed. I've used the convention of prefixing my file IDs with FILE_, giving me FILE_InstallMeTXT, for example:

Each file in the File table is sorted alphabetically by the Id value you gave to it via the File element. This is the order in which the files are copied to the end user's computer. So, how can you make things faster? You can give your files IDs that will cause WiX to sort them more efficiently.

The file copy process takes longer when Windows has to write to one directory and then switch to another and then another and so on. If it could copy all of the...

In this chapter, we discussed the elements used to install files and create directories. The File, Directory, and Component elements play vital roles here, but you may also benefit from using ComponentGroup to group your components. This allows you to better organize your markup and even to separate it into multiple WiX source files.

The heat.exe tool can create Component elements for you. You simply need to point it at a certain directory. However, it's best to fine-tune its arguments so that the output that you get is optimal. We discussed a few other topics such as how to copy a file, how to set file permissions, and how to organize your File element Id attributes for maximum installation speed.

In the next chapter, we'll move on to discuss WiX properties and the various ways of searching the end user's system for files, directories, and settings.