Click or drag to resize
Sandcastle Help File Builder

XCOPY/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 limitations 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.

If your version of Visual Studio supports them, PackageReference elements can be used to add the help file builder packages to your project. The packages contain a properties file that defines the necessary project properties to define the root path and component path so that you do not have to define them manually as described below. To enable NuGet package restore, the following changes must be made to the help file builder project. Note that many of these changes may already be there if you have created a recent project. In older projects, these elements will need to be added.

At the top of the project, import the common properties file to support package restore and add the required TargetFrameworkVersion element.

<Project ToolsVersion="14.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <!-- Import the common properties to support NuGet restore -->
  <Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props"
    Condition="Exists('$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props')" />

  <PropertyGroup>
    <!-- A framework version is required for NuGet restore.  This can be any valid version -->
    <TargetFrameworkVersion>v4.5</TargetFrameworkVersion>
  .
  .
  .

Add the package references to import the help file builder tools package and the reflection data set package. Update the version attributes to the latest releases.

<ItemGroup>
  <!-- IMPORTANT: Update the package versions to the latest releases. -->
  <PackageReference Include="EWSoftware.SHFB" Version="2019.9.15" />
  <PackageReference Include="EWSoftware.SHFB.NETFramework" Version="4.8.0" />
</ItemGroup>

At the end of the project file just above the line that imports the help file builder targets, add an import for the common build targets. Also add the Condition attribute to the help file builder targets import.

<!-- Import the common build targets during NuGet restore because before the
  packages are being installed, $(SHFBROOT) is not set yet -->
<Import Project="$(MSBuildToolsPath)\Microsoft.Common.targets"
  Condition="'$(MSBuildRestoreSessionId)' != ''"/>

<!-- Import the SHFB build targets during build -->
<Import Project="$(SHFBROOT)\SandcastleHelpFileBuilder.targets"
  Condition="'$(MSBuildRestoreSessionId)' == ''"/>

If not using package references, 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):

<PropertyGroup>
  <!-- NOTE: Update the version number in the path (YYYY.M.D.R) to match the package version -->
  <SHFBROOT Condition=" '$(SHFBROOT)' == '' ">$(MSBuildThisFileDirectory)..\packages\
EWSoftware.SHFB.YYYY.M.D.R\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 file format is unsupported in the XCOPY/NuGet deployment scenario as it requires 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 MS Help Viewer, Open XML, website, and markdown help file formats are guaranteed to work as they have no external tool dependencies.

For NuGet installations, you must also install one or more of the Reflection Data Set packages based on which platform types you need: .NETCore, .NETFramework, .NETMicroFramework, .NETPortable, Silverlight, WindowsPhone, and/or WindowsPhoneApp. If multiple versions are available for any given reflection data set package, download the latest version as it will cover all prior versions as well. For example, the .NETFramework 4.8 package covers all .NET Framework versions from 1.0 to 4.8.

See Also