How To Use Third-Party Build Components in DocProject

Introduction

The XML configuration files that are used by Sandcastle's Build Assembler program are available as project items in your DocProjects and DocSites. They are located in the Help\Presentation\Style\Configuration directory. You can edit these files using Visual Studio's XML editor or, as this article will show you how, in the DocProject Properties window or the DocProject External UI.

Build Components

Sandcastle's high level of flexibility can be attributed to its plug-in type architecture, which consists of Build Components and a single program named, BuildAssembler.exe that processes them. As such, Build Components make up a significant portion of Sandcastle's functionality. Adding or configuring Build Components, in what the Sandcastle team refers to as the Build Component Stack, allows end-users to completely customize the HTML topic build process. When used in conjunction with DocProject's extensibility features, developers have full control over the entire build process.

Build Components are registered in Build Assembler's configuration file, which ships with Sandcastle as a file named, sandcastle.config. A different version of this file can be found in each particular presentation style's Configuration directory, although they are mostly the same. Each presentation style has its own implementation of a Build Component Stack to generate HTML topics that have the look and feel of that style; e.g., VS2005, Hana or Prototype.

For more information, see BuildAssembler (EXE) on the Sandcastle blog.

Build Component Stacks

A Build Component Stack is a Sandcastle configuration file that lists Build Components, which build the individual HTML topics. Sandcastle's BuildAssembler.exe program processes each component in the stack once, top-down, for each HTML topic in the build manifest.

When you create a new DocProject or DocSite it will import the selected Sandcastle presentation style into the new project. The sandcastle.config file, containing the presentation's Build Component Stack, will also be imported. However, since DocProject can build both Help 1.x and Help 2.x output, and since the build process for these two types of compiled help usually require different configurations, DocProject will import the sandcastle.config file as two distinct files named, sandcastle.help1x.config and sandcastle.help2x.config, respectively.

Note: You can control the changes that DocProject makes when it imports a sandcastle.config file by configuring the XML elements under the <sandcastleConfigChanges> element in DocProject's configuration file, commonly found at C:\Program Files\Dave Sexton\DocProject\bin\DaveSexton.DocProject.dll.config. (Do not confuse this file with the DocProject.exe.config file.)

Editing a Build Component Stack

The two Sandcastle configuration files, sandcastle.help1x.config and sandcastle.help2x.config, contain the Build Component Stacks that are used by Sandcastle's Build Assembler program to build Help 1.x and Help 2.x output, respectively. You can find them in your DocProject or DocSite by viewing the project in Solution Explorer and browsing to the Help\Presentation\Style\Configuration folder.

The files can be edited in Visual Studio's XML editor. They can also be edited using properties that are exposed in the DocProject Properties window (right-mouse click your project in Solution Explorer and select, DocProject Proprties) or by using DocProject's Build Component Stack editor, which is explained below.

Choosing a Build Component Stack

The first thing to consider before you can edit a stack is which stack you will be editing. Currently, there are four types of build stacks that you can choose from when using any of the built-in Sandcastle presentation styles. The four stacks appear in the DocProject Properties window under the Configuration category:

Configuring Build Components

The components in the four Bulid Component Stacks that appear in the DocProject Properties window can be edited in a few different ways:
Component Names and Descriptions
The descriptions for individual components in the DocProject Properties window are taken from the XML comments that immediately precede their declaration in the configuration file. However, if a component has an associated System.ComponentModel.DescriptionAttribute then that will be used instead. The same goes for the component's name, which component vendors can set by attaching the System.ComponentModel.DisplayNameAttribute to their components; otherwise, without that attribute, the simple type name of the component as it appears in the configuration file is used for display purposes.

Adding Build Components

The same procedure can be used to add build components from both Sandcastle's build component library and third-party component libraries:
  1. Open the DocProject Properties window for your DocProject or DocSite.
    1. Right-mouse click your project in Solution Explorer and select, DocProject Properties from the context menu.
    2. If you prefer you can use the Tools > Options > DocProject > Active Projects page or the DocProject External UI (the latter being the only supported option for Express users).
  2. Click the ellipses button (...) at the far-right side of one of the build component stacks to open the editor dialog (see Choosing a Build Component Stack above).
    1. Note: You do not need to expand the stack to see the ellipses button.
  3. Click the New Build Component button to open the Add Build Components dialog.
Add Build Components Dialog
The Available list contains all of the built-in Sandcastle build components. From this list you can choose the components that you want to add one at a time, by double-clicking each individual row. You can also select more than one, right-mouse and click Select in the context menu.

When you select components from the Available list they will appear in the Selected grid below. When you are finished selecting components, press OK and an editor dialog will be shown for the last component that you selected (or the only component if you only selected one).

The Default Component Editor
The default editor allows you to configure the raw XML configuration and a description of the component as they will appear in the configuration file. The description is saved as an XML comment immediately above the component's definition in the configuration file.

Adding Third-Party Build Components

Continuing with the instructions from Adding Build Components above, you should still have the Add Build Components dialog open. To add third-party components:
  1. Click the Browse... button and locate the managed assembly (.exe or .dll) that contains the build component(s) that you want to add. Press Open on the Browse dialog to load the components into the Available grid.
  2. You can find the third-party components that are defined in the assembly that you just added, if there are any, by scrolling to the bottom of the Available grid.
  3. Select the components that you want to include in the stack (see Adding Build Components above for help).
  4. When you are finished choosing components, press OK on the Add Build Components dialog. The components will be appended to the end of the Build Component Stack and an editor dialog will be shown for the last component that you selected (or the only component if you only selected one).
    1. In the component's editor dialog, add a description that will appear as an XML comment immediately above the component's definition in the configuration file.
    2. If the component vendor has provided a default XML configuration, enter it in the second text box.
      1. The root <component> element is required even if it's empty.
      2. The type and assembly attributes on the <component> element are ignored if they are specified.
    3. Press OK on the editor dialog to commit the changes to the component.
    4. Note: If the component's vendor has provided an editor that is compatible with DocProject, then clicking the ellipses button (...) next to the component will show the vendor's dialog.
  5. Use the up and down arrows to move the new components to the proper location.
    1. Note: This step is very important. You must consult the component vendor's documentation to find out where your component should be located in the Build Component Stack. Placement is usually expressed as being relative to one of the built-in Sandcastle components, such as before SaveComponent or before ResolveReferenceLinksComponent2, for example.
  6. Click OK on the Build Component Stack editor dialog to commit the changes.
Third party components will appear as sub properties of stacks when they are expanded in the DocProject Properties window. If a component provides a DocProject-compatible editor then the ellipses (...) button will invoke the editor. Similarly, if the component supports configurable properties then they will appear under the component when it's expanded in the DocProject Properties window.

Component vendors can use the Sandcastle Build Component Template 1.0 to easily create Sandcastle Build Components that take advantage of DocProject configuration features such as modal dialog and drop-down editors and configurable sub properties. Components based on this template will also work out-of-the-box in the Sandcastle Help File Builder. They'll also work without using automation tools, but without a graphical editor as well.