Calling Sandcastle with response file

· November 17, 2008

I’ve been generating documentation from our XML-comments with Sandcastle for quite some time now. It has worked alright but there were some stuff that really annoyed me, I thought that I had to put up with it. But this is the beauty of my line of work comes into play… all of a sudden we’ve got a new team member. Christer Cederborg from Avega (of course) - a great guy and very knowledgeable in things like build scripts and other. And you get to learn from each other. This is why I am in this business - sharing and knowing. OK - Christer told me that you can use something called a response file to send commands to Sandcastle. The response file is in fact just the parameters you would send to Sandcastle the command line, but in a file. This made us go around the use of .shfb-files.

Sandcastle Help File Builder is certainly a great tool when you generate the documentation manually but is sucks when it comes to incorporating it into a build script. You cannot use wildcards or relative paths in .shfb-files which complicate things in a major way. I actually created two separate file, one for local developer use and one for our build script. They were of course almost always out of sync… But with the use of a response file you can set all the commands you need to Sandcastle and get the same result.

Here is a short extract from our response file:

-assembly=SystemName.*.dll, SystemName.*.xml
-VisibleItems="InheritedMembers, InheritedFrameworkMembers, Protected, SealedProtected"

And here is how to call Sandcastle in MsBuild with the use of the response file:

    <!-- Sandcastle parameters -->
    <SandCastleExePath>C:\Program Files\EWSoftware\Sandcastle Help File Builder\SandcastleBuilderConsole.exe</SandCastleExePath>
    <SandCastleResponseFile>$(CurrentSolutionRoot)\Solution Items\Documentation\SystemName.SandCastleSettings.txt</SandCastleResponseFile>

<Target Name="GenerateDocumentation" Condition="'$(Documentation)' == 'true'">
    <!-- Clean directories -->
    <RemoveDir Directories="$(SandCastleOuputLocation)" />
    <MakeDir Directories="$(SandCastleOuputLocation)" />
    <RemoveDir Directories="$(SandCastleWorkingDir)" />
    <MakeDir Directories="$(SandCastleWorkingDir)" />
    <!-- Create the documentation with call to Sandcastle with the parameters of the response-file -->
    <Exec WorkingDirectory="$(OutDir)"
        Command="&quot;$(SandCastleExePath)&quot; @&quot;$(SandCastleResponseFile)&quot; -workingpath=&quot;$(SandCastleWorkingDir)&quot; -outputPath=&quot;$(SandCastleOuputLocation)&quot;" />
    <!-- Clean working directory -->
    <RemoveDir Directories="$(SandCastleWorkingDir)" />

Twitter, Facebook