Sandcastle under the hood, part 2

In my previous post, I talked you through the first steps of the Sandcastle build process. So far it’s been more or less simple xsl transforms, but now we’re getting to the fun part – the BuildAssembler.

The BuildAssembler is actually just a small console application that runs an XML document through a configurable pipeline of components. The pipeline is run once for each topic in the manifest. It is sandcastle.config that tells the BuildAssembler which components to apply to the XML document, and in which order they are to be applied. Before running the first topic, each component gets a chance to initialize itself according to the parameters given.

There’s a whole bunch of different components you can use. I’ve compiled a list of them and a short description of what (I think) they do.

Content components

These components are primarily used to add new content to the XML document.


Adds the contents of a file to the XML document


Copies specific parts of the contents of one or more XML files to the XML document.
When initializing, this component builds up an index of the set of XML-files which makes the process rather quick. The index is global to the entire process so the same index can be used by multiple CopyFromIndexComponents.

Flow components

Components used for controlling the flow through the pipeline.


This component typically contains one or more other components. It applies these contained components on each node in a node list given by an xpath expression.


Evaluates an xpath expression. Depending on the result it either applies the components in the then-branch or the else-branch.


Evaluates an xpath expression. Depending on the value it applies the appropriate components in the correct case-branch.

Output components


Dumps the contents of the current XML document to the console. Check out a previous post to see how you can take advantage of this!


Saves the contents of the current XML document to a file.


Validates the current document against one or more XML Schema (xsd) files. Any errors are written to the log (usually just the console).

Transformation components

These components do the main workload. They resolve references, replace nodes, transform, create new structures et.c.


Resolves links to other pages in the current project or to pages in external documents. There are three kinds of links available; Local (within the current project, creates <a href= style links), Index (to other MShelp documents, creates MSHelp-style links) and None (just text, doesn’t produce a link at all).


Used together with one or more SyntaxGenerators (there is one for each main language) to create syntax strings for the current class/method/property et.c. The syntax generators actually seem complex enough to warrant an entire article of their own.


Replaces <include> and <includeAttribute> elements with contents found in external xml files (like shared_content.xml and reference_content.xml). The content can also take parameters in the standard form expected by string.Format, so if the item in shared_content.xml looks like this:

<item id="artPath">..\art\{0}</item>

Then a node like this:

<includeAttribute name="src" item="artPath">

Will be transformed into this:

</img src="..\art\LastChild.gif" temp_src="..\art\LastChild.gif">


Simply applies an xsl transform to the document.

Other components

These are components that I’m not really sure about how they work since they aren’t used in the example given.


Seems to be used to include a set of common sample code snippets. Not sure, but I think it looks for comment links with the following signature:


Seems to be used for linking to common image files?


Looks quite similar to the ResolveReferenceLinksComponent, and I’m not really sure about the difference.

Well, this turned out to be a rather long post. In the next session, I’ll explain how the sandcastle.config is currently wired to build the sample project


Also check out Part 1 and Part 3

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

About Me

Consultant, Solution Architect, Developer.

Do note that this blog is very, very old. Please consider that before you follow any of the advice in here!


%d bloggers like this: