Creating Custom Components
In addition to the help file builder project template, component project templates are provided in Visual Studio to create custom build components, plug-ins, syntax generators, and presentation styles. Templates are provided for C# and VB.NET and appear in the given language categories in the Documentation subcategory.
The following component project templates are available:
Sandcastle Help File Builder Plug-In - Create a build process plug-in used to extend or alter the help file builder build process.
BuildAssembler Build Component - Create a build component for use with the BuildAssembler tool that can alter the topics in some way as they are being generated.
Build Component/Plug-In Configuration Editor - Create a configuration editor for a build component or plug-in. This allows you to configure the component or plug-in interactively from within the standalone GUI or Visual Studio. The configuration editor is placed in a separate assembly from the component or plug-in as the editors are specific to the Windows platform. This allows the components to remain platform-neutral and usable with either MSBuild or dotnet build.
BuildAssembler Syntax Generator - Create a syntax generator for use with the BuildAssembler SyntaxComponent used to create declaration or usage syntax sections within topics.
Sandcastle Presentation Style Component - Create a presentation style component to add a new presentation style used to format the topics. This template provides a shell into which you can copy the content files from an existing presentation style or start from scratch and add all new content.
Once the project has been created, see the comments in the template source code for things to do to implement the given component. Refer to the related topics in the See Also section below for more information on creating the components.
Common Traits
All component project templates are set up to generate .NET Standard 2.0 assemblies. As noted above, this allows the components to remain platform-neutral and usable with either MSBuild or dotnet build. In addition, the necessary properties are defined to automatically generate a NuGet package from the build output.
Each component project has a .\build folder containing a .props file that defines a single SHFBComponentPath item that equates to the path of the .\tools folder for the NuGet package. This allows the help file builder to locate the component when adding it to the project via the related property page and at build time so that it can be used.
Additional supporting files can be added to the project such as configuration files or other content files. These will be added to the package's .\tools folder as well. If placed in subfolders within the project, the folder structure will be retained when compiled into the package.
The configuration UI project template is the exception to the above. It is set to generate a .NET 4.7.2 assembly as it will only be used from the standalone GUI or Visual Studio on the Windows platform. In addition, it does not generate a NuGet package. Instead, you will include the assembly in your component package as an additional assembly. Instructions are given in the UI project template example source code and the build component and plug-in project files on how to do this. The configuration forms can be created with Windows Forms or XAML. An example of each is provided in the template project as a starting point.