MSBuild script for Sandcastle 20

Update

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:

  • Sandcastle.zip
    Unzip the contents of this file to c:\Program Files\MSBuild\Sandcastle.
  • SandcastleTest.zip
    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 Sandcastle.zip to your MSBuild folder (usually c:\Program Files\MSBuild)
  3. Unzip the contents of SandcastleTest.zip 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..

Update

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 thoughts on “MSBuild script for Sandcastle

  1. Anonymous Aug 1,2006 11:04

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

  2. Anonymous Aug 1,2006 15:01

    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. Sarah Aug 1,2006 17:56

    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. Sarah Aug 1,2006 18:11

    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 Aug 1,2006 20:19

    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. Anonymous Aug 1,2006 22:18

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

  7. Anonymous Aug 2,2006 14:44

    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 Aug 4,2006 08:04

    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.

    http://agramont.net/blogs/conrad/archive/2006/08/01/Provware-Framework_2620_the-first-drop.aspx

  9. Frank Kroondijk Aug 4,2006 08:42

    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:
    http://www.overnight.nl/download/sandcastleaddin.html

    Download:
    http://dotnetpret.blogspot.com/2006/08/sandcastle-continued-documentation.html

    Cheers,

    Frank Kroondijk

  10. Frank Kroondijk Aug 4,2006 08:46

    Working links:
    Sandcastle Add-In VS2005video

  11. Zef Aug 7,2006 11:15

    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?

    Zef

  12. Anders Ljusberg Aug 7,2006 11:45

    Zef,

    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. Louis Aug 7,2006 22:05

    I found another free addin for visual studio that works very well. You should take a look at http://www.processacademy.ca and download their free addin to generate documentation using sandcastle.

  14. Anonymous Aug 11,2006 13:20

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

  15. s mathews Aug 22,2006 15:51

    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. hullion Sep 24,2006 08:37

    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 Jun 1,2007 14:54

    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 http://www.microsoft.com/downloads/details.aspx?FamilyID=e82ea71d-da89-42ee-a715-696e3a4873b2&DisplayLang=en
    to get the latest Sandcastle – but this did not help.

    Any suggestions greatly appreciated.
    Thank you.

  18. rodgel Sep 12,2007 13:07

    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. Jeremy Sep 12,2007 16:45

    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)

Comments are closed.