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:
- Help 1.x build component stack: Provides the stack that builds reference (API) topics for compiled Help 1.x.
- Help 2.x build component stack: Provides the stack that builds reference (API) topics for compiled Help 2.x.
- Help 1.x conceptual build component stack: Provides the stack that builds conceptual topics for compiled Help 1.x.
- Help 2.x conceptual build component stack: Provides the stack that builds conceptual topics for compiled Help 2.x.
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:
- Clicking the ellipses (...) button on any of the stacks will open the Build Component Stack editor for that particular stack.
- Expanding stacks, by double-clicking the row or using the preceding plus (+) signs, will load the configuration file and display each individual component as a dynamic sub property.
- The list is filtered, by default, to only show components that have an associated editor. To show all components set the Show entire build component stack option to True (this option precedes the stacks in the DocProject Properties window).
- To edit individual components simply click the ellipses (...) button. If a DocProject-compatible editor is associated with the component then it will be displayed; otherwise, the XML configuration file will be opened in Visual Studio and the component's definition will be selected automatically.
- If a component provides sub properties then it will be preceded by a plus (+) sign, allowing you to expand it. Sub properties can either be simple types that can be edited in-line or they can provide their own modal dialog editors, drop-down editors and more sub properties if needed.
Component Names and DescriptionsThe 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:
- Open the DocProject Properties window for your DocProject or DocSite.
- Right-mouse click your project in Solution Explorer and select, DocProject Properties from the context menu.
- 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).
- 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).
- Note: You do not need to expand the stack to see the ellipses button.
- Click the
button to open the Add Build Components dialog.
Add Build Components DialogThe
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 EditorThe 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:
- 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.
- 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.
- Select the components that you want to include in the stack (see Adding Build Components above for help).
- 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).
- 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.
- If the component vendor has provided a default XML configuration, enter it in the second text box.
- The root <component> element is required even if it's empty.
- The type and assembly attributes on the <component> element are ignored if they are specified.
- Press OK on the editor dialog to commit the changes to the component.
- 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.
- Use the up and down arrows to move the new components to the proper location.
- 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.
- 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.