A few faqs about Sandcastle

I’m super excited about the response to the Sandcastle CTP launch.  Much of the response has been positive, and folks have asked some great questions.  Let me try to address a few of the common questions people have about the site:

Where can post Sandcastle related questions?
Please post all Sandcastle related questions and discussions at http://forums.microsoft.com/MSDN/ShowForum.aspx?ForumID=66&SiteID=1. Please use Sandcastle: at the beginning of your questions when posting questions at this forum. You can also send feeback and bugs to sandchlp@microsoft.com.

Is Sandcastle used by Microsoft for their API documentation?
Yes. This CTP version has a new architecture and has reduced the .Net Framework build time from 10 plus hours during VS 2005 ship cycle to 30 minutes. For the current CTP release the focus was on scalability and performance.

When can we get better documentation?
Scott Hanselman’s provides his honest opinion about this CTP release documentation here
. Better documentation with architectural overview is on it’s way and I will post them shortly.

Will there be an SDK for Sandcastle? 
Most likely; Sandcastle will be a part of VS SDK release. For the current CTP release the focus was on scalability and performance.

Will Sandcastle have a GUI and viewer?
Not for Version 1.0. Several customer written GUIs are available at http://www.sandcastledocs.com.

Will there be another CTP release?
Yes; We plan to few CTP releases before Sandcastle 1.0 RTW.

How can change author comments from comments.xml to a different file name?
Please look at the following section in sandcastle.config file:

<!– Copy in comments –>
<component type=”Microsoft.Ddue.Tools.CopyFromIndexComponent” assembly=”..\..\ProductionTools\BuildComponents\BuildComponents.dll”>
         <index name=”comments” value=”/doc/members/member” key=”@name” cache=”100″>
           <data files=”comments.xml” />
           <data files=”C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\*.xml” />

The comments.xml in sandcastle.config file can be replaced with any other file name such as foo.xml or multiple xml files with *.xml.

How can I use MrefBuilder with /dep option?
The dependencies can be at a separate folder called dependency.
MrefBuilder can be invoked with the /dep switch as below:

MRefBuilder foo.dll /out:reflection.org /dep:dependency\*.dll

MrefBuilder also takes wildcards like the following:

MRefBuilder dll\*.dll /out:reflection.org /dep:dependency\*.dll

That is, if I put all the assemblies I want to reflect over in a directory named dll and tell it to get them from there.

Is it possible to include private members in the output from Sandcastle? If not will this be added as an option on a later CTP?
It’s not possible to document private members using the July CTP version of Sandcastle. However we plan to add couple switches to the syntax invocation for MRefBuilder is as follows:

MRefBuilder.exe dll /dep:dep /out:out /internal- 

The Boolean /internal option enables documentation of private APIs to be produced for the internal consumption of development teams.

Does Sandcastle resolve reference to GAC DLLs?
We do not resolve references to GAC. You have to use the /dep switch and refernce those dependent assemblies. Resolving refence to GAC is a feature request that we did not get to in this CTP release.

Can the build steps be automated?
Yes. We will be releasing automated scrips in our future releases. Mikael Söderström has a “Sandcastle Helper” here,
Ashley van Gerven has a batch script availabe here and Scott Hanselman’s has power shell script availabe here.


That’s all for now…more coming soon.  I’m trying to read as many blog posts and comments as possible to collect feedback and questions about the site, but if you have particular questions you’d like to make sure I address, please post them here!


Comments (42)

  1. Vimpyboy says:

    Hi Anand,

    Thanks for linking to me.

    I´m working on an updated version av the SandCastle Helper for the moment where you will be able to change all the settings in a win application. 🙂


  2. KIKOS31 says:

    Here is my GUI for SandCastle :


    This is the first version, I will update soon. Please send me comments.

  3. Garry Trinder says:

    Mikael and Kikos,

    Thanks a bunch for your efforts. This is great to see.

    Since Mrefbuilder can use /dep switch, as I have explained above in the FAQ, the GUI can also have a path for dependency.

    Thanks again.


  4. kentcb says:

    Hi Anand,

    Can you add a FAQ about how to resolve references to GAC DLLs. I tried to document my DLL which references System.Configuration.dll and I get:

    Error: Unresolved assembly reference: System.Configuration (System.Configuration, Version=, Culture=neutral, PublicKeyToken

    =b03f5f7f11d50a3a) required by MyAssembly

    Also, I set the reference to copy local just to try out Sandcastle. However, I then managed to crash it:

    Info: Loaded 1 assemblies for reflection

    Unhandled Exception: System.NullReferenceException: Object reference not set to an instance of an object.

      at Microsoft.Ddue.Tools.Reflection.DocStudioNamer.WriteType(TypeNode type, TextWriter writer)

      at Microsoft.Ddue.Tools.Reflection.DocStudioNamer.GetTypeName(TypeNode type)

      at Microsoft.Ddue.Tools.ManagedReflectionWriter.WriteStartTypeReference(TypeNode type)

      at Microsoft.Ddue.Tools.ManagedReflectionWriter.WriteParameter(Parameter parameter)

      at Microsoft.Ddue.Tools.ManagedReflectionWriter.WriteParameters(ParameterList parameters)

      at Microsoft.Ddue.Tools.ManagedReflectionWriter.WriteMember(Member member, TypeNode type)

      at Microsoft.Ddue.Tools.ManagedReflectionWriter.VisitMember(Member member)

      at Microsoft.Ddue.Tools.Reflection.ApiVisitor.VisitMembers(MemberList members)

      at Microsoft.Ddue.Tools.ManagedReflectionWriter.VisitType(TypeNode type)

      at Microsoft.Ddue.Tools.Reflection.ApiVisitor.VisitTypes(TypeNodeList types)

      at Microsoft.Ddue.Tools.ManagedReflectionWriter.VisitNamespace(Namespace space)

      at Microsoft.Ddue.Tools.Reflection.ApiVisitor.VisitNamespaces(NamespaceList spaces)

      at Microsoft.Ddue.Tools.ManagedReflectionWriter.VisitNamespaces(NamespaceList spaces)

      at Microsoft.Ddue.Tools.Reflection.ApiVisitor.VisitApis()

      at Microsoft.Ddue.Tools.MRefBuilder.Main(String[] args)

    Any thoughts?


    Kent Boogaart

  5. Garry Trinder says:


    We do not resolve references to GAC. You have to use the /dep switch and refernce those dependent assemblies.

    Resolving refence to GAC is a feature request that we did not get to in this CTP release.


  6. It was due to arrive, and it finally has. Microsoft have released the first CTP of Sandcastle this weekend….

  7. kobush says:

    Hi Anand,

    I’ve managed to get past the MRefBuilder but got stuck on BuildAssembler. Actually it crushed after runing for a while. Please take a look for details on my blog: http://geekswithblogs.net/kobush/archive/2006/07/30/86656.aspx



  8. Ashley van Gerven says:

    I’ve improved my BAT script – it can run from any directory. Set DLL, XML, and CHM path in the BAT (lines 3, 4, 18). Improved the readme as well:


  9. dm.CaT says:

    As I know, win32 c++ project in VS2005 can produce xml comments files also. Will Sandcastle processed produced xml-comments files from such projects?

  10. KIKOS31 says:


    I’ve updated my GUI.


    Now, you can use dependency and customize the HTML Help WORKSHOP Path.


  11. Ashley van Gerven says:

    GUI to customise BAT script:


    Once you have the BAT script for your assembly you can run it repeatedly without needing any GUI, having to set paths etc.

    Set Assembly, XML, CHM paths. Checkbox to leave output folder so you can work with Help project (e.g. fixing the default page so you don’t start of with a ! icon). Sandcastle and HTML help install paths can be configured manually in template.xml.

  12. andlju says:


    I’ve created a MSBuild script that can be used to automate the process of building help files with Sandcastle. Feel free to check it out at:




  13. pritam says:

    This is really good.

  14. techcommdood says:

    Hi. A couple of questions that are apparently not frequently asked for ya. 😉

    Is Sandcastle capable of producing fully-localized documentation in both single and double byte languages?

    How customizable is it with regard to changing the look of the output?

    I was going to ask about automation but I see that was just commented on. Thanks Anders!

  15. Vimpyboy says:


    I have updated the SandCastle Helper with a GUI and some bug fixes now.


  16. Garry Trinder says:


    Yes I will add a FAQ about Sancastle support for localized documentation.

    We plan to use Sandcastle to ship .Net Frameowork in English and International languages. We have not tested Sandcastle yet for single and double byte languages.

    Bue yes we will support this scenario if it’s not already supported in this CTP release.

    The output is controlled by a set of XSLTs and scripts in C:Program FilesSandcastlePresentation folder and it’s completely customizable. I will do a future blog about this.


  17. Vimpyboy says:

    The SandCastle Helper now supports localization in both the GUI and the documentation. 🙂


  18. dm.CaT says:

    Anand, please answer this question:

    "Monday, July 31, 2006 8:12 AM by dm.CaT

    As I know, win32 c++ project in VS2005 can produce xml comments files also. Will Sandcastle processed produced xml-comments files from such projects?"

    I try to generate chm file and got nothing. 🙁 I want to know, will Sandcastle support non-.Net laguages? Or I have to look for other tools?

  19. Bill Menees says:

    I really appreciate all the people who’ve created automated wrappers for Sandcastle, but so far everyone seems to only be generating docs for a single assembly.  

    Can one of the generator GUI authors please update their utility to support multiple assemblies and XML files?  For my product I have over 20 DLLs and XML files, and I’d like to generate the docs for all of them all into one big HTML Help file.

    Or at least I think I would.  If there’s a better way, please let me know.  Thanks!

  20. andlju says:


    My MSBuild script, while not (yet) a GUI, can handle multiple assemblies and xml files. It’s quite easy to work with, you’ll find it together with a sample project at:



  21. ssj4finalflash says:

    Is it possible to include private members in the output from Sandcastle? If not will this be added as an option on a later CTP?

  22. Ashley van Gerven says:

    My GUI/BAT script solution is updated to support multiple assemblies/xml-comments files:


  23. Paul R says:


    I’m generating a single chm file from multiple assemblies using Anders’ MSBuild script and I have a couple of questions.

    1. Our unit tests are included in the assembly files (in separate namespaces) and so they end up appearing in the chm file. Is it possible to exclude namespaces when the assembly files are reflected over (preferably with wildcard syntax e.g. *.Tests)?

    2. I get a number of warnings of the following form….

    ResolveReferenceLinksComponent: Unknown reference target ‘T:System.Collections.Generic.Dictionary{`0,`1}.KeyCollection’.

    How should I go about fixing these?



  24. andlju says:

    I’ve just released an initial version of a Visual Studio plugin for Sandcastle. It installs a new kind of Project that keeps the configuration for your Sandcastle build and can build the documentation like any other project. Still in a very early stage, but if you’re brave, download it from:


    Actually, even if you’re not brave, you can always look at the screenshots..

    Oh, and I’ve updated the build script too. It should now work better even if you give more complex paths to your assemblies/xml files:



  25. dwhearn says:

    I have tried it on a 32-bit processor and Sandcastle works great. But it appears that Sandcastle has been compiled for ‘Any CPU’ instead of ‘x86’. Since it uses COM objects, it will not run on a 64-bit processor.

  26. Vimpyboy says:

    SandCastle Helper now supports multiple files!

    You can also get your documentation in your own language (for the moment it supports english, swedish, german and dutch).


  27. frankkroondijk says:

    Visual Studio 2005 Sandcastle Add-In

    For the ones having troubles with the scripts, here a super easy add-in, with source code.

    Having troubles getting it started?, let me know!



    Post with rest of the links:



    Frank Kroondijk


  28. andlju says:

    If you’re interested in knowing a bit more of the inner workings of Sandcastle, but don’t have the time to figure it out for yourself, come have a look:



    I’m working on part three, let me know if there is something specific you’d like me to include!


  29. Garry Trinder says:

    Is it possible to include private members in the output from Sandcastle? If not will this be added as an option on a later CTP?

    Not in this version. However we plan to add couple switched to the invocation syntax for MRefBuilder is as follows:

    MRefBuilder.exe dll /dep:dep /out:out /namespaces- /internal-

    The Boolean /namespaces option enables the componentized build scenario. In that scenario, MRefBuilder would be run with /namespaces- on each assembly. The resulting reflection data would be used to generate separate HxS documentation, without namespace topics, for each assembly. Then a separate tool would be run over all the assembly reflection data files together to produce a namespace reflection data file, listing all the namespaces and their corresponding members in all assemblies. This namespace reflection data file would then be used as input to generate one more CHM/HxS containing only namespace topics.

    The Boolean /internal option enables documentation of private APIs to be produced for the internal consumption of development teams.

  30. Mike44 says:

    I have been experimenting with Sandcastle and there are couple of issues I have noticed that I would appreciate some advice on: 1) If my C# code has a protected member in it, the generated help seems to treats it as a public member. It does not show the correct icon and if you untick the public checkbox, it does not show the protected member anymore. 2) The columns generated in the help do not seem to be resizable and when you have long namespace or method names, you cannot see the last few characters of the name.

    Maybe I am using it incorrectly, but I would appreciate it if these issues I have found can be confirmed by someone else.

  31. Garry Trinder says:


    Could you send me screen shots of these two issues. I will be happy to take a look at them and provide details.

    My email is aramATmicrosoftDOTcom.


  32. Mike44 says:

    Will Sandcastle automatically generate the context sensitive help for use in Visual Studio 2005 when you press the F1 help key for c# methods and properties etc, or does the c# source have to been changed in some way to support this. I have generated help from my source code using Sandcastle and used the help integration wizard to make it available in Visual Studio 2005, but I get no context-sensitive help.

    If this is not available in Sandcastle, I would appreciate any help on how to get the context-sensitive help to work for my c# code in Visual Studio 2005.

  33. KarloX2 says:

    About the planned visibility switches: I read that support of boolean options like  /internal+- is planned for the next release.

    Please also consider a switch to include or exclude

    1. explicit interface implementation method

    2. protected members

    2. internal protected members



  34. Jan Schreuder says:

    I’ve been using the current CTP for some weeks now, and so far I’m quite happy. I was wondering if you could give us more information on the upcoming CTP. Like what will be in it and when it will be available.

  35. Garry Trinder says:


    Thanks for blogging about Sandcastle and for using our CTP version. We are currently testing the August CTP release. I expect to release this version by the end of next week. This CTP will address the following:

    1. Firefox support for HTMs generated by Sandcastle.

    2. Sandcastle’s issue with multi-dimensional arrays has hit a lot of people. We have addressed this issue.

    3. Links to MSDN topics supported.

    4. We addressed several other bugs in our first CTP.

    I will post a detailed blog this week about "what’s new" in our next CTP release.


  36. Jan Schreuder says:

    Thanks for the answers. I’ll keep an eye out the next CTP.

  37. It was due to arrive, and it finally has. Microsoft have released the first CTP of Sandcastle this weekend.

  38. abhi243 says:


    i am able to create the chm for my assembles, but i want to merge them into one chm….

    so is there is any way to include 4 to 5 dll to generate the chm… and how to create the xml for it??


  39. torres says:

    I am new to Sandcastle and I need to hide all the fields in all my classes so that they don’t appear in the .chm.  How can I do that in the MRefBuilder.config file?  Thank you.

    For example, I have this class:

    public sealed class ChargeRqmntDA


    /// <summary>

    /// An object of type Database.

    /// </summary>

    private Database db;




    and so on.  I don’t want to see the db field in the .chm file.

  40. melissa_1202 says:

    Is it possible to hide protected members from .chm file? Sandcastle Help File Builder can remove the protected members by modify reflection.org, how about Sandcastle? Is there a switch to do this?

  41. cebastos says:

    hi, I’m new using this tool. I’m getting a problem generating description information in .chm files. how should I tag the code to generate this information? thanks

    [source code]

    /// <summary>

    /// Gets a value that is used to convert twips to pixels based on screen settings.

    /// <returns>The conversion factor.</returns>

    /// </summary>

    public float TwipsPerPixelY




       return Support.TwipsPerPixelY();


    [generated documentation]

    Name Description

    TwipsPerPixelY  – empty description –

    Any Ideas?