This topic describes the parts of a custom build component configuration file and how to create one.

Component Configuration Files

Custom build components can easily be added to the Sandcastle Help File Builder without having to modify its configuration template files. This is accomplished by creating an XML configuration file that describes the custom build component along with how and where it should be merged into the configuration file template at build time. The custom build component assembly, configuration file, and any supporting files are copied into the .\Components and Plug-Ins folder or a subfolder beneath it in the help file builder's Common Application Data folder. See the Special Folder Locations topic for more information. The component configuration files must use the extension .components. A sample configuration is shown below:

CopySample Custom Build Component Configuration
<?xml version="1.0" encoding="utf-8"?>

<!-- CustomComponent.components example -->
<components>
  <component id="IntelliSense Component"
    type="SandcastleBuilder.Components.IntelliSenseComponent"
    assembly="{@SHFBFolder}SandcastleBuilder.Components.dll">
      <description>This build component is used to extract the XML
comments into files that can be used for IntelliSense.  Only the
basic set of tags needed for IntelliSense are exported and only for
documented API members.</description>

      <dependencies>
          <component id="Show Missing Documentation Component" />
      </dependencies>

      <insert placement="after"
        id="Show Missing Documentation Component" />

      <!-- <insertConceptual /> Not used for this one -->

      <configureMethod name="ConfigureComponent" />

      <defaultConfiguration>
          <output includeNamespaces="false"
            namespacesFile="Namespaces"
            folder="{@OutputFolder}" />
      </defaultConfiguration>
  </component>
</components>

Component Configuration Elements

The root components node contains one or more component nodes that describe the build components. The order of the component definitions is not significant. The help file builder uses this information to merge them with the configuration file at build time and also to allow users to configure them interactively from within the GUI. The Sandcastle Help File Builder supports several replacement tags that can be specified in place of such things as the components folder, the project folder, etc. These will be replaced before use with the physical path associated with the project.

The following sections list the elements and their attributes that make up the definition for a component node.

For a working example of a component configuration file, see the SandcastleBuilder.components file in the help file builder installation folder. It contains a fully commented set of configurations for the custom build components supplied with the help file builder.

component

This element contains all of the other elements. The element itself has three required attributes:

  • The id attribute gives the component a unique ID. This is used in the configuration dialog as a friendly name that is more easily recognized. It is also used by the other elements in the configuration to identify the build component.
  • The type attribute provides the fully qualified type name of the build component.
  • The assembly attribute provides the location of the assembly that contains the indicated type. Normally, you will use the {@ComponentsFolder} replacement tag to represent the path to the .\Components and Plug-Ins folder. However, the assembly can be located in any other location. Just be sure that the path is correct.

description

This element is used to provide a brief description of the build component. This will appear in the configuration dialog when the build component is selected in the list of available build components.

dependencies

This element is used to specify a list of components on which the current component depends. If the indicated components do not exist in the project settings or in the configuration file template already, they will be added automatically with their default configuration at build time. This element can be omitted if there are no dependencies. To specify dependencies, add a nested component element for each one with a single id attribute set to the ID of the required component. Dependent configurations are merged prior to project settings. As such, it is not required that a dependent component appear in the project as well. If it does, the project settings will override the default configuration.

insert

This element is the most important one. It defines where the component configuration is inserted into the reference (API) configuration template file at build time (sandcastle.config). The following attributes can be used to define the placement options.

  • The placement attribute defines where to insert the configuration. It can have one of the following values:

    • start - The configuration is inserted at the start of the configuration file ahead of all others. If multiple build components use this option they are all inserted at the start in no particular order. All other attributes are ignored if this option is used.
    • end - The configuration is inserted at the end of the configuration file after all others. If multiple build components use this option they are all inserted at the end in no particular order. All other attributes are ignored if this option is used.
    • before - The configuration is inserted before the component indicated by the id/type and instance attributes.
    • after - The configuration is inserted after the component indicated by the id/type and instance attributes.
    • replace - The configuration for the custom component replaces a different component in the configuration template indicated by the id/type and instance attributes.
    Note

    If a component already exists in the configuration file with a matching id attribute it is assumed to be the same component in the correct location and is automatically replaced with the custom configuration.

  • The id attribute can be used to identify another component in the configuration file by ID.
  • The type attribute can be used to identify another component in the configuration file by type name. For example, the stock Sandcastle components do not have IDs in the configuration file template. By specifying their type name, you can merge custom components before or after them without having to assign an ID to them first.
  • The instance attribute can be used to identify a specific instance of a build component in the configuration file. For example, the CopyFromIndex component appears multiple times in the standard configuration file. If you need to merge a custom build component before or after one of these occurrences, you can use this attribute to specify which one. If omitted, the first instance is assumed.

If this element is omitted, the build component will not be useable in reference builds.

insertConceptual

This element is similar to the insert element above. However, it defines where the component configuration is inserted into the conceptual content configuration template file at build time (conceptual.config). It uses the same attributes described above to define the placement options. If omitted, the build component will not be useable in a conceptual content build. If a component has both, like the CodeBlockComponent, it can be used in both build types.

configureMethod

This element can be used to identify the name of the static (shared) method that the help file builder can invoke to configure the component interactively from the project manager GUI. The named method should accept a string as a parameter that contains the current component configuration as an XML fragment and should return a string containing the edited component configuration as an XML fragment. The configuration passed and returned is in the format that is inserted into the configuration file at build time. If the build component does not contain a configure method, this element can be omitted and a default editor will be used. Specify a dash ("-") for the name if the component contains no editable configuration information.

defaultConfiguration

This is used to specify the default configuration for a custom build component. This information is used when the component is added as a dependency and when the component is added to the project and the user does not modify it. You can use the various replacement tags as attribute values. These will be replaced at build time with the appropriate project values.

hidden

This element can be used to hide a component in the help file builder's configuration dialog box. The component will still be merged if it is a dependency but it will not show up in the configuration dialog box so that the user can add it to the project with a custom configuration.

Making a Stock Build Component Editable

By creating a configuration file for one of the stock build components such as ResolveReferenceLinksComponent2 or one of the many other build components that are not included by default, you can add the ability to edit their configurations. Simply create a new configuration file with the necessary information. Since stock build components do not have a configuration method, omit the configureMethod element and the standard editor will be used to allow you to modify the raw XML configuration data.

See Also