The Sandcastle Build Component Templates 1.1 release provides two C# Item Templates that you can use to easily create custom Sandcastle Build Components in Visual Studio 2005 and Visual Studio 2008.
In this blog post I intend to provide some details about the templates, with more focus on hosted components and DocProject's API. Instructions for template installation and usage can be found here.
Basic Sandcastle Build Component Item Template
The Basic Sandcastle Build Component item template is a multi-file Visual Studio Item Template, written in C#, that provides a working example of a custom build component that can be used for command-line builds or with editor support in automation tools such as DocProject and the Sandcastle Help File Builder. It comes with a built-in graphical editor and a dynamic sub property for the DocProject Properties window, which can be shown by expanding the component in a build component stack (for more information about the stack properties, see How To Use Third-Party Sandcastle Components in DocProject).
Hosted Sandcastle Build Component Item Template
The Hosted Sandcastle Build Component item template is the same as the basic template, but it also provides direct access and a working example of how to gather information from DocProject's API, thus DocProject is required in order to compile the build components that are created based on this template. Although, DocProject isn't actually required to use the components if you provide a fall-back initialization path.
Initialization Paths
The template's Configuration class provides two initialization paths, one of which is a fall-back that's automatically invoked if the DocProject host API is not detected.
Note: The host API is never available during builds - it's only available when the component's editor is displayed.
Fall-back initialization works since the template depends upon just-in-time (JIT) compilation. If you properly encapsulate the use of host interfaces, as the template does out-of-the-box, then you can control the initialization path of the component's Configuration class.
The template's Host class is used to encapsulate host interfaces and services, and it provides a way to safely check, at runtime, whether a particular host is reachable. Support for DocProject's host API is built-in to the template. All other hosts will use the fall-back initialization path automatically unless you add support for them to the Host and Configuration classes. The only requirement is that the host invokes your component's editor by calling its EditValue method and passes in an IServiceProvider implementation that can be used to obtain a reference to one or more of the host's services. (On a side note, the value argument should be set to a System.Xml.XPath.IXPathNavigable implementation that's positioned on the outer XML of the component's configuration, which includes the <component> element itself.)
Modifying Project Options
The template gathers read-only data as an example and does not actually modify any build settings or project options at runtime. If you want your component implementation to write to the API, then make sure there's a clear relationship between your component and the changes that it's making.
For example, a proprietary AuthorBuildComponent changing the value of the Generate root API topic setting when edited will probably not be obvious to end-users. But it might be appropriate for the same component editor to add external sources if, for example, it were to provide a way for an end-user to create a list of associations between sources and author names, much like the Version management dialog does with version information. In this case, the component's editor could save the input-to-author mappings as its inner XML configuration data and add the external sources as a convenience for the user.
Hosted Components as Plug-Ins
Hosted build components are not meant to be a plug-in mechanism for DocProject, per se, but instead are a plug-in mechanism for Sandcastle. DocProject's API is exposed merely to provide a more user-friendly and integrated experience when editing Sandcastle build components in DocProject.
If you want to create a true DocProject plug-in, then create a custom build engine provider or a build process component, which can provide control over all aspects of DocProject, including the entire build process, engine settings, project options, tool bars, tool windows, menus, custom wizard steps in the New Project Wizard, etc.
DocProject's API for Hosted Components
With the recent release of DocProject 1.10.0 RC, a new interface was added that would provide build components access to DocProject's API, for their graphical editors. The API can be used to gather information about the environment in which the component's editor is being hosted. The component can then provide automatic configuration and apply appropriate editor defaults, simplifying configuration for end-users while also adhering to the project paradigm that DocProjects and DocSites use to store their settings.
The purpose of the gateway interface, IDocProjectHost is to provide components with access to DocProject-specific interfaces and types for the context in which the component's editor is being hosted. Here's the interface's definition:
public interface IDocProjectHost
{
IDocProject Project { get; }
BuildSettings Settings { get; }
DocProjectOptions Options { get; }
IBuildEngine Engine { get; }
IEnvironmentHost EnvironmentHost { get; }
bool RunningInVisualStudio { get; }
}
The Hosted template gets a reference to an IDocProjectHost implementation through the service provider that's passed to the editor's EditValue method. If the host is available then the Configuration class's InitializeForDocProject() method is invoked instead of the fall-back Initialize() method (see above for information about initialization paths).
The InitializeForDocProject method uses the types and interfaces exposed through IDocProjectHost to gather information, which it then stores in private fields. The fields back properties that are used by the template's EditorControl class. They are typed as nullable primitives, such as System.String and bool?, so if the values are never set then they'll remain null, in which case the EditorControl will substitute them with "Unavailable" for its read-only display.
Developers are free to remove this code (actually, it's recommended) and replace it with appropriate code for gathering information that's required by the component being developed. However, the same pattern can be used to safely encapsulate data that can be initialized with or without a host API.
Note: The configuration fields must not be typed as host-specific types or interfaces if you want to be able to use your components in other environments, without the host API installed.
Conclusion
With the release of DocProject 1.10.0 RC and the corresponding Hosted Sandcastle Build Component Item Template 1.1, developers can now have seamless integration in DocProject for their custom build components' editors, providing a more robust platform on which to configure and build documentation while potentially simplifying configuration for end-users through automation and inferred default settings.