Coding Insomnia

Things that keep me from sleeping

MSBuild script for Sandcastle

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

,

Posted by:

codinginsomnia

20 responses to “MSBuild script for Sandcastle”

  1. Anonymous Avatar
    Anonymous

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

    Like

    Reply
  2. Anonymous Avatar
    Anonymous

    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

    Like

    Reply
  3. Sarah Avatar
    Sarah

    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

    Like

    Reply
  4. Sarah Avatar
    Sarah

    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.

    Like

    Reply
  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

    Like

    Reply
  6. Anonymous Avatar
    Anonymous

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

    Like

    Reply
  7. Anonymous Avatar
    Anonymous

    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

    Like

    Reply
  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.http://agramont.net/blogs/conrad/archive/2006/08/01/Provware-Framework_2620_the-first-drop.aspx

    Like

    Reply
  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:http://www.overnight.nl/download/sandcastleaddin.htmlDownload:http://dotnetpret.blogspot.com/2006/08/sandcastle-continued-documentation.htmlCheers,Frank Kroondijk

    Like

    Reply
  10. Frank Kroondijk Avatar
    Frank Kroondijk

    Working links:Sandcastle Add-In VS2005 – video

    Like

    Reply
  11. Zef Avatar
    Zef

    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

    Like

    Reply
  12. Anders Ljusberg Avatar
    Anders Ljusberg

    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.

    Like

    Reply
  13. Louis Avatar
    Louis

    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.

    Like

    Reply
  14. Anonymous Avatar
    Anonymous

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

    Like

    Reply
  15. s mathews Avatar
    s mathews

    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!!

    Like

    Reply
  16. hullion Avatar
    hullion

    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?

    Like

    Reply
  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 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.

    Like

    Reply
  18. anders Avatar
    anders

    You should use the new script found at:

    http://www.codeplex.com/MSBuildSandcastle

    Like

    Reply
  19. rodgel Avatar
    rodgel

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

    Any Suggestions?

    Like

    Reply
  20. Jeremy Avatar
    Jeremy

    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)

    Like

    Reply

Leave a reply to Zef Cancel reply

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!

Recent Posts

Newsletter