Click or drag to resize
Sandcastle Help File BuilderXCOPY/NuGet Build Server Deployment

For use in a build server environment, the Sandcastle Help File Builder and Tools support simple XCOPY deployment. As long as the SHFBROOT system environment variable points to the location of the help file builder assemblies, it will be able to find everything it needs at build time. In such situations, custom build components, plug-ins, syntax generators, and presentation styles may also be copied to the help file builder folder or a sub-folder beneath it.

A NuGet Package is also available (EWSoftware.SHFB) that allows you to deploy the Sandcastle Help File Builder tools inside of a project to build help files without installing the tools manually and without defining the SHFBROOT environment variable. Certain limitation apply in this case and are detailed in the package's Read Me file which is displayed when the package is installed.

When searching for custom components, the following search order is used:

  • If a ComponentPath project property value is set, the folder it refers to is searched first and then the actual project folder is searched. If the property contains no value, the actual project folder is searched first.

  • Next, the common application data folders noted in the Special Folder Locations topic are searched.

  • Finally, the help file builder installation folder (SHFBROOT) is searched.

If any duplicate components are encountered, the first one loaded based on the above search order will be used.

It is possible to build a project without defining the SHFBROOT environment variable such as when using the NuGet package. To do this, a conditional SHFBROOT property must be added to each help file builder project as a child of the main PropertyGroup element. An example is shown below (lines wrapped for display purposes):

Copy
<PropertyGroup>
  <!-- NOTE: Update the version number in the path to match the package version -->
  <SHFBROOT Condition=" '$(SHFBROOT)' == '' ">$(MSBuildThisFileDirectory)..\packages\
EWSoftware.SHFB.2014.11.22.0\Tools\</SHFBROOT>

  ... other SHFB project properties ...

</PropertyGroup>

By making it conditional, you can work with the project on your local machine with the available tools where the environment variable is defined but still allow it to be built on a server using the XCOPY/NuGet deployment.

Important note Important

The Help 1 and MS Help 2 help file formats are unsupported in the XCOPY/NuGet deployment scenario as they require additional tools and components to be installed. If these tools and components are missing on the build server, the help file build will fail. Only the Website, MS Help Viewer, and Open XML help file formats are guaranteed to work as they have no external tool dependencies.

See Also