This topic describes the additional tools that are required to use the Sandcastle Help File Builder along with some general configuration information.
Due to the number of products that need to be installed to get a working build environment, a guided installation package has been created to simplify the process. The guided installer contains most of the necessary parts and various optional components. For those parts that cannot be distributed such as the help compilers, it contains instructions on where to get them and how to install them if you need them.
Download the latest Sandcastle Help File Builder Guided Installer
When using the guided installation, you can skip the Requirements section below as it takes care of all of the required steps. See the Recommended Additions sections for additional tools not included in the guided installation that you may find useful.
The help file builder tools and the Visual Studio package can be installed manually by running the MSI and VSIX installers found in the .\InstallResources folder extracted from the guided installer download. If installing the tools manually, the optional components such as the snippets will not be installed. You will also need to ensure the requirements noted below are also present if needed.
The latest version of the Sandcastle Help File Builder and Tools can always be found at the Sandcastle Help File Builder project site (v2024.9.12.0 when this help file was produced).
.NET Framework 4.7.2 or later is required to run the desktop tools and build projects with MSBuild.
.NET Core 3.1 or later is required to build projects with dotnet.exe.
If you are using the standalone GUI to build help file projects, you will need to install the Microsoft Build Tools for Visual Studio 2017 or 2019. If you are using Visual Studio 2017 or later to build help file projects, there is no need to install the build tools separately. The version of MSBuild deployed with Visual Studio will work as expected from the command line or within Visual Studio.
Note
The underlying Sandcastle tools were originally created by Microsoft. The help file builder uses them to produce the help file topics. Microsoft officially discontinued development in October 2012. The Sandcastle tools have been merged with the Sandcastle Help File Builder project and are developed and supported there now as part of that project.
In order to use the help file builder, the following additional tools are required based on the types of help files that you want to produce. Each must be installed prior to building a help file of that particular type:
The HTML Help Workshop for building HTML Help 1 (.chm) help files. The Microsoft download link appears to have been discontinued. If you need a copy to install, it can be downloaded from the Sandcastle Help File Builder project website
The Microsoft Help Library Viewer for installing and viewing Microsoft Help Viewer (.mshc) help files. These are installed as part of Visual Studio.
The additional tools can be installed in any order.
Note
You may need to reboot the system in order for any environment variable changes to take effect.
The following tools are optional but you may find them useful:
If you need a spell checker for Visual Studio, the Visual Studio Spell Checker extension can be downloaded and installed from the Visual Studio Gallery. It is an editor extension that checks the spelling of comments, strings, and plain text as you type or interactively with a tool window. Support is included for spell checking source code, XML files, and MAML topic files. Versions are available for Versions are available for Visual Studio 2013 and 2015, Visual Studio 2017 and 2019 and Visual Studio 2022 and Later.
For extended XML comments completion support in Visual Studio 2019 and later, install the Extended XML Documentation Comments Completion Provider extension which can be downloaded and installed from the Visual Studio Gallery. Versions are available for Visual Studio 2019 and Visual Studio 2022 and later.
For a Visual Studio add-in used to create XML comments automatically, check out SubMain's GhostDoc.