This component is a slightly modified version of the standard MSHCComponent included with Sandcastle itself. The main difference is that this component supports an optional sortOrder attribute on the table of contents file elements that lets you alter the sort order for a topic and its subsequent sibling topics. The Sandcastle Help File Builder uses this feature to allow parenting of the API content to a conceptual topic and to ensure that all content is properly sorted when parented to an existing help viewer topic.

Example Configuration

The following is the default configuration for the help viewer component. It should be inserted into the configuration file before the SaveComponent in builds that generate MS Help Viewer output.

CopyExample Configuration
<component type="SandcastleBuilder.Components.MSHCComponent"
  assembly="{@SHFBFolder}SandcastleBuilder.Components.dll">
  <data self-branded="{@SelfBranded}" topic-version="{@TopicVersion}" toc-file="toc.xml"
    toc-parent="{@ApiTocParentId}" toc-parent-version="{@TocParentVersion}" locale="{@Locale}" />
</component>

The example given above is taken from the Sandcastle Help File Builder's configuration file. When used with it, the replacement tag {@SHFBFolder} is used to insert the help file builder's folder in the file path. This is replaced at build time with the appropriate value. If using the component in your own build scripts, replace the tag with a relative or absolute path to the component assembly. The other tags are replaced with project property values. Replace them with settings appropriate for your project.

The following is an example toc.xml file that contains the optional sortOrder attributes to change the sort order of the topics.

CopySample toc.xml file
<?xml version="1.0" encoding="utf-8"?>
<topics>
  <!-- Sort our content below that of the parent node's existing sub-topics -->
  <topic id="d4648875-d41a-783b-d5f4-638df39ee413" file="d4648875-d41a-783b-d5f4-638df39ee413" sortOrder="100">
    <topic id="57f7aedc-17d3-4547-bdf9-5b468a08a1bc" file="57f7aedc-17d3-4547-bdf9-5b468a08a1bc" />
    <topic id="0e6bbd29-775a-8deb-c4f5-5b1e63349ef1" file="0e6bbd29-775a-8deb-c4f5-5b1e63349ef1" />
    <topic id="fcdfafc4-7625-f407-d8e9-ec006944e1d7" file="fcdfafc4-7625-f407-d8e9-ec006944e1d7" />
    <!-- API content (7 namespaces, merged later) goes here and this topic follows it -->
    <topic id="ce37cf86-fd95-49fc-b048-ba7d25d68d87" file="ce37cf86-fd95-49fc-b048-ba7d25d68d87" sortOrder="10">
  </topic>
  .
  .
  .
</topics>

See Also