The following are some common problems and solutions along with some known issues with Sandcastle and help files that you may encounter.

All Questions

Documenting Assemblies

How do I use Sandcastle and the help file builder?
Read through the topics in the Getting Started section in the table of contents. These will give you an overview of how to use Sandcastle, the help file builder, and how to set up your projects to generate XML comments.
I have been using version 1.7.0.0 or earlier. Version 1.8.0.0 is a significant change. Where did option/feature X go?
Be sure to read through the version history starting at Version 1.8.0.0 (Alpha) since it contains all of the information about the change in project format and the user interface. The Where Did That Feature Go? section in that topic contains information about how to find features or equivalent functionality in the new release.
How do I document a web application or a website project?
See the Documenting Web Projects topic for details.
My project relies on third-party assemblies and/or interop assemblies that do not have XML comments files. How can I document my assemblies without them? / My project uses third party assemblies but I don't want to include them in my documentation. How do I exclude them?
Third-party assemblies with or without XML comments files and Visual Studio generated interop assemblies do not need to be documented. They are considered to be dependent or reference assemblies. As such, add them to the References node in the Project Explorer window rather than as documentation sources. See the References topic for more information.
How do I specify a generic such as IEnumerable<T> in a cref target and/or XML comments?

Use curly braces in cref targets and HTML entities (&lt; and &gt;) in the general XML comments. For example:

 Copy imageCopy
/// <summary>
/// See <see cref="IEnumerable{T}"/> for more information.
/// <p/>Another reference to IEnumerable&lt;T&gt;.
/// </summary>
Can I use HTML markup in my XML comments?
Yes, you can use HTML markup in your XML comments to add additional formatting. You can also use the img tag to embed an image in a namespace element's XML comments. Since the comments are XML, all HTML tags must be specified with a closing tag or as self-closing (i.e <p>This is a paragraph</p> or <p/>New paragraph).
How can I embed an image in a namespace, type, or member's help topic?

Embedding an image in an element's help topic is a two step process. First, you must add the image to the help file builder project as a content item (add it using the Project Explorer window and set the BuildAction to Content). The second step is to edit the member's XML comments (summary, remarks, etc) to add the img tag. To embed an image in the project summary or namespace comments, add the image tag to the help file builder's ProjectSummary property text or to a namespace's comments using the NamespaceSummaries project property.

Below are two examples of embedding an image in the XML comments. Note that all namespace help topics reside in an .\html folder so you must use a relative path to go up one level to find the image file. The first example assumes that the image is copied to the root of the help project. As such, no additional path beyond the relative indicator is required. The second example assumes that the image is copied to an .\Images folder. In that case, you must also specify the folder name. As noted above, the image tag must be self-closing to conform to the XML specification.

Example <img> Tag Usage Copy imageCopy
/// <summary>
/// A class member.
/// </summary>
/// <remarks>An image: <img src="../Process.gif"/>
/// </remarks>
public void TestMethod()
{
    // ... Method implementation ...
}

/// <summary>
/// A useful class.
/// <p/>UML Diagram: <img src="../Images/TestClassUML.gif"
///     alt="UML Diagram" />
/// </summary>
public TestClass
{
    // ... Class implementation ...
}
How can I create an IntelliSense XML comments file that contains information on only the members documented in the help file and excludes all of the private member details?
Add the IntelliSense Component to the project using the ComponentConfigurations project property.
How can I share project summary and namespace settings between multiple help file builder projects?
Create a standalone XML comments file and add it to the project as a documentation source. See the Sharing Project Summary and Namespace Comments help topic for details.
I have an assembly without code and without an XML comments file for which I'd like to create documentation and/or an Intellisense file. How can I do that?

Create a blank XML comments file like the following and name it after the assembly with a .xml extension:

Blank XML Comments File Copy imageCopy
<?xml version="1.0"?>
<doc>
  <assembly>
    <name>YourAssemblyNameHere</name>
  </assembly>
  <members>
  </members>
</doc>

Create a new help file builder project and add just that assembly and comments file to it as documentation sources. Select the ComponentConfigurations property and click the "..." button to the right of it. In the Component Configurations dialog, add the IntelliSense Component to the project. Next, set the project's Show Missing Tags properties to your liking. This will force the build to add "missing" notes for all items that you might want to document. Build the project and you will find a new XML comments file named after the assembly in the project's output folder. Edit the <member> elements in the XML comments file to add the comments that you want for each member. For example:

Member Comments Example Copy imageCopy
<member name="M:SandcastleBuilder.Utils.XmlCommentsFileCollection.FindMember(System.String)">
    <summary>
    Search all comments files for the specified member.  If not found,
    add the blank member to the first file.
    </summary>
    <param name="memberName">The member name for which to search.</param>
    <returns>The XML node of the found or added member</returns>
</member>

When you are done, replace your original placeholder file with the one generated from the build with your edited comments.

I want to create a help file without an assembly. When I try to build the help file, it stops and tells me I need at least one documentation source. Why?

Sandcastle was designed to document code based on a set of XML comments and API information found in a reflection information file. As such, it requires at least one assembly in order to produce a help file containing API documentation. If you do not include at least one assembly with a namespace containing at least one public class, the help file cannot be produced. To produce help files unrelated to assemblies, you can use some other tool such as the HTML Help Workshop or one of the commercial equivalents.

You can use the Additional Content Only plug-in to produce a help file based on conceptual content and/or additional content items alone. To do so, add the plug-in to the project via the PlugInConfigurations project option, add conceptual and/or additional content to the project, and build the help file. See the Additional Content Only Plug-In help topic for more information about it. See the Conceptual and Additional Content topic for more information about how to utilize conceptual and additional content files.

Build Failures

Why does the build fail telling me that it cannot find the Sandcastle or HTML help compiler tools?
First and foremost, be sure that you have installed the latest version of Microsoft's Sandcastle documentation compiler tools and the HTML help compiler(s). The Sandcastle tools and the help compilers are not part of the help file builder and must be downloaded and installed separately.. The help file builder is written by Eric Woodruff and consists of a GUI and a project build system that act as front ends to the Sandcastle tools and help compilers produced by Microsoft. See the Links to Resources topic for information on where to download the required tools. If you have the tools installed, but in a non-standard location, you may need to specify the paths to the tools. See the Paths Category Properties topic for more information.
Why does the build fail telling me that it cannot find the most current version of Sandcastle?

First, be sure that you have the most recent version of Sandcastle installed. This can be confirmed by running MRefBuilder.exe from the command line and making sure that the version number that it reports is the same as the one expected by the help file builder.

Also check the top of the log file to see where it found the copy of Sandcastle that it tried to use. A common cause of finding an outdated version of Sandcastle is if you install the Visual Studio 2005 SDK. It contains an outdated version of Sandcastle and it resets the DXROOT environment variable to point at its copy. You can edit the environment variable to point at the latest version of Sandcastle or reinstall the latest version so that it sets the variable back to the right location.

Note

There may be two copies of the DXROOT environment variable: one user copy and one system copy. If this is the case, delete the user copy and make sure that the system copy is pointing at the latest release of Sandcastle (the one from Microsoft, not the help file builder). You may need to reboot in order for the changes to take effect.

Why does my build fail with an error saying that it cannot find an assembly?
When you added documentation sources to the project, you may have specified the wrong name or perhaps chose the assembly from the wrong folder (i.e. .\Debug instead of .\Release). Check the assembly path and filename and verify that it does exist. If the path is correct, make sure the assembly actually exists. Rebuild your project if necessary to recreate it.
Why does my build fail with an Unresolved assembly reference error?
If the build fails in the Generating reflection information step with an error that starts "Error: Unresolved assembly reference", you need to add the named assembly as a reference. This is done by adding a reference to it to the References node in the Project Explorer window. See the References topic for more information on adding reference items. See the next question as well if you are documenting a Compact Framework application.
Why does my build fail with an Unresolved assembly reference error when I try to document a Compact Framework application?

In order to document Compact Framework applications you also need to add a reference item for the Compact Framework assemblies. These are usually located under the Visual Studio 2005 installation folder. The easiest way to reference them is to add the Wildcard References Plug-In to the project's PlugInConfigurations property and add an entry to its configuration for a path similar to the following:

 Copy imageCopy
%VS80COMNTOOLS%\..\..\SmartDevices\SDK\CompactFramework\2.0\v2.0\WindowsCE\

This will expand the VS80COMNTOOLS environment variable in order to find the Visual Studio 2005 installation location and append the necessary path to find the Compact Framework assemblies. See the References topic for more information on adding reference items.

Why can't Sandcastle resolve all dependent assembly references automatically?
Sandcastle, specifically MRefBuilder, uses CCI (Common Compiler Infrastructure) for assembly reflection. CCI searches the current directory for dependent assemblies as well as any directories specified by the /dep (Dependencies) option. CCI does not attempt to open a dependent assembly until some information from that assembly is needed. CCI is used because technically, CCI never "loads" any assembly; it just parses the data in the assembly file. That is why CCI can reflect over a foreign mscorlib while System.Reflection cannot. This allows Sandcastle to be used for documenting assemblies built with any version of the .NET Framework. CCI is also used by FxCop.
Why does my build fail with an error saying "No APIs found to document"?
Classes need to be declared public in your code, you need to enable the DocumentPrivates and/or DocumentInternals project property so that Sandcastle documents the internal/private members, or you need to include at least one assembly and at least one namespace to document. There should be at least one assembly, solution, or project file listed in the Documentation Sources node in the Project Explorer window. Use the NamespacesSummaries or ApiFilter project propery editor to be sure that you have at least one valid item that is checked and thus included. If you are using the ApiFilter property, check it to make sure you have not accidentally excluded everything.
Why does my build fail in MRefBuilder with a NullReferenceException related to OrcasNamer.WriteType?
The most likely cause of this problem is that you have the project's FrameworkVersion property set to .NET 1.0 or .NET 1.1 but you are trying to document a .NET 2.0 or later assembly. Check the property to make sure that it is set appropriately for your assembly.
My build fails because I am behind a proxy server and it cannot connect to the MSDN web service. How do I fix it?

If the SDK link type project property related to the help file format you are building is set to MSDN, BuildAssembler will attempt to contact the MSDN web service to resolve links to SDK topics. If you are behind a proxy server, this will most likely fail and will abort the build process with an error similar to "HTTP status 407: Proxy Authentication Required" or "HTTP status 417: Expectation Failed". The simplest fix is to set the HtmlSdkLinkType and WebsiteSdkLinkType properties to None, the MsHelp2SdkLinkType property to Index, and the MSHelpViewerSdkLinkType property to Id. The downside for the HTML Help 1 and website formats is that you will not get links to online SDK content. For the MS Help 2 and MS Help Viewer formats, the noted value generates links to the local help content when merged with the collection.

It has been reported that creating a BuildAssembler.exe.config file in the same folder as BuildAssembler.exe (the .\ProductionTools folder under the Sandcastle installation folder) and putting one of the following in it may allow it to work with the proxy server:

Method 1 (this works most often so try it first): Copy imageCopy
<configuration>
    <system.net>
        <defaultProxy useDefaultCredentials="true">
            <proxy usesystemdefault="true"/>
        </defaultProxy>
        <!-- Add this setting if you get an HTTP 417 error. -->
        <settings>
            <servicePointManager expect100Continue="false" />
        </settings>
    </system.net>
</configuration>
Method 2: Copy imageCopy
<configuration>
    <system.net>
        <defaultProxy enabled="true" useDefaultCredentials="true">
            <proxy bypassonlocal="true"
                proxyaddress="http://yourproxy:8080" />
        </defaultProxy>
        <!-- Add this setting if you get an HTTP 417 error. -->
        <settings>
            <servicePointManager expect100Continue="false" />
        </settings>
    </system.net>
</configuration>
Method 3 (use this if your company uses a proxy configuration script): Copy imageCopy
<configuration>
    <system.net>
        <defaultProxy useDefaultCredentials="true">
            <proxy scriptLocation="http://your.server.com/proxy.pac"
                usesystemdefault="true" />
        </defaultProxy>
        <!-- Add this setting if you get an HTTP 417 error. -->
        <settings>
            <servicePointManager expect100Continue="false" />
        </settings>
    </system.net>
</configuration>
My builds seem to hang during the BuildAssembler step. Why?
If your builds seem to hang during the BuildAssembler step, set the HtmlSdkLinkType and WebsiteSdkLinkType properties to None, the MsHelp2SdkLinkType property to Index, and the MSHelpViewerSdkLinkType property to Id. This will get it to run faster with the side-effect that you will not have links to online SDK content for the HTML Help 1 and website help formats. The only other alternative is to be patient and wait for it to finish. On a slow connection, it can take a very long time. If you are building an MS Help 2 (HxS) or MS Help Viewer (MSHC) file, you can set the related option as noted above so that it generates links to the local help content when merged with the collection.
I'm getting an Out of Memory exception during a very large build. How do I prevent it?
When performing a build that generates an extremely large amount of output, you may encounter an OutOfMemoryException if verbose logging is enabled in the help file builder GUI. If this occurs, turn off the Build window verbose logging enabled option in the File | User Preferences dialog box. Full details are still written to the log file and can be viewed after the build.
Why is the help compiler failing with HHC3002 and HHC3004 errors referencing non-html files such as images?
See BE0060: The [itemType] '[item]' contains a comma or '.h' which may cause the Help 1 compiler to fail.
Why is the help compiler failing with HHC6000 and HHC5007 errors referencing "disk full" and "fatal navigational compilation" errors?
Check the log file for the MRefBuilder output. It will most likely report that it found and documented zero types. This is caused by not having any public types in the documented assemblies or not specifying any assemblies at all to document (i.e. the Documentation Sources project node is empty or only contains XML comments files). Sandcastle requires at least one assembly and will not document internal and private code by default. Be sure to declare at least one class public. If all classes really are supposed to be private and/or internal, set the DocumentPrivates and/or DocumentInternals project properties to true.
Why is the help compiler failing with HHC6003 error stating that itircl.dll has not been registered?

This error affects a small number of people and is caused by one of the help components (ITCC.DLL) either not getting installed or not getting registered correctly. Search your system for the DLL. If not found, you can either locate it on another system that has the Help 2 components or you can search Google for it. Once you obtain it, you will need to copy it to the failing system and register it. This can be done by running the following command from a command prompt. Adjust the path to the DLL as necessary based on its location on your system.

 Copy imageCopy
regsvr32 C:\Windows\System\itcc.dll

Help File Issues

Why doesn't my compiled help file load? / Why do all of the help file topics display a "Page not found" or "This program cannot display the webpage" error?

For an MS Help 2 file (.HxS), you need a separate viewer to load the help file or you need to integrate it into an existing collection. See the Links to Resources topic for a link to a freeware Help 2 viewer and a tool that can help you register your help file with a collection.

For HTML Help 1 files (.CHM), if the path to the help file contains "#", the help file may fail to load. The apparent reason for this is that the help viewer considers the "#" to be an unsafe character and it must be encoded for it to use it. Rename the folder to remove the "#" to get the file to load.

Another cause for the pages not displaying is a security patch that prevents the help viewer from running from the intranet zone (i.e. a network share). You can fix this problem by saving the following to a file and importing it into the registry.

HelpFix.reg Copy imageCopy
Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\HTMLHelp\1.x\ItssRestrictions]
"MaxAllowedZone"=dword:00000001

It may also be possible to unblock the file so that it can be viewed by right-clicking on it, selecting Properties and clicking the Unblock button on the General tab if it is there.

Why doesn't my help file contain any/all of the classes from the assembly?

The most likely cause of an empty help file or one that does not contain all of your assembly's classes is that the missing classes are not declared public. By default, when you add a class to a Visual Studio project, it does not add the public keyword to it. As such, you must remember to edit the class to make it public if necessary. Sandcastle does not document private and internal methods by default either. If you really want to see them in the help file, set the DocumentPrivates and/or DocumentInternals project properties to true.

You should also check the project to be sure that it does not have an ApiFilter defined that is excluding the items in question. An <exclude /> tag in the item's XML comments will also cause it to be removed from the documentation.

Another possible cause of missing classes is compiling a help file project using the wrong framework version selection. For example, if you compile a .NET 2.0 help project with the FrameworkVersion project property set to a .NET 1.x version number, you may end up with lots of missing classes. As such, check the property to be sure that it is set appropriately.

The help file is built okay but I don't see my comments on the members. Why not?

You either have not enabled the Visual Studio project option to produce an XML comments file for your assembly, it has a name different from that of the assembly and the help file builder did not see it when you added the assembly to the project, or the XML comments filename is not unique. Check the Documentation Sources node in the Project Explorer window. You should see the assembly name and the XML comments filename listed. If you added a solution or project file as a documentation source, check the build log to see if it found the correct assembly and XML comments file. See the Walkthrough: Enabling and Using XML Comments topic for information on enabling the XML comments file option in Visual Studio.

Be sure to give each project's XML comments file a unique name as they are copied to a common location for the build. Identically named files may overwrite each other and the documentation in the overwritten files will not appear in the help file. If the comments file options are set correctly, check to be sure that the XML comments in your source files are preceded by a triple slash for C# code (///) or a triple quote for VB.NET (''').

My help file contains lots of red "missing documentation" messages. How do I get rid of them?
The project properties in the Show Missing Tags category control which types of "missing documentation" messages appear in thehelp file. These can help you locate help topics that need attention to provide better documentation. Adding the missing tags to your code is one way to get rid of the message. You can search the help file for the text "missing documentation" or review the build log file to locate the members in question. If you do not care to see these messages, simply alter the project properties to turn off the ones that you do not want to see.
Why are all of my code samples colorized as C# code? / Why don't my code samples show up unless I select the C# code filter?

The help file builder automatically includes a copy of the Code Block Component that adds several attributes to the <code> tag. One of these is the lang attribute that lets you specify the language rules to use when colorizing the code. It is also used to indicate the code filter to which the sample should be connected. If omitted, the component will assume that the code is C#. You can change this behavior by adding a lang attribute that specifies a different language. You can also specify "none" as a value to disable colorization and the code filter for it.

If the majority of your code samples are in a language other than C#, you can override the default by using the ComponentConfigurations project property to add the Code Block Component to the project and configure it to use a different default setting.

The language name is showing up as the default title on a colorized code block but I don't want it to do that. How do I get rid of it?
Specify the title attribute and set it to a title of your choice or to a single space to suppress it (title=" "). To turn it off globally, use the ComponentConfigurations project option to add the Code Block Component to the project and edit its configuration to turn off the Use language name as title option.
Why does my help file title not appear when I use a language selection other than English?

For non-English HTML Help 1 help files, the help title will not appear on the title of the help window unless the system's language matches the help file's language exactly. This is a known issue with the way the help viewer compares the language values.

To resolve encoding issues, add the DBCS Fix for CHM Builds Plug-In to the project. See the plug-in documentation for information about its configuration.

Why does the help file title contain garbage characters?

The HTML Help 1 compiler does not appear to support Unicode encoding of its project and table of contents files. This may cause the help title to display incorrectly if it contains extended characters that need encoding.

To resolve encoding issues, add the DBCS Fix for CHM Builds Plug-In to the project. See the plug-in documentation for information about its configuration.

How can I view an MS Help 2 file?
For proofreading, you can use a standalone help view such as H2Viewer.exe. See the Links to Resources topic for information on where to get it. See the next question for information on deploying a Help 2 file.
How can I deploy an MS Help 2 file to an end-user's system?
The simplest way to deploy a Help 2 file is to use H2Reg.exe. The help file builder produces a configuration file for it as part of the Help 2 build process. See the Deploying an MS Help 2 File topic for more information.
How can I add support for NamedUrlIndex options such as DefaultPage, HomePage, AboutPageIcon, etc.?
See the Named URL Index Support topic for details.

The API Filter

I used the NamespaceSummaries project option to exclude a namespace but it is still showing up in the help file. Why? / I used the <exclude /> tag feature to exclude a namespace/type/member but it is still showing up in the help file. Why?
Check the build log in the section where it generated the API filter. You will probably see a warning there about the exclusion conflicting with the API filter. The API filter always wins. To fix the issue, edit the ApiFilter project property and exclude the item there.
I used the NamespaceSummaries project option to exclude a namespace. I now want it included but it is not showing up. Why? / I used the <exclude /> tag to exclude a namespace/type/member. I removed the tag as I now want it included but it is not showing up. Why?
Check the ApiFilter project property as it is probably being excluded in there. This situation does not generate a warning in the log so you have to check for it manually. Simply place a checkmark next to the item you want to have included.

Conceptual Content/Additional Content

I want my additional content pages to look like the selected presentation style used in the API topics. How can I do that?
The preferred method for adding additional content (also known as conceptual content) to a project is to use Microsoft Assistance Markup Language (MAML). See the Conceptual and Additional Content topics for more information. An older method (Topic File Transformation) is also supported but that feature has been deprecated in favor of using MAML.
How do I arrange the additional content pages and specify which is the default topic?
If using MAML, the Content Layout File Editor is used to define the content layout and the default topic. For HTML files, add a site map file to the project and edit it to define the layout. See the Site Map File Editor topic for details.
How can I create a link to a namespace element's help topic from an additional content page?
If editing a MAML topic, use the Entity References Window to add a link to the topic. If editing an HTML file, use a <see> tag to reference the namespace element. When the additional content page is parsed, the <see> tag will be replaced with a link to the namespace element's help topic page. See the Linking to Namespace Content help topic for details.
How can I create a link to an additional content page from a a namespace, type, or member help topic?

Edit the member's XML comments (summary, remarks, etc) to add an anchor (<a>) tag that points to the additional content page. To add a link in the Project Summary or Namespace comments, add the anchor tag to the help file builder's Project Summary notes or namespace comments. Below are two examples of adding a link in the XML comments. Note that all namespace help topics reside in an .\html folder so you must use a relative path to go up one level to find the additional content file. The first example assumes that the file is copied to the root of the help project. As such, no additional path beyond the relative indicator is required. The second example assumes that the file is copied to a .\Tutorials folder. In that case, you must also specify the folder name.

Linking to Additional Content Copy imageCopy
/// <summary>
/// A class member.
/// </summary>
/// <remarks>Class usage tutorial:
/// <a href="../SomeClassTutorial.html">SomeClass Tutorial</a>
/// </remarks>
public void TestMethod()
{
    // ... Method implementation ...
}

/// <summary>
/// A useful class.  For more information see the
/// <a href="../Tutorials/SomeClass.html">tutorial</a>.
/// </summary>
public TestClass
{
    // ... Class implementation ...
}
How can I colorize code in my additional content (HTML) files?
Use a <pre> tag and specify the necessary attributes to colorize it. When the additional content page is parsed, the content will be colorized based on the settings. See the Syntax Highlighting <pre> Tag Content help topic for details.

Custom Build Components

How do I configure the custom build components with project-specific settings?
Use the ComponentConfigurations project property. Click the "..." button to the right of the property, select the component from the list in the dialog that appears, and click the Configure button.
Where can I find more information on the custom build components supplied with the help file builder?
See the Custom Build Components help topic for more information and links to details about each component.
How can I create my own custom build components?
For information on writing your own custom build components, see the Code Project article Creating Custom Build Components for Sandcastle.

Build Process Plug-Ins

How do I configure the plug-ins with project-specific settings?
Use the PlugInConfigurations project property. Click the "..." button to the right of the property, select the plug-ins from the list in the dialog that appears, and click the Configure button.
Where can I find more information on the plug-ins supplied with the help file builder?
See the Build Process Plug-Ins help topic for more information and links to details about each plug-in.
How can I create my own custom plug-ins?
For information on writing your own custom plug-ins, see the Creating Build Process Plug-Ins help topic.

General Help Topic Questions

How can I create a link to a namespace element's help topic from an external source such as application code or a page in an external web site?

Set the project's NamingMethod property based on your preference and see the NamingMethod help topic for examples that show how to open specific topics based on the selected naming method from application code and how to determine the URL for a website link.

See Also