WiX tricks and tips

We've been using WiX for a while now, and despite the usual gripes about ease of use, it's going reasonably well. What I'm looking for is useful advice regarding:

• Setting up a WiX project (layout, references, file patterns)
• Integrating WiX into solutions, and build/release processes
• Configuring installers for new installations and upgrades
• Any good WiX hacks you'd like to share

Solution 1:

1. Keep variables in a separate wxi include file. Enables re-use, variables are faster to find and (if needed) allows for easier manipulation by an external tool.

2. Define Platform variables for x86 and x64 builds

   <!-- Product name as you want it to appear in Add/Remove Programs-->
   <?if $(var.Platform) = x64 ?>
     <?define ProductName = "Product Name (64 bit)" ?>
     <?define Win64 = "yes" ?>
     <?define PlatformProgramFilesFolder = "ProgramFiles64Folder" ?>
   <?else ?>
     <?define ProductName = "Product Name" ?>
     <?define Win64 = "no" ?>
     <?define PlatformProgramFilesFolder = "ProgramFilesFolder" ?>
   <?endif ?>
   

3. Store the installation location in the registry, enabling upgrades to find the correct location. For example, if a user sets custom install directory.

    <Property Id="INSTALLLOCATION">
       <RegistrySearch Id="RegistrySearch" Type="raw" Root="HKLM" Win64="$(var.Win64)"
                 Key="Software\Company\Product" Name="InstallLocation" />
    </Property>
   

   Note: WiX guru Rob Mensching has posted an excellent blog entry which goes into more detail and fixes an edge case when properties are set from the command line.

   Examples using 1. 2. and 3.

   <?include $(sys.CURRENTDIR)\Config.wxi?>
   <Product ... >
     <Package InstallerVersion="200" InstallPrivileges="elevated"
              InstallScope="perMachine" Platform="$(var.Platform)"
              Compressed="yes" Description="$(var.ProductName)" />
   

   and

   <Directory Id="TARGETDIR" Name="SourceDir">
     <Directory Id="$(var.PlatformProgramFilesFolder)">
       <Directory Id="INSTALLLOCATION" Name="$(var.InstallName)">
   

4. The simplest approach is always do major upgrades, since it allows both new installs and upgrades in the single MSI. UpgradeCode is fixed to a unique Guid and will never change, unless we don't want to upgrade existing product.

   Note: In WiX 3.5 there is a new MajorUpgrade element which makes life even easier!

5. Creating an icon in Add/Remove Programs

   <Icon Id="Company.ico" SourceFile="..\Tools\Company\Images\Company.ico" />
   <Property Id="ARPPRODUCTICON" Value="Company.ico" />
   <Property Id="ARPHELPLINK" Value="http://www.example.com/" />
   

6. On release builds we version our installers, copying the msi file to a deployment directory. An example of this using a wixproj target called from AfterBuild target:

   <Target Name="CopyToDeploy" Condition="'$(Configuration)' == 'Release'">
     <!-- Note we append AssemblyFileVersion, changing MSI file name only works with Major Upgrades -->
     <Copy SourceFiles="$(OutputPath)$(OutputName).msi" 
           DestinationFiles="..\Deploy\Setup\$(OutputName) $(AssemblyFileVersion)_$(Platform).msi" />
   </Target>
   

7. Use heat to harvest files with wildcard (*) Guid. Useful if you want to reuse WXS files across multiple projects (see my answer on multiple versions of the same product). For example, this batch file automatically harvests RoboHelp output.

   @echo off  
   robocopy ..\WebHelp "%TEMP%\WebHelpTemp\WebHelp" /E /NP /PURGE /XD .svn  
   "%WIX%bin\heat" dir "%TEMP%\WebHelp" -nologo -sfrag -suid -ag -srd -dir WebHelp -out WebHelp.wxs -cg WebHelpComponent -dr INSTALLLOCATION -var var.WebDeploySourceDir 
   

   There's a bit going on, robocopy is stripping out Subversion working copy metadata before harvesting; the -dr root directory reference is set to our installation location rather than default TARGETDIR; -var is used to create a variable to specify the source directory (web deployment output).

8. Easy way to include the product version in the welcome dialog title by using Strings.wxl for localization. (Credit: saschabeaumont. Added as this great tip is hidden in a comment)

   <WixLocalization Culture="en-US" xmlns="http://schemas.microsoft.com/wix/2006/localization">
       <String Id="WelcomeDlgTitle">{\WixUI_Font_Bigger}Welcome to the [ProductName] [ProductVersion] Setup Wizard</String>
   </WixLocalization>
   

9. Save yourself some pain and follow Wim Coehen's advice of one component per file. This also allows you to leave out (or wild-card *) the component GUID.

10. Rob Mensching has a neat way to quickly track down problems in MSI log files by searching for value 3. Note the comments regarding internationalization.

11. When adding conditional features, it's more intuitive to set the default feature level to 0 (disabled) and then set the condition level to your desired value. If you set the default feature level >= 1, the condition level has to be 0 to disable it, meaning the condition logic has to be the opposite to what you'd expect, which can be confusing :)

    <Feature Id="NewInstallFeature" Level="0" Description="New installation feature" Absent="allow">
      <Condition Level="1">NOT UPGRADEFOUND</Condition>
    </Feature>
    <Feature Id="UpgradeFeature" Level="0" Description="Upgrade feature" Absent="allow">
      <Condition Level="1">UPGRADEFOUND</Condition>
    </Feature>
    

Solution 2:

Checking if IIS is installed:

<Property Id="IIS_MAJOR_VERSION">
    <RegistrySearch Id="CheckIISVersion" Root="HKLM" Key="SOFTWARE\Microsoft\InetStp" Name="MajorVersion" Type="raw" />
</Property>

<Condition Message="IIS must be installed">
    Installed OR IIS_MAJOR_VERSION
</Condition>

Checking if IIS 6 Metabase Compatibility is installed on Vista+:

<Property Id="IIS_METABASE_COMPAT">
    <RegistrySearch Id="CheckIISMetabase" Root="HKLM" Key="SOFTWARE\Microsoft\InetStp\Components" Name="ADSICompatibility" Type="raw" />
</Property>

<Condition Message="IIS 6 Metabase Compatibility feature must be installed">
    Installed OR ((VersionNT &lt; 600) OR IIS_METABASE_COMPAT)
</Condition>

Solution 3:

Keep all IDs in separate namespaces

• Features begin with F. Examples: F.Documentation, F.Binaries, F.SampleCode.
• Components begin with C. Ex: C.ChmFile, C.ReleaseNotes, C.LicenseFile, C.IniFile, C.Registry
• CustomActions are CA. Ex: CA.LaunchHelp, CA.UpdateReadyDlg, CA.SetPropertyX
• Files are Fi.
• Directories are Di.
• and so on.

I find this helps immensely in keeping track of all the various id's in all the various categories.