Sandcastle Help File Builder error BE0035

A build should be as self-contained as possible and ideally contains all the tools required without having any dependencies on whether the tools are actually installed on the computer the build is running on.

Sandcastle and Sandcastle Help File Builder have proved to be tricky in this respect but a few days ago I made a concerted effort to nail down all the little gotchas that usually result in me giving up and just installing them on whatever computer I’m trying run a build on.

Sandcastle uses an environment variable called DXROOT to identify where it’s located. Similarly, the latest version of Sandcastle Help File Builder uses a variable called SHFBROOT. Sandcastle Help File Builder used to ship with a command line tool that could be called from a build but this has changed in the latest version. Instead an MSBuild project file is used to perform the build of the documentation.

This leads to a chicken and egg situation as regards trying to configure the location of Sandcastle Help File Builder in the build properties and I gave up and just set it as a relative path in the batch file used to invoke the build. Not ideal but I couldn’t see a way around that.

I thought I’d finally got a portable configuration but when I copied the build over to a build machine that didn’t have anything related to the build already installed it failed with this:

SHFB : error BE0035: Could not find the path to the Microsoft Sandcastle documentation compiler tools.  See error topic in help file for details.

Sandcastle Help File Builder’s help file indicates that this is a problem with DXROOT not being set to the location where Sandcastle can be found but I knew that I did have it set – to the build’s local copy of Sandcastle. I remembered hitting this problem before and conceding defeat but this time I was going to sort it out once and for all.

It took 30 minutes of experimentation to realise what the problem really is. Sandcastle Help File Builder is simply not using the DXROOT variable at all. In the abscence of an explicit path in the Sandcastle Help File Builder project file it simply looks in C:\Program Files\Sandcastle.

The solution is to set the value in the project file specifying the DXROOT variable as an MSBuild property:

<SandcastlePath>$(DXROOT)</SandcastlePath>

Unfortunately, this must be done using a text editor rather than the Sandcastle Help File Builder GUI tool because it insists on adding a trailing ‘\’ which makes the path invalid as the DXROOT variable usually has a trailing slash already.

Once this is done both Sandcastle and Sandcastle Help File Builder will run successfully without having to be installed.