Click here to Skip to main content
14,733,617 members
Articles » Platforms, Frameworks & Libraries » .NET Framework » General
Posted 4 Nov 2008


34 bookmarked

Getting Started with Sandcastle

Rate me:
Please Sign up or sign in to vote.
3.29/5 (7 votes)
4 Nov 2008CPOL
Install and build your first Sandcastle Help Document easily


This article will take you through the steps from installing Sandcastle to generating your first Sandcastle Help Document. It is assumed you already know how to generate XML comments within Visual Studio and what Sandcastle is.


Documentation is always something that some programmers like to cry and moan about (well at least I do). When someone asks me how I did something I say 'I dunno, and who cares? It does what it's supposed to do!'. Well documentation insists we have an answer to this question.  Visual Studio makes documenting easy as WELL as useful! Pressing (/) three times allows you to create XML comments for entering function data. This is not only useful for intellisense, but documentation as well.

Sandcastle is a program that turns the 'would be' painful documentation process into a few clicks of the mouse button (aside from adding XML comments). Currently there is no formal documentation for getting up and running with Sandcastle. So to save you the headache of searching the I-net like I had to do, I've created this tutorial.


To get started, you will need the following:

Building Your Help Documentation

Visual Studio Setup

Before you can build your documentation, you have to ensure to build your XML documentation file. The file is useless on its own; however, Sandcastle requires it in order to build the help doc.

In Visual Studio 2005, go to Project -> Properties and select the Build tab and ensure the XML documentation checkbox at the bottom under Output is checked:

Image 1

It is important to note that the XML file should be in the format 'mylibraryname'.xml! In this example the library name is 'Sample'. You can now build the project and you are ready to export as a Sandcastle Help Document.

Sandcastle Help File Builder

  • Open the Sandcastle Help File Builder (SHFB) from your Start -> Program Files.
  • Within the Sandcastle Help File Builder, select Project -> New Project from Visual Studio Project... and open the *.sln from which you built your XML Documentation in the previous step (Visual Studio Setup).
  • Define the Help file Format within the HelpFileFormat Property in the Project Properties Window within SHFB. (Select Help1xAndWebsite because the website looks best IMO).
  • Define the OutputPath Property. (Project Properties Window)
  • Select Documentation -> Build Project

That is it, you are finished. You can load the *.chm file via the HTML Help Workshop program you've installed or, if you've exported as a website, you can open the index.html file. Both of these files are located in the directory you specified in the OutputPath property of the SHFB.

I Suggest You Also Read


  • 4th November, 2008: Initial post


This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)


About the Author

Canada Canada
No Biography provided

Comments and Discussions

Generalok article Pin
Donsw7-Feb-09 14:19
MemberDonsw7-Feb-09 14:19 
GeneralRe: ok article Pin
stodgey9-Feb-09 6:24
Memberstodgey9-Feb-09 6:24 
GeneralRe: ok article Pin
Donsw9-Feb-09 11:12
MemberDonsw9-Feb-09 11:12 
GeneralRe: ok article Pin
stodgey9-Feb-09 11:18
Memberstodgey9-Feb-09 11:18 
Generalxml Doc output in Express versions Pin
Kent K11-Nov-08 12:54
professionalKent K11-Nov-08 12:54 
FYI, I'm pretty sure this isn't possible in the Express versions as when I first used Sandcastle in the past I ran up against this.
GeneralFilename for XML file Pin
Roland Bär5-Nov-08 5:08
MemberRoland Bär5-Nov-08 5:08 
GeneralRe: Filename for XML file Pin
stodgey5-Nov-08 7:21
Memberstodgey5-Nov-08 7:21 
GeneralProblems with instruction Pin
3sL4-Nov-08 23:10
Member3sL4-Nov-08 23:10 
GeneralRe: Problems with instruction Pin
stodgey5-Nov-08 7:20
Memberstodgey5-Nov-08 7:20 
GeneralEnhancing the documentation experience [modified] Pin
Thomas Weller4-Nov-08 22:58
MemberThomas Weller4-Nov-08 22:58 
GeneralRe: Enhancing the documentation experience Pin
Dmitri Nеstеruk5-Nov-08 1:48
MemberDmitri Nеstеruk5-Nov-08 1:48 
GeneralRe: Enhancing the documentation experience Pin
Thomas Weller5-Nov-08 2:17
MemberThomas Weller5-Nov-08 2:17 
GeneralRe: Enhancing the documentation experience Pin
stodgey5-Nov-08 9:23
Memberstodgey5-Nov-08 9:23 
General"this is best IMO" Pin
agorby4-Nov-08 21:22
Memberagorby4-Nov-08 21:22 
JokeRe: "this is best IMO" Pin
geo_m4-Nov-08 22:36
Membergeo_m4-Nov-08 22:36 

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.