The Problem

WiX has been a wonderful tool for producing MSIs despite a handful of deficiencies.

In a large project with multiple developers assemblies are added to and removed from the project on a continuing basis. Keeping WiX in sync with these changes is not well-supported. If an assembly is removed, WiX will complain that it can’t find the file and abort. New assemblies are a different story.

Ideally, a new assembly would be added to a WiX project by having heat run on it, the resulting XML massaged, and inserted into the correct component group. There is no mechanism for doing this automatically at this point.

My Solution

In order to prevent the WiX project from producing an MSI with missing files, I wrote a custom MSBuild task to compare the contents of the application’s build directory with the WiX source code. If any extra files are found, the custom task logs each orphan as an error, and the WiX project fails to build.

The following isn’t bullet-proof and lacks some necessary error checking, but I hope it sheds light on the core of my approach.

Step 1: Create a Custom Build Task to Detect Orphans

Creating the Custom Build Task

I’ll not detail creating a custom build task here, but refer you to some articles I found most useful:

1. Bart de Smet’s excellent article The Custom MSBuild Task Cookbook
2. The MSDN reference pages
   1. How to: Write a Task
   2. UsingTask Element (MSBuild)
   3. MSBuild Tasks
3. Marcin Kawalerowicz’s Writing MSBuild Custom Task

The long and short of it is that a custom task is a simple class that descends from Microsoft.Build.Utilities.Task and overrides the Execute() method. Execute() returns a simple bool to indicate success or failure.

Required Parameters

This process needs two directories: where the application build files reside, and where the WiX source files reside. (This assumes that all respective files exist in a single directory.)

namespace WiXInstallValidator
{
    public class OrphanedFileCheck: Task
    {
.
.
.
    [Required]
    public string ArtifactsDirectory { get; set; }
 
    [Required]
    public string WiXSourceDirectory { get; set; }

The [Required] attribute ensures that the project file sets both of these parameters.

Fetching the File Names

In the Execute() method, loading the list of file names from the directories supplied by the ArtifactsDirectory and WiXSourceDirectory was straightforward.

//
// Extract list of WiX source files
//
IEnumerable lWixFiles =
    from f in System.IO.Directory.GetFiles(WiXSourceDirectory, "*.wxs")
    select f.ToLower();
 
//
// DLLs that exist in the build artifacts directory
//
IEnumerable lBuildFiles =
    from f in System.IO.Directory.GetFiles(ArtifactsDirectory, "*.dll")
    select System.IO.Path.GetFileName(f).ToLower();

The WiX source files need the path since we’re going to actually open the files. The DLL names have the path stripped off since we’re going to compare them against the WiX source code.

Extract Filenames from XML

The WiX code is nothing special. I have a variable $(var.BuildRoot) that points to the directory where the DLLs are found. Thus a typical WiX source file has the form:

<?xml version="1.0" encoding="UTF-8"?> 
<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">  
 
    <?include "incFileLocations.wxi"?>  
 
    <!-- 
        List the various components individually, then put them into 
        component groups in the next <Fragment> tag. 
    --> 
    <Fragment>  
        <DirectoryRef Id="INSTALLLOCATION">
            <Component Id="Foo.Bar.dll" Guid="9722F565EED03FCA2239C7BA01410083">  
                <File Id="fil9722F565EED03FCA2239C7BA01410083" KeyPath="yes" 
                    Source="$(var.BuildRoot)\Foo.Bar.dll" />
            </Component> 
.
.
.

XElement requires that we add the WiX namespace. I define that as a constant for code clarity. Thus the Linq code looks something like:

private const string BUILD_ROOT = "$(var.BuildRoot)\\";
private const string WIX_NAMESPACE = "{http://schemas.microsoft.com/wix/2006/wi}";
.
.
.
//
// Extract filenames from XML begining with $(var.BuildRoot)
//
IEnumerable lFilesInWiX =
    from f in lWixFiles
    from c in XElement.Load(f).Descendants(WIX_NAMESPACE + "File")
    where ((string)c.Attribute("Source")).StartsWith(BUILD_ROOT)
    select ((string)c.Attribute("Source")).Substring(BUILD_ROOT.Length).ToLower();

Compare the Lists of Files

Determining if there are new files in danger of not being included in the MSI only requires the simple statement:

//
// Files in the build artifacts directory which aren't in WiX
//
IEnumerablelOrphanedFiles = lBuildFiles.Except(lFilesInWiX);

Informing the User of Orphans

To create a nice list of errors, one uses the Log.LogError() method thus:

foreach (string s in lOrphanedFiles)
    Log.LogError("The file {0} appears to be missing from the WiX source code.", s);

Wrapping Up the Custom Task

Lastly, the custom task returns a boolean indicating success or failure.

return lOrphanedFiles.Count() == 0;

Step 2: Inserting the Custom Task Into the WiX Build

Including the Extension

The WiX project file has the extension wixproj. First we have to make MSBuild aware of the extension.

<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003"> 
    <UsingTask 
        TaskName="WiXInstallValidator.OrphanedFileCheck" 
        AssemblyFile="..\WiXInstallValidator\bin\debug\WiXInstallValidator.dll"/> 
.
.
.

This is straight out of the articles on writing MSBuild custom tasks that I listed above.

Triggering the Extension

Again, this is straight out of the articles on writing MSBuild custom tasks that I listed above. There are some comments in the default WiX project file showing where to add custom tasks.

    <!--
        To modify your build process, add your task inside one of the targets below and uncomment it.
        Other similar extension points exist, see Wix.targets.
        <Target Name="BeforeBuild">
        </Target>
        <Target Name="AfterBuild">
        </Target>
    -->
    <Target Name="BeforeBuild">  
        <OrphanedFileCheck 
            ArtifactsDirectory = "..\ProjectBuild\Debug\" 
            WiXSourceDirectory = "..\WiXInstaller\" 
            ContinueOnError="false" />  
    </Target>

Conclusion

That’s it! This is something that I don’t do often, so recorded my personal notes here in case somebody else might benefit from my working through the problem.

Credits

Thanks to the wonderful WiX mailing list members, especially Simon and Blair who pointed me in this general direction.

Updates

2010-01-21

Added ToUpper() to the Linq expressions to avoid false positives due to case sensitivity.