Dave Donaldson

Configure Sandcastle To Use Your XML Comment Files

Wednesday, August 01 2007

As you may know, Sandcastle is Microsoft's answer to the death of NDoc. One of the architects for my current client put together a PowerShell script that uses Sandcastle to generate MSDN-style documentation for all of our project's .NET assemblies.

However, in testing the script (before adding it to our CC.NET build process), I noticed that the resulting .chm help file contained all of the typical API stuff but not any of our XML comments. Looking back through the PowerShell output window I noticed the following line:

Searching for files that match '.\comments.xml'.

That's not any of our XML comment files, so I began trying to determine where that was coming from and why it was looking for it. Initially I couldn't find anything about it and began wondering if it was hardcoded into Sandcastle, which I thought might be a distinct possibility given how early it is in the product cycle. This lead me to believe that maybe I'd have to find a way to merge all of our XML comment files into comments.xml to make it work properly.

Fortunately, further digging revealed where comments.xml was coming from. It turns out that Sandcastle has four profiles that you can use for output, which are basically different presentations of the docs. Each profile has its own set of icons, CSS, and JavaScript files, as well as its own sandcastle.config file. It's this config file that tells Sandcastle what XML comment files to look for, which by default is comments.xml.

To change it, look for the section that starts with <!-- Copy in comments -->. It contains a node that looks like this:

<data files=".\comments.xml" />

To make Sandcastle pick up all of your XML comment files, edit the node so it looks like this:

<data files=".\*.xml" />

Or you use the wildcard character to look for whatever makes sense for your app, such as:

<data files=".\MyApplication.*.xml" />

After making the change and re-running the PowerShell script, the generated docs now contain our XML comments in their full glory. Keep in mind that the above change works for the June 2007 CTP of Sandcastle, so no promises if it breaks something in future releases. Enjoy.

Post your comment

Name

Mail

Website