MSBuild script for Sandcastle


After installing the August CPT of Sandcastle, you’ll need to update to the latest version of the MSBuild script.

The MSBuild script has been improved to work with Help Compiler 2. Check out the new instructions!

Last friday, Microsoft finally released a CTP version of Sandcastle. For this initial release however, they didn’t really focus on usability, and that shows! The 11-step instructions you need to follow just in order to compile the sample documentation are not really straight-forward..

There have already been some contributions to help you on your way; Mikael Söderström has created a Sandcastle Helper, there is a batch script from Ashley van Gerven, and a Power shell script from Scott Hanselman.

But what I really missed was some sort of MSBuild-integration, so I’ve spent the day building a .targets-file that can be used to simplify your Sandcastle builds greatly!

You can download the following files:

    Unzip the contents of this file to c:\Program Files\MSBuild\Sandcastle.
    This file contains a sample solution and a sample MSBuild script (called Documentation.proj).

Instructions for trying this out:

  1. If you haven’t already done so, install the Sandcastle June CTP. The scripts rely on a completly unmodified installation, so don’t make any changes to it (especially not the sandcastle.config file).
  2. Unzip the contents of to your MSBuild folder (usually c:\Program Files\MSBuild)
  3. Unzip the contents of to wherever you like to keep your sample projects.
  4. Open up the SandcastleTest.sln solution file and build the project.
  5. Open a Visual Studio 2005 Command prompt, navigate to the SandcastleTest folder and run the following command:

    MSBuild Documentation.proj

  6. Cross your fingers, and when the process is finished, look for the Output\SandcastleTest.chm file!

Please post any errors and/or comments! The next step will be to try to integrate this script in the Team Foundation Build process.. I’ll keep you posted..


I’ve updated the script to work better with the Visual Studio plugin

Update 2

If you’re interested in the inner workings of Sandcastle, check out my Sandcastle under the hood-series: Part 1 and Part 2 and Part 3

20 responses to “MSBuild script for Sandcastle”

  1. I just tried your procedure and it worked really great, first time too. 😉 Thanks for sharing and keep up the good work.


  2. I haven't tried it yet, but it's what I'm looking for. Will download and give it a go. Thanks for your efforts!Max


  3. Very nice!!Btw, I see a drop down box in the generated help file with "C#" and "Visual Basic". Changing this drop down value to "Visual Basic" does not change the syntax. (Not that I am interested in VB!! ;)Anyway clicking on the buttons (or links) of 'C#', 'Visual Basic' and 'Managed C++' works!!This is pretty cool!!Thanks,Sarah


  4. I see the below text as a foot note in each page. Can we change this!?————————————(c) Microsoft Corporation. All rights reserved. Send comments about this topic to Microsoft.


  5. Anders Ljusberg Avatar
    Anders Ljusberg

    Well, all the html-files are built using xml/xsl transforms, and all the source files for those are found in C:\Program Files\Sandcastle\Presentation, so I'd have a look around there if I were you.Actually, it seems that the particular string you're looking for is found in C:\Program Files\Sandcastle\Presentation\Content\shared_content.xml


  6. Well, once again the Internet has shown that there are some very very very smart people out there. Thanks a heap!


  7. Thanks for pointing this out to me over on Anand's Sandcastle blog. I'm using this script to generate docs for multiple assemblies, and it's working fine.Now I'm looking at modifying the SandcastleConfigurator.vbs file so I can use my own shared_content.xml file instead of Microsoft's.Bill Menees


  8. Conrad Agramont Avatar
    Conrad Agramont

    In the Documentation.proj file, if you provide a "HelpName" that has a space in it, it fails on line 101 of the targets file.Took the space out, it worked fine.What wasn't obvious to me was that I was to copy the documentation.proj file to my own project folder and make the updates to that. I guess I missed something on your site or something. Anyhow, the script works well…now I have a lot of commenting to do in my code!I have a new tool that I'm building called provware. I plan to use Sandcastle and your script to build the documentation.


  9. Frank Kroondijk Avatar
    Frank Kroondijk

    For all the people who like it nice and easy, I wrote a Visual Studio 2005 Add-In, free for download, incl. source. Document your libs without leaving VS :-)Intro Video:,Frank Kroondijk


  10. Frank Kroondijk Avatar
    Frank Kroondijk

    Working links:Sandcastle Add-In VS2005video


  11. Great work, thanx!

    I'm trying to build a help file for a Visual Studio 2005 Add-In. This works but only partially, as the "BuildHTM" target is generating "unresolves reference target" warnings for all references to types from the EnvDTE, EnvDTE80 and Extensibility libraries. I added the filepaths of all three libraries to the <Dependencies> section of the Documentation project file, but the BuildAssembler utility is still complaining about unknown references.

    Am I missing something?



  12. Anders Ljusberg Avatar
    Anders Ljusberg


    I think that the BuildAssembler simply complains that it couldn't find any relected xml for those assemblies. You may be able to fix this by including the ENVDTE-assemblies in the &lt;assemblies&gt;-element instead of as dependencies – that should generate reflection xml for those as well.


  13. I found another free addin for visual studio that works very well. You should take a look at and download their free addin to generate documentation using sandcastle.


  14. Thanks for this!!! The first “helper” that was working right a way


  15. Thanks a lot Anders..

    I am new to SandCastle and after installing it and going through the steps, I was thinking why Microsoft made it so tedious…

    But now your script made it so simple..

    Great work!!


  16. Love this script – to be honest I looked at Sandcastle when it first came out and decided it was TOO much hassle. With an MSBuild task it is now trivial.

    What confuses me, however, is why I need to go to the command line to invoke this – I though the point of an MSBuild task was that MSBuild would do it and as VS.NET uses MSBuild itself why doesn’t the task running when I build the solution?

    I know it is a long running task so I assume that is the reason? Or is it just because you wouldn’t be able to edit the build comfortable with VS.NET?


  17. David L.Pruett Avatar
    David L.Pruett

    When building (step 5) I get error message stating that Files missing from C:\ ProgramFiles
    \Sandcastle \ProductionTransforms\AddOverload.xsl could not be found. I then went to
    to get the latest Sandcastle – but this did not help.

    Any suggestions greatly appreciated.
    Thank you.


  18. I am getting the same problems with missing transform files with the June CTP. I even downloaded the latest script from codeplex.

    Any Suggestions?


  19. The March 2007 Sandcastle CTP removed several xsl files and reworked how some of the transformations occur. When you download the latest Sandcastle, look in the build_Sandcastle.bat file to see how the new transformation are structured. Then you’ll have to modify the MSBuild targets to emulate them. This is also true of any Sandcastle CTP since March (June, and for next week.. September)


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

About Me

Consultant, Solution Architect, Developer.

Do note that this blog is very, very old. Please consider that before you follow any of the advice in here!


%d bloggers like this: