Click here to Skip to main content
15,396,019 members
Articles / Programming Languages / C#
Posted 31 Jul 2006


54 bookmarked

Sandcastle CHM-compile BAT script and configuration utility

Rate me:
Please Sign up or sign in to vote.
4.81/5 (18 votes)
5 Aug 20064 min read
Create MSDN-style class documentation CHM files for your assemblies using Microsoft Sandcastle CTP with this configuration utility and BAT script.



Sandcastle is Microsoft's new tool for generating MSDN-style documentation from your .NET assemblies and in-code XML comments. More info here^. On 29 July 2006, they released the CTP, and the blog soon followed up with an 11-step manual process to generate the CHM file using their test class. It seemed easy enough to create a BAT script to accomplish all this automatically, however, there were a few issues that made this non-trivial. I've come up with a BAT script to automate this process, as well as a configuration utility.


  • Multiple assemblies supported.
  • Simply re-run the BAT script when you need to recompile your documentation (no need to run a GUI and re-select assembly/comments files).
  • Doesn't overwrite help project if it exists (so you can modify it in the Help workshop - especially handy for setting the default page so you don't get the ! icon when you open the CHM).
  • Option to keep or delete the working files after compiling your CHM.
  • The configuration utility automatically fills the XML path and the CHM path when you select your assembly. (So long as the XML file exists and the CHM field is empty.)


  • BAT script doesn't have any nice logging or friendly messages or error handling.

Configuration Utility

Browse for your .NET assembly. If an XML file with the same path exists, the XML path is automatically set. The CHM path is also automatically set using the same path, unless you specified a CHM path already. If you check the Delete working files checkbox, the "output" folder containing the HTML help project, HTML files, art files etc., will be deleted by the batch script.

Click Create BAT, which will customise the BAT script and save it to the same folder that you selected for the CHM file (filename: sc_compile.bat). And the customised sandcastle.config file will also be saved to this folder (with the correct paths as per the manual setting in template.xml). Now, just double click sc_compile.bat and wait for it to work its magic. You should end up with the CHM file that you specified.

Note: You can move the sc_compile.bat and sandcastle.config to another folder if you want - the BAT script will run from anywhere. When it runs, it creates an output folder which is where all the working files are generated/copied to. If you have checked the checkbox in the configuration utility, then this folder is automatically deleted once the CHM compile is complete.

What's this template.xml?

Well, I'm not a big fan of XSLT for simple template transformations. And the String.Format() can be really confusing with various {0}..{n} scattered throughout the source string. A few years ago, I created a class to perform replacements by processing replacement variables which correspond to element names.

In template.xml, you can edit two settings that are not editable using the configuration utility. They are: SandCastleInstallPath and HtmlHelpInstallPath. If you select different install paths for Sandcastle or HTML Help, you will need to change these values manually.

Two small excerpts from template.xml:

<AssemblyPath>C:\test_sc\assembly here\ScrollingGrid.dll</AssemblyPath>
<XmlCommentsPath>C:\test_sc\assembly here\ScrollingGrid.xml</XmlCommentsPath>
MRefBuilder "{$AssemblyPath$}" /
copy "{$XmlCommentsPath$}" comments.xml

As you can guess, {$AssemblyPath$} gets replaced with the AssemblyPath node's text. The class to perform this replacement functionality is included in the source.


  1. Sandcastle
  2. HTML Help 1.4 SDK
  3. .NET framework 2.0

BAT Script

This is the latest edition of the BAT script:

Text has been wrapped in the snippet below to avoid page scrolling.

if not exist output mkdir output
cd output
if not exist comments mkdir comments
del comments\*.xml
copy "C:\Inetpub\wwwroot\_dev\ScrollingGrid\bin\asb\*.xml" comments
MRefBuilder "C:\Inetpub\wwwroot\_dev\ScrollingGrid\bin\asb\*.*" 
XslTransform "C:\Program Files\Sandcastle\ProductionTransforms\AddOverloads.xsl" 
    | XslTransform "C:\Program Files\Sandcastle\
XslTransform "C:\Program Files\Sandcastle\ProductionTransforms\
              ReflectionToManifest.xsl"  reflection.xml 
if not exist html mkdir html
if not exist art mkdir art
if not exist scripts mkdir scripts
if not exist styles mkdir styles
copy "C:\Program Files\Sandcastle\Presentation\art\*" art
copy "C:\Program Files\Sandcastle\Presentation\scripts\*" scripts
copy "C:\Program Files\Sandcastle\Presentation\styles\*" styles
BuildAssembler /config:../sandcastle.config manifest.xml
XslTransform "C:\Program Files\Sandcastle\ProductionTransforms\
             ReflectionToChmContents.xsl" reflection.xml 
             /arg:html="html" /out:"Test.hhc"
if not exist help_proj.hhp copy "C:\Program Files\Sandcastle\
       Presentation\Chm\test.hhp" help_proj.hhp
"C:\Program Files\HTML Help Workshop\hhc.exe" "%CD%\help_proj.hhp"
@copy "Test.chm" "..\doc.chm"
@cd ..
REM @rd /s /q output

As you can see, all the paths are configured. The tricky part while developing this was figuring out what customisation sandcastle.config required to be able to find its assemblies and XML files and generate the HTML files to the correct directory. There was no documentation about this at the time, nor any documentation about the arguments.

Note: Sandcastle installation adds C:\Program Files\Sandcastle\ProductionTools to the Windows PATH environment variable. However, if you have an issue running MRefBuilder, XslTransform, and BuildAssembler, you can convert these calls to absolute paths (just update template.xml).


I think Microsoft have done a good job on the interface of the generated HTML files (i.e., DHTML capabilities etc.), which is the main thing that piqued my interest in this release. I haven't seen any good quality MSDN-style documentation from other documentation compilers - but I must admit I haven't experimented with the latest version of NDOC.


  • Link label to open output directory. (5 Aug 2006)
  • Now supports wildcards (i.e., class documentation for multiple assemblies in the same CHM file). As you can see in the screenshot, just specify *.* as the assembly file, and *.xml as your comments file. The BAT script and sandcastle.config have been updated to support this, and it is working well for me. (2 Aug 2006)


This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here


About the Author

Ashley van Gerven
Australia Australia
Ash is a C# developer (MCAD) with a background developing e-commerce and content management solutions. His current role includes working with VOIP systems, integration and maintenance of business and billing apps. His personal projects include the ScrollingGrid web control to enable cross-browser freeze-header 2-way scrolling of DataGrids. His other interests include travel, cinema, Squash, photography, Muay Thai.

Comments and Discussions

NewsAnother solution Pin
Victor Blomberg29-Apr-07 12:41
MemberVictor Blomberg29-Apr-07 12:41 
QuestionError - Not able t o copy ".output\test.hhc" Pin
kidambiN19-Sep-06 15:49
MemberkidambiN19-Sep-06 15:49 
AnswerRe: Error - Not able t o copy ".output\test.hhc" Pin
Ashley van Gerven19-Sep-06 20:27
MemberAshley van Gerven19-Sep-06 20:27 
GeneralRe: Error - Not able t o copy ".output\test.hhc" Pin
kidambiN20-Sep-06 5:17
MemberkidambiN20-Sep-06 5:17 
AnswerRe: Error - Not able t o copy ".output\test.hhc" Pin
andyqp12-Oct-06 4:38
Memberandyqp12-Oct-06 4:38 
GeneralNDoc alpha vs. Sandcastle Pin
MirkoMaty8-Aug-06 22:08
MemberMirkoMaty8-Aug-06 22:08 
GeneralRe: NDoc alpha vs. Sandcastle Pin
Eric Woodruff9-Aug-06 5:07
professionalEric Woodruff9-Aug-06 5:07 
GeneralRe: NDoc alpha vs. Sandcastle Pin
Joel Thoms5-Sep-06 12:26
MemberJoel Thoms5-Sep-06 12:26 
GeneralRe: NDoc alpha vs. Sandcastle Pin
Jamie Nordmeyer24-Oct-06 6:43
MemberJamie Nordmeyer24-Oct-06 6:43 
GeneralVisual Studio 2005 Sandcastle Add-In [modified] Pin
mystic7004-Aug-06 1:52
Membermystic7004-Aug-06 1:52 
QuestionRe: Visual Studio 2005 Sandcastle Add-In Pin
Gfw8-Aug-06 3:40
MemberGfw8-Aug-06 3:40 
AnswerRe: Visual Studio 2005 Sandcastle Add-In Pin
mystic7008-Aug-06 7:57
Membermystic7008-Aug-06 7:57 
GeneralRe: Visual Studio 2005 Sandcastle Add-In Pin
Gfw8-Aug-06 8:02
MemberGfw8-Aug-06 8:02 
GeneralNice Work Pin
M Harris2-Aug-06 19:07
MemberM Harris2-Aug-06 19:07 
Generalrepath issues Pin
dalkema1-Aug-06 4:03
Memberdalkema1-Aug-06 4:03 
GeneralRe: repath issues Pin
Ashley van Gerven1-Aug-06 4:41
MemberAshley van Gerven1-Aug-06 4:41 
GeneralNice work Pin
luis de santiago31-Jul-06 23:03
Memberluis de santiago31-Jul-06 23:03 
GeneralRe: Nice work Pin
Ashley van Gerven31-Jul-06 23:22
MemberAshley van Gerven31-Jul-06 23:22 
GeneralException Pin
helpsoft.ru31-Jul-06 19:45
Memberhelpsoft.ru31-Jul-06 19:45 
GeneralYou need to copy files from Demo zip Pin
Ashley van Gerven31-Jul-06 21:21
MemberAshley van Gerven31-Jul-06 21:21 
GeneralNicely (and quickly) done Pin
Ed.Poore31-Jul-06 8:18
MemberEd.Poore31-Jul-06 8:18 
GeneralRe: Nicely (and quickly) done Pin
Ashley van Gerven31-Jul-06 23:32
MemberAshley van Gerven31-Jul-06 23:32 
GeneralNicely Done Pin
Mortman31-Jul-06 6:25
MemberMortman31-Jul-06 6:25 
GeneralRe: Nicely Done Pin
Ashley van Gerven31-Jul-06 23:26
MemberAshley van Gerven31-Jul-06 23:26 
GeneralMultiple assemblies and cross referencing? [modified] Pin
Marc Clifton31-Jul-06 4:18
mvaMarc Clifton31-Jul-06 4:18 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.