Sandcastle Build Component Templates
Introduction
Sandcastle Build Component Templates 1.1 consists of two distinct
Visual Studio Item Templates (C#) that can help developers to create custom
Sandcastle build components that work
with or without automation tools and take advantage of editor support in
DocProject and the
Sandcastle Help File Builder.
Sandcastle Build Component Overview
Sandcastle uses a flexible architecture based on pluggable components, which allows developers to control the information and layout of each auto-generated topic. Topics are generated using XML configuration and XSLT processing by executing a
stack of build components that manipulate and transform the XML data into its final output - an XML-compliant HTML help topic.
You can create custom build components to add, remove or modify information in each topic as you see fit. Build components, for example, have the ability to add HTML on-the-fly or to introduce new data into topics that can be used by another component later in the
stack.
For more information about DocProject's support for custom build components, see
How To Use Third-Party Sandcastle Components in DocProject.
Item Template Usage
To get started, follow these instructions after you download the item templates:
- Create a new C# class library project or open an existing one.
- Add an assembly reference to BuildAssemblerLibrary.dll, which is installed by Sandcastle (it is commonly found in, C:\Program Files\Sandcastle\ProductionTools\). Remaining dependencies will be referenced automatically.
- Add a new item to the project.
- In the Add New Item dialog, scroll down to the My Templates section and select one of the Sandcastle Build Component templates. (If you don't see them then you may need to restart Visual Studio.)
- Name your component something simple that indicates its primary function.
- Sandcastle build component names commonly end in Component; e.g., ResolveConceptualLinksComponent.
- Important: Due to a limitation with multi-file item templates, you must ensure that the name you enter is a valid Type name; e.g., no spaces, no symbols, doesn't start with a number, etc.
- Click Add to add the new component to your project.
At this point you should be able to build the project and add the component to a
sandcastle.config file for immediate use.
Basic Sandcastle Build Component
The basic template provides a foundation on which authors can create a custom build component for use with or without the Sandcastle Help File Builder or DocProject. It also provides a working implementation that can take advantage of optional features in
DocProject, such as dynamic sub properties.
Dependencies
There is
no dependency on DocProject when using this template, so DocProject does not have to be installed to
build build components that are based on it or for them to function properly when executed.
The only dependencies are various framework assemblies, which are referenced automatically, and
BuildAssemblerLibrary.dll, which is installed by Sandcastle and must be referenced manually (see
Item Template Usage above for instructions).
Hosted Sandcastle Build Component
The second item template is the same as the first, but it's also designed to take advantage of host-specific services in the component's editor when a host is available.
Built-in support for DocProject's API in particular is provided as a working example. Access to a few of DocProject's interfaces, such as the active
IDocProject,
IBuildEngine,
BuildSettings,
DocProjectOptions and
IEnvironmentHost, are used in the example intialization path for DocProject, which is executed automatically when DocProject's host service is detected. The default implementation gathers read-only information about the context in which the component is being edited and displays the information in the component's editor. A useful implementation would instead use this information to provide automatic configuration or to apply appropriate default values in the editor.
Dependencies
DocProject must be installed to create new components using this template; however, DocProject is
not required to use the components, which means that a fall-back initialization mechanism is required. Placeholders for both host-specific initialization and host-independent (fall-back) initialization are provided by the template. The proper initialization path is automatically chosen based on whether specific host services can be reached.
Note: Do not deploy DocProject assemblies with components that are created using this template. DocProject must be installed by end-users using the DocProject installer. If DocProject is not installed, and if you've followed the comments in the template to properly encapsulate host interfaces, then your components should still function properly on the command-line and in other tools such as the Sandcastle Help File Builder.
The other dependencies are various framework assemblies, which are referenced automatically, and
BuildAssemblerLibrary.dll, which is installed by Sandcastle and must be referenced manually (see
Item Template Usage above for instructions).
The Default Implementations
Both of the templates share the same basic implementation and therefore provide basically the same features and behavior.
When Applied To Topics (Executed)By default, a component generated from either template will simply write its XML configuration to the build trace window for each topic that is built by Sandcastle.
DocProject Properties WindowYou can view the component in a
DocProject or
DocSite by expanding one of the build component stack properties. When the component is expanded there will be a boolean sub property named,
Enabled. You can add additional settings in the property grid by adding properties to your component's
Configuration class (just look for the
Enabled property to see a working example).
Modal Editor DialogThe modal editor dialog is just a basic user control with a constructor that accepts your component's configuration. It allows users to read/write the component's inner XML configuration using a standard
TextBox control. It's highly recommended that you clear this control and then add your own implementation instead. Note that additional functionality is provided by the second template, but that code should be removed as well when creating your custom component since it only serves as an example to component developers and provides no value to end-users.