Getting Started with Sandcastle

At this point, you have a nifty new XML file that contains a wealth of information about your application, whatever that application may be. An XML file doesn’t make for a very good help file. Of course, you could always use XSLT to make the XML viewable—it’s a time-honored method of dealing with XML. You could also do something new and interesting, such as using the XML file as input for a Language INtegrated Query (LINQ) application. Using LINQ, you could ask for a list of all of the methods with a particular parameter. However, that’s still not a help file. No, you need something else and that something else is Sandcastle.

Microsoft has been busy creating Sandcastle over the last few months. However, most developers find that using Sandcastle alone is difficult. Consequently, what you really need is Sandcastle combined with something else. This article looks at Sandcastle combined with Sandcastle Help File Builder. In order to use Sandcastle Help File Builder, you must first download the Sandcastle product from Microsoft at: http://www.microsoft.com/downloads/details.aspx?familyid=E82EA71D-DA89-42EE-A715-696E3A4873B2. After you download and install Sandcastle, download Sandcastle Help File Builder from: http://www.codeplex.com/Wiki/View.aspx?ProjectName=SHFB and install it as well.

Overcoming a Potential Sandcastle Problem

At this point, it’s tempting to think that you have everything needed to create that help file, but it turns out that there’s something still missing. If you attempt to compile the help file now, you’ll still see one error that complains the XML file automatically generated by Visual Studio is missing a namespace XML comment. Interestingly, Visual Studio doesn’t provide a means to create this comment.

It’s possible to create a custom XML comment to solve this omission, but there’s an easier way to fix it. Right click the solution entry in Solution Explorer and choose Add | New Item. Select the XML File item template in the Add New Item dialog box and give the XML file a name that represents the content the file will contain, such as ProjectAndNamespace.XML. Add the project and namespace comments, as shown here.

<?xml version="1.0" encoding="utf-8" ?>
<doc>
   <assembly>
      <name>ApplicationComments</name>
   </assembly>
   <members>
      <member name="R:Project">
         <summary>
            This project demonstrates the use of application comments
            and shows how to test them.
         </summary>
      </member>
      <member name="N:ApplicationComments">
         <summary>
            This namespace consists of the ChangeStrings class and the
            associated test application. It also contains the StringExtensions
            used to extend the String class with some additional manipulation
            methods.
         </summary>
      </member>
   </members>
</doc>

The code begins with the <assembly> element that holds the actual name of the file that holds the assembly without the file extension. If your application contains more than one assembly, you can create an <assembly> element for each assembly. Within the <assembly> element is a list of <member> elements. Each <member> element must include a name that consists of a special code letter (R for project and N for namespace), followed by the project or namespace name. Each <member> element has a <summary> child element where you place the comment that Sandcastle request.

Considering the Sandcastle Help File Builder Properties

You’re finally ready to begin using the Sandcastle Help File Builder. Open the application by choosing Start | Programs | Sandcastle Help File Builder | Sandcastle Help File Builder GUI and you see the window shown in Figure 3.

Figure 3: The Sandcastle Help File Builder window provides you with a number of properties you can change.

You modify this window using the same approach that you normally use for working with the Properties window in the Visual Studio IDE. However, you’ll find that the default settings provide a reasonably nice help file. The only default setting that may pose problems is Framework Version found in the Build category. Make sure you set this property to match the version of the .NET Framework that you’re using.

You’ll also want to choose a help file format. The Sandcastle Help File Builder provides access to three formats: HtmlHelp1x, HtmlHelp2x, and Website. You can produce all three in a single compile if you wish. The default is to use the HtmlHelp1x option, which produces a Compiled HTML Help Module (CHM) file.

In addition, you may want to define the properties in the Help File category. Modifying any of the other properties in the list is purely optional. You’ll definitely want to look through the property list though—you can add all kinds of interesting features such as a content site map.