Freigeben über

A few faqs about Sandcastle

  • Artikel

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 https://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 https://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" />
</index>

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!

Anand..

Comments

  • Anonymous
    July 30, 2006
    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. :)

    Mikael

  • Anonymous
    July 30, 2006
    Here is my GUI for SandCastle :

    ftp://ftp-developpez.com/kikos31/SandCastle/SandCastleGui.zip

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

  • Anonymous
    July 30, 2006
    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.

    Anand..

  • Anonymous
    July 30, 2006
    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=2.0.0.0, 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?
    Thanks,
    Kent Boogaart

  • Anonymous
    July 30, 2006
    Kent,
    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.

    Anand..

  • Anonymous
    July 30, 2006
    It was due to arrive, and it finally has. Microsoft have released the first CTP of Sandcastle this weekend....

  • Anonymous
    July 30, 2006
    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

    Thanks,
    Szymon

  • Anonymous
    July 30, 2006
    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:

    http://ixnay2infinity.blogspot.com/2006/07/improved-sandcastle-bat-script.html

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

  • Anonymous
    July 31, 2006
    Hi,

    I've updated my GUI.

    ftp://ftp-developpez.com/kikos31/SandCastle/SandCastleGui0.1.zip

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

    Regards

  • Anonymous
    July 31, 2006
    GUI to customise BAT script:
    http://ixnay2infinity.blogspot.com/2006/07/sandcastle-bat-script-configuration.html

    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.

  • Anonymous
    July 31, 2006
    Hi,

    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:

    http://blog.ljusberg.com/2006/07/msbuild-script-for-sandcastle.html

    Regards,

    /Anders

  • Anonymous
    July 31, 2006
    This is really good.

  • Anonymous
    July 31, 2006
    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!

  • Anonymous
    July 31, 2006
    Hi,

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

    http://www.dotnetjunkies.com/WebLog/mikaels/archive/2006/07/31/143020.aspx

  • Anonymous
    July 31, 2006
    Techcommdood,
    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.

    Anand..

  • Anonymous
    August 01, 2006
    The SandCastle Helper now supports localization in both the GUI and the documentation. :-)

    http://www.dotnetjunkies.com/WebLog/mikaels/archive/2006/08/01/143106.aspx

  • Anonymous
    August 01, 2006
    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?

  • Anonymous
    August 01, 2006
    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!

  • Anonymous
    August 01, 2006
    Bill,

    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:

    http://blog.ljusberg.com/2006/07/msbuild-script-for-sandcastle.html

    /Anders

  • Anonymous
    August 01, 2006
    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?

  • Anonymous
    August 02, 2006
    My GUI/BAT script solution is updated to support multiple assemblies/xml-comments files:

    http://ixnay2infinity.blogspot.com/2006/07/sandcastle-bat-script-configuration.html

  • Anonymous
    August 02, 2006
    Hi

    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?

    Thanks,

    Paul

  • Anonymous
    August 03, 2006
    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:

    http://blog.ljusberg.com/2006/08/sandcastle-visual-studio-project.html

    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:

    http://blog.ljusberg.com/2006/07/msbuild-script-for-sandcastle.html

    /Anders

  • Anonymous
    August 03, 2006
    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.

  • Anonymous
    August 03, 2006
    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).

    http://www.dotnetjunkies.com/WebLog/mikaels/archive/2006/08/03/143253.aspx

  • Anonymous
    August 04, 2006
    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!

    Video:
    http://www.overnight.nl/download/sandcastleaddin.html

    Post with rest of the links:
    http://dotnetpret.blogspot.com/2006/08/sandcastle-continued-documentation.html

    Cheers,

    Frank Kroondijk
    fh_kro<NO-SPAM>ondijk@yahoo.com

  • Anonymous
    August 04, 2006
    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:

    http://blog.ljusberg.com/2006/08/sandcastle-under-hood-part-1.html

    http://blog.ljusberg.com/2006/08/sandcastle-under-hood-part-2.html

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

    /Anders

  • Anonymous
    August 05, 2006
    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.

  • Anonymous
    August 07, 2006
    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.

  • Anonymous
    August 07, 2006
    Mike,
    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.

    Anand..

  • Anonymous
    August 08, 2006
    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.

  • Anonymous
    August 10, 2006
    The comment has been removed

  • Anonymous
    August 20, 2006
    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.

  • Anonymous
    August 20, 2006
    Jan,
    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.

    Anand..

  • Anonymous
    August 21, 2006
    Thanks for the answers. I'll keep an eye out the next CTP.

  • Anonymous
    October 09, 2006
    It was due to arrive, and it finally has. Microsoft have released the first CTP of Sandcastle this weekend.

  • Anonymous
    December 06, 2007
    Hi, 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?? Thanks

  • Anonymous
    July 24, 2008
    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.

  • Anonymous
    August 14, 2008
    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?

  • Anonymous
    November 17, 2008
    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 {  get  {    return Support.TwipsPerPixelY();  } [generated documentation] Name Description TwipsPerPixelY  - empty description - Any Ideas?