Using Visual Studio Online to Build with SHFB

Topics: Developer Forum, Project Management Forum, User Forum
Jan 13, 2014 at 4:29 PM
Hi folks,

On my workstation, I use the SHFB plug-in for VS 2013 to build our API documentation. It works well to produce a .CHM file.

Our source control is at so I'm wondering whether I can automate the build process on TFS by shifting the essential elements to the server in the clouds.

I've looked at the starter topic at It isn't clear to me how to set up the Source Settings including Source Control Folder and Build Agent Folder.

Where to I put my Sandcastle and SHFB binaries and config files to have everything built on

If someone could point me to a tutorial or sample script, I'd be very grateful - and probably flesh out some documentation for anyone else who comes along.


Jan 13, 2014 at 7:22 PM
Edited Jan 13, 2014 at 7:25 PM
First a couple of general comments:
  1. Bear in mind that I haven't used the visualstudio,com online version of TFS so this is just speculation on my part.
  2. This will most likely be much easier with the next release I plan on publishing in a couple of weeks since I've consolidated the tools under a single installation folder with a single environment variable/project property (SHFBROOT) used to locate the tools. It also uses MEF to locate all third party build components, plug-ins, syntax generators, and presentation styles so they can all reside in a common location alongside the tools and supporting files.
Based on item 2 above, reading the documentation on the Hosted Builder Controller page, the "Add assemblies for custom activities and other unit test frameworks" section would seem to make this possible. You'd create a folder to contain the content of the SHFB installation folder along with any third party components. You probably wouldn't set the path as given on that page. Instead, you'd add a conditional property to your SHFB project that defines SHFBROOT conditionally upon it not being defined already:
<SHFBROOT Condition=" '$(SHFBROOT)' == '' ">..\..\RelativePath\ToSHFB\Adjust As Needed</SHFBROOT>
On your local PC, it would find the standard SHFBROOT environment variable and use it. On the build server it would use the local project property to find the tools relative to the project path.

As I said, speculation on my part but it might work. It's possible it may work with the current release but you'd have to set both SHFBROOT and DXROOT and combine the SHFB and Sandcastle Tools folder content. The code is also a lot more dependent on the environment variables in the current release so that may cause it problems.

Jan 13, 2014 at 7:30 PM
Thanks Eric! You're a busy lad!

Perhaps I'll hang back until your next release and give it a shot. It certainly would be convenient to drop in the assemblies and kick off the build.

If that works, I'll try chaining in a build of the final help that uses MadCap Flare's madbuild command line tool.

Jan 23, 2014 at 1:43 AM
I use for my source control, however I doubt that their in-cloud build servers will be usable for doing these kinds of builds, given things actually need to be installed on the build server. The good news is you can setup a locally hosted build server (on your own network) that the cloud TFS can talk to and start builds.

It doesn't take a lot of work to setup:

1) Install Team Build on your build server. You can use TFS Express and only install the build portion if you wish (which is what I did).
2) Open up the TFS Administration Console
3) Go to Build Configuration, and configure it there. You'll need 1 controller, and at least 1 agent.

NOTE: The controller manages the agents on the machine, and the agents are what perform the builds. I personally like having at least 2 agents configured so I can run more than one build at a time.

4) From inside Visual Studio, open Team Explorer
5) Edit the build you wish to use your new local build controller.
6) Click the Build Defaults tab, and change the Build Controller listed in the drop down to use the controller you configured in step 3.

The only issue I've had with SHFB so far from a build server is that it ignores command-line options and outputs the files to the wrong location since it's not being built from within Visual Studio. So instead of the generated file going into the Binaries special output folder used by TFS like it should, it sits in the sources folder. Any packaging processes you have in place will need to take that into account, aside from that it works fine.