Help File Issues

This topic covers common issues related to the viewing help files and their content.

• 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 web page" error?
• Why doesn't my help file contain any/all of the classes from the assembly?
• The help file builds successfully but I don't see my comments on the members. Why not?
• My help file contains lots of red "missing documentation" messages. How do I get rid of them?
• 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 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?
• Why does my help file title not appear when I use a language selection other than English?
• Why does the help file title contain garbage characters?

For an MS Help Viewer file (.mshc), you need to integrate it into an existing collection. See the Deploying an MS Help Viewer File topic for details. An alternate MSHC file viewer can also be specified in the help file builder user preferences.

For problems opening and viewing Open XML documents, see the Open XML Document Help File Format topic for troubleshooting information.

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.

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.

See the answer to the previous question.

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 Document Privates and/or Document Internals project properties to true.

You should also check the project to be sure that it does not have an API Filter 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 Framework Version 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.

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 Enabling and Using XML Comments topic for information on enabling the XML comments file option in Visual Studio.

Be sure that you selected the proper configuration and platform for the help file build. You can check the build log to see if the XML comments file selected matches the expected configuration and platform. You may also need to rebuild your assembly to ensure that the XML comments file is up to date.

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 (''').

The project properties in the Missing Tags category control which types of "missing documentation" messages appear in the help 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 messages. 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.

The help file builder automatically includes a copy of the Code Block Component that adds several attributes to the <code> element. One of these is the language 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 language 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 Component Configurations project category to add the Code Block Component to the project and configure it to use a different default setting.

See the answer to the previous question.

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 Components project category to add the Code Block Component to the project and edit its configuration to turn off the Use language name as title option.

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.

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.

Other Resources