SandCastle Builder

August 7, 2006

[Update #3] – 11 August 0900

Version 1.2 

Apparently (can’t isolate the issue exactly) it works for some people and not for others.

– Logs the commands it executes (so you can see if there are any issues with paths, etc)

– Cleaned up some of the UI elements

[UPDATE # 2] – 9 Aug

Version 1.1

Well, as one is wont to accidentally do, I packaged the debug build rather than the release …. hence the snafu.

I believe SandCastle Builder is working now.

[UPDATE # 1] – 9 Aug

Version 1.1

– Fixed issue of incorrect extension when chosing your own CHM

– Added feature to allow specification of custom footer


Yep. Another one.

Joining the bandwagon of individuals keen to build a GUI for Sandcastle is yours truly.

Here are screen shots of Builder




Builder In Action


Builder At Rest

What makes mine different?

  • It is “Project” based so you don’t have to keep specifying the assembly, xml file, etc
  • Does not assume SandCastle or the Help Compiler is installed to the default location. It does however assume they are installed somewhere!
  • Reasonably polished UI – don’t you think?😉
  • All in C# – no batch files (except for a workaround to piping output from one process to another)
  • Does all its work in the temp folder and cleans up after itself
  • Allows you to immediately view the CHM

Do I have any other plans?


  • Fix the inevitable bugs that MUST be hiding somewhere
  • Capture output from SandCastle’s various executables and log to file
  • Convert builder to a Visual Studio Addin
  • Allow builder to directly build projects & solutions
  • Allow builder to run from console so it can be used by built tools like nant and msbuild

Have a go and let me know what you think by leaving a comment. What i’m keen to know is if it runs at all:)

Download SandCastle Builder Here

Download the Manual Here

kick it on DotNetKicks.com

35 Responses to “SandCastle Builder”

  1. […] for all this stuff would be great to see. Share this post: Email it! | bookmark it! | digg it! | reddit! Posted: Wednesday, August 09, 2006 10:35 AM by astopford Filed under: .NET, Build Systems,Sandcastle […]

  2. greg kats Says:

    I tried it and it says it worked successfully, but no chm file was generated. Is there a log or something I can check to see what has happened.

    I see files created in the temp directory. But no html files and no chm.


  3. Tomi B. Says:

    What version of HTML Help Workshop are you using? For me if the builder starts hhw.exe and it is not already running, I don’t see the Help Workshop GUI and it never returns (ie. the builder gets stuck on “Generating CHM”). Even then the CHM file path is “%TEMP%\tmpxxx.tmp\Test.chm” but not compiled automatically.

  4. Hmm … I’ve not come across such a problem. Have you been able to generate any CHM files manually?

    I’m using version 4.748702, which generates HTML Help 1 files.

    I’m working on getting it to HTML help 2 as well.

  5. Corrado Cavalli Says:

    I’ve installed your tool and tried to generate a chm from a xml commented assembly.
    Everything seems ok (no error messages) but chm is not generated, is there any log to inspect?
    I’m using version 4.74.48702 of help compiler.

    Here’s what appears on listbox:

    Started 9:31:49
    Checking Sandcastle location … OK
    Checking Help Compiler location … OK
    Checking the assembly DLL … OK
    Checking the output location … OK
    Executing MRefBuilder … OK
    Generating Content … OK
    Generating Manifest … OK
    Executing Build Assembler … OK
    Generating HTML Content … OK
    Completed 9:31:52

  6. Hi Corrado

    Just check in the folder where you installed the Builder if there is a sandcastle.config file. I suspect you’re running an older version

  7. Corrado Cavalli Says:

    Yes i have a SandCastle.config file in the builder folder, I presume having latest release because I’ve downloaded from this site yesterday…

  8. Hi Corrado.

    Do this – check back in a couple of hours. I’m adding a facility to capture the output from the various SandCastle executables to log file to help in troubleshooting and I’m removing the command windows it spawns.

  9. Corrado Cavalli Says:

    Ok, I’ll test new version and I’ll let you know.
    Thanks for your help, tool looks great!

  10. Corrado Cavalli Says:

    Hello, downloaded new version, nothing chaged…
    Where is log file saved?

  11. Sorry, wasn’t able to update it last night but I have now. After the tool runs it opens a test file of the commands it executed. That should be able to tell you if the correct commands are being run.

  12. Corrado Cavalli Says:

    Downloaded new version, but after a successful build i see no test file opening😦 where is it saved?

  13. Text file i meant …

    It should be copied to the same directory where the CHM is generated. Or rather supposed to be.

    Out of curiosity, what operating system do you use? And do you have Norton Security or some security tool of the kind that stops batch files from running?

  14. Corrado Cavalli Says:

    Unfortunately no error, no chm and no Text file on chm folder.
    I’m using XP Sp2 and no security tool active, I am also machine Admin (I shouldn’t but i like easy life… :))
    Also tried reinstalling Sancastle CTP, no luck😦


  15. Version 1.2 writes out the paths & executables its using to the console on the main form. Can you check those and see if they are ok?

    [Framework Folder] OK
    [Sandcastle Folder] OK
    [Help Compiler exe] OK
    [Output CHM] OK

    BY THE WAY — is your windows the English version? I have yet to localize it properly

  16. Matthew Becker Says:

    I am also not getting a CHM file generated.

    Started 12:50:59 PM
    Checking Sandcastle location … OK: C:\Program Files\Sandcastle
    Checking Help Compiler location … OK: C:\Program Files\HTML Help Workshop\hhc.exe
    Checking the assembly DLL … OK: U:\VSS\DSData\DSData.Common\bin\DSData.Common.dll
    Checking the output location … OK: U:\VSS\DSData\DSData.Common\bin\DSData.Common.chm
    Executing MRefBuilder … OK
    Generating Content … OK
    Generating Manifest … OK
    Completed 12:51:02 PM

  17. Tomi B. Says:

    Version 1.2 fixes the “hhc.exe” getting stuck problem I reported earlier. Could you make opening the log after the build optional? Also, it would be nice to be able to resize the window.

  18. Corrado Cavalli Says:

    Here’s the output
    Started 21:03:55
    Checking Sandcastle location … OK: C:\Program Files\SandCastle
    Checking Help Compiler location … OK: C:\Program Files\HTML Help Workshop\hhc.exe
    Checking the assembly DLL … OK: C:\Pozzo\VS2005\LocalizerEngine\LocalizerEngine\bin\Debug\LocalizerEngine.dll
    Checking the output location … OK: C:\Pozzo\VS2005\LocalizerEngine\LocalizerEngine\bin\Debug\LocalizerEngine.chm
    Executing MRefBuilder … OK
    Generating Content … OK
    Generating Manifest … OK
    Executing Build Assembler … OK
    Generating HTML Content … OK
    Generating CHM … OK
    Completed 21:04:21

    I’m using XP Sp2 English version.

  19. Eric G Says:

    I’m having the same problem… I can run the tool, and it says everything is OK, but I get no output.
    I’m running as administrator on Windows XP SP2 with the Sandcastle CTP and HTML Help Workshop 4.74.8702.

    Thanks for putting this together! I hope you can get it working. Any thoughts about releasing the source?

    Started 6:23:49 PM
    Checking Sandcastle location … OK: C:\Program Files\SandCastle
    Checking Help Compiler location … OK: C:\Program Files\HTML Help Workshop\hhc.exe
    Checking the assembly DLL … OK: C:\Documents and Settings\Eric\Desktop\OIVL\SensorService\OIVLSensors\bin\Release\OIVLSensors.exe
    Checking the output location … OK: C:\Documents and Settings\Eric\Desktop\OIVL\SensorService\OIVLSensors\bin\Release\OIVLSensors.chm
    Executing MRefBuilder … OK
    Generating Content … OK
    Generating Manifest … OK
    Executing Build Assembler … OK
    Generating HTML Content … OK
    Generating CHM … OK
    Completed 6:24:19 PM

  20. Alex Says:


    same problem here, no output.
    Is the source available? I would really like to help out finding the problem.


  21. Rafa Says:


    I have the same problem. Is there source code available?


  22. 黑兔 Says:


    Same for me.
    Everything’s “OK”, but no output…

  23. Hi 黑兔,

    I’ve put up the source code for builder so you can run through it and see if you can identify the problem. Unfortunately I’ve not been able to isolate why it doesn’t work for some😦

    Good luck!

  24. Alex Says:

    Thank you for uploading the source. Was pretty easy to locate the problem with the source.
    The HTML help compiler could not be startet on my system because the path to it contains space characters. Its the same with the argument for the help compiler. Surround the command and argument in commas and it works

    i changed line 328-330 and it works great now:

    exe = @”””” + HelpCompilerLocation + @””””;
    arguments = string.Format(@”””{0}\test.hhp”””,


  25. Matthias Says:

    I don’t have the source. Is it possibl to become a new version which works?



  26. Du Says:

    I know it has being one month since the last entry.

    Do you have a new version that works. I would love to help find the problem and help you put a new version that works.

    Let me know if I can help.



  27. Matthias Says:

    I have version 1.2. I take it today but it dosen’t work.



  28. Sascha Nitschke Says:

    Hello Matthias,

    after I have started SandCastle Builder 1.2 I just could choose DLL but no EXE files. Why?


  29. MikeN Says:

    You do realise that leaving it a “not working” state will just cause people not to use this tool…

    Any chance that we’ll get an update? Or maybe a corrected code posted?

  30. kumar Says:

    I can run the tool, and it says everything is OK, but .chm file is not generated in the location.

    Anyone who solve this issue..may help me..

    thanks in advance

  31. kumar Says:


    I think you solve the issue.. can you help me to solve the issue..it’s very urgent..thanks for understanding

  32. and they also said, that we couldn’t last togethe. Serafino Raimondo.

  33. Horsa Amadeo Says:

    please tell me why, i’m feeling . Horsa Amadeo.

  34. Martin Says:

    This is rediculus. Alex has posted the solution for the bug and you don’t even bother to implement it. Gonna try another Sandcastle UI…

  35. Abodoulu Says:

    picture big bird sesame street,

Leave a Reply

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

WordPress.com Logo

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

Twitter picture

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

Facebook photo

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

Google+ photo

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

Connecting to %s


Get every new post delivered to your Inbox.

%d bloggers like this: