The new release uses the Sandcastle Guided Installer to install the Sandcastle tools and some extras such as the Sandcastle MAML Guide. Once downloaded, extract the files to a location of your choice and run SandcastleInstaller.exe.

Installation Issues

IMPORTANT: The new release uses a brand new MSI installer. As such, you must manually remove the old Sandcastle release using the Add/Remove Programs or Programs and Updates option in the Control Panel. In addition, you should check for and remove the old Sandcastle folder (i.e. C:\Program Files (x86)\Sandcastle) if it still exists after removal to delete any old patch files that could interfere with the new release.

VS2010 Presentation Style

Thanks to Don Fehr for creating a brand new VS 2010 style for Sandcastle. The first version is included in this release. The following are the known issues at this time:
  • The VS2010 presentation style is most definitely in beta state. The primary goal for now is to have real-world users try it out and see what issues are discovered.
  • Custom branding package support is not yet implemented. This will be supported in a future release once it becomes clear how it will be affected by Help Viewer 2.0.
  • In Help 1 (CHM format) builds, the language filter is not sticky.
  • The table of contents and frame style for website output will use the style supplied by the build tool and not the MSDN Lite table of contents style.
  • Help Viewer 2.0 in the Windows 8 Preview and used by Visual Studio 2011 does not support the new VS2010 style. It does support the self-branded VS2005 style. If producing help content for Windows 8 or Visual Studio 2011, use the older VS2005 style for the time being. This will be addressed in a future release.

General Changes

Rearranged the source project folders to match the installed folder layout. This makes testing a development build much easier as you can point DXROOT at the .\Sandcastle\Main folder and have it work like a release build.

Created separate solutions for each tool so that they can be loaded, built, and tested individually. Reflector was used to get the source code for the tools that were missing source code and projects were added for them too.

All tools are now built using .NET 4.0. This will allow taking advantage of newer features in the runtime added since .NET 2.0. This does not change the ability to run the tools against assemblies built with prior framework versions. That is still supported.

Removed all GlobalSuppressions.cs files from all projects. Many of us don't have a version of Visual Studio that supports code analysis within the IDE. Instead, individual FxCop projects have been created for each project. Some clean up has been performed based on the initial scans. Warnings still exist in several projects and have been left for review until later.

Signed all assemblies with a new key file and standardized the assembly attributes.

Added Data\BuildReflectionData.bat and Data\BuildReflectionData.proj to properly rebuild the reflection data files.

Updated the XSL stylesheet version number to 2.0 in all XSL transformations. A bug in .NET 4.0 prevents the <xsl:sort> function from working when using XSL version 1.1.

Merged the Sandcastle Guided Installer, the Language Pack, Sandcastle MAML Guide, Web Code Providers, and the HTML to MAML Converter projects from Sandcastle Styles into the Sandcastle project. These are located under the .\Extras folder.

The Sandcastle Guided Installer has been rewritten as a WPF application. It uses flow documents rather than HTML resources for the pages which are much easier to extend and work with in the code.

Created a new setup project to install Sandcastle. This version includes the content from the .\Extras folder as additional installable options. This installer also gives Sandcastle a presence on the Program Files menu with links to the included help files, the project web site, and the example GUI. The setup project is located in the .\Extras folder too as it isn't part of the core Sandcastle code and uses the Wix tools.


Added a new optional attribute to the reflection data schema for parameter elements. This is needed to properly document optional parameters that use OptionalAttribute and have no default specified using assignment.

Updated the MAML schemas to include all of the new elements and attributes added by the Sandcastle Styles patch and adjusted a few elements to reflect how Sandcastle uses them. This allows for proper validation of MAML topics in Visual Studio.


Reworked the command line option classes to fix various FxCop warnings and to correctly implement support for required options.


Moved the content of the CCI\ and Reflection\ folders into the MRefBuilder project and made them members of the project so that they are compiled directly into MRefBuilder.exe to match prior releases of Sandcastle.

Fixed ExtensionMethodAddIn.cs so that it doesn't add extension methods to enumerations and static classes.

Fixed ExtensionMethodAddIn.cs so that it ignores unexposed namespaces and types. This prevents it from scanning unnecessary namespaces and types and stops a crash caused by it scanning compiler generated types created by the code contracts post-processing tool.

Fixed Method.ImplicitlyImplementedInterfaceMethods in Nodes.cs so that it recognizes interface member matches when the return type is generic.

Fixed GetTemplateMember() and ParametersMatch() to properly check for template parameters when there are method overloads in which one uses a generic type and the other does not (i.e. Contains(T) and Contains(Guid)). This most likely fixed work item 7803 too as it looks similar and the test case works as expected now.

Fixed TypeNode.Attributes so that it won't get stuck in an endless loop if a type's attribute references the type being parsed.

Fixed TypeNode.NestedTypes so that it won't get stuck in an endless loop when a type contains a nested type that itself implements a nested type from within the containing type.

Fixed IsExposedMember() and IsExposedType() in ApiFilter.cs so that they ignore unrecognized type and member visibility values.

Fixed IsExposedMember() so that it compares generic members using the "Name<T>" and "Name{T}" syntax so that it gets a match either way.

Fixed IsExposedExpression() in ApiFilter.cs so that it doesn't exclude a type in an attribute expression as long as the hidden type has exposed members thus exposing the type.

Fixed IsExposedNamespace(), IsExposedType(), and IsExposedMember() in ApFilter.cs so that they exclude members with names containing characters that are not valid in XML (i.e. obfuscated member names).

Fixed MemberDictionary.Contains() so that when checking for matching members it compares generic template parameters by name to match members with generic parameters correctly. This fixes an issue where it treats overridden members as overloads when they contain generic template parameters. This most likely fixed work item 11303 too as it looks similar and the test case works as expected now.

Fixed OrcasNamer.WriteTemplate() so that it uses the correct template parameter names which don't always match the base class's template parameter names (i.e. Collection<TControl> vs Collection<T>).

I'm not sure if one of the other changes fixed it or if it was fixed already in the source code, but work item 2903 (Spurious references to parameterized class with inner class) is fixed as the test cases in it work as expected.

Added a check for exposed members in unexposed types in IsExposedType() in ApiFilter.cs. Such cases effectively expose the type and it should be included whenever this check occurs for it. Without the check, it was incorrectly excluding types in several locations.

Added CompilerGeneratedAttribute check to IsExposedType() in ExternalDocumentedFilter.cs as public members can sometimes be compiler generated (i.e. generated types for public fields that use the "fixed" keyword). This was a new issue I found while testing the "fixed" keyword syntax issue.

Added FixedBufferAttribute to the default MRefBuilder.config API filter as an exposed attribute so that it gets passed through. This is needed in order to properly document fixed members in the syntax section.

Added OptionalAttribute to the default MRefBuilder.config API filter as an exposed attribute so that it gets passed through. This is needed in order to properly document optional parameters.

Added code to write out the new "optional" attribute for optional parameters. This is needed to properly document optional parameters that use OptionalAttribute and have no default specified using assignment. The syntax components and XSL transformations have been updated to make use of it to document optional parameters and their values.

Merged my changes into the AssemblyResolver class to provide support for assembly binding redirection. Added example configuration info for it to MRefBuilder.config.


Added the proxy configuration settings that work around the HTTP 407 and HTTP 417 errors in comments to the BuildAssembler.exe.config file.

Added support for specifying a verbosity level on the configuration element. This can significantly reduce the build assembler output and makes it easier to see warnings as it is much less chatty. The default verbosity is Info so that its default behavior matches prior releases.

Build Components

NOTE: Custom build components that override Dispose() will need to be updated to override protected void Dispose(bool disposing) rather than public void Dispose() as the Sandcastle source code release correctly implements the IDisposable pattern.

Fixed ResolveReferenceLinksComponent2 so that it does not write out unnecessary parentheses on unresolved property elements.

Fixed ResolveReferenceLinksComponent2 so that references to enumerated field types are redirected to the containing enumerated type so as to produce a valid link target.

Fixed the C#, C++, VB.NET, F#, and J# syntax generator components so that they output numeric attribute values. In the event that an unrecognized attribute parameter type is encountered, the syntax generators write out the value as-is. Array parameters are also supported now but the reflection data does not contain the values. As such, it writes out the array type and a generic "{ ... }" placeholder where the values would go. The information is probably there but it would probably require changes to the CCI code to include it.

Fixed the XamlUsageSyntaxGenerator.WritePropertySyntax() so that it generates syntax for properties with abstract return types as long as there is a type converter for it (i.e. Brush).

Added support for a duplicateWarnings attribute that can be added to the data elements of the index element on the CopyFromIndexComponent. When set to false, it suppresses duplicate index key warnings. This is useful for comments files where there can be duplicate keys but it isn't an issue. The default is true if not specified to maintain the behavior from past releases and report the warnings.

Added support for optional arguments to the C#, C++, VB.NET, F#, and J# syntax generator components. I didn't enclose them in brackets as it looked rather odd when attributes were present and the assignment is a dead giveaway that it's an optional parameter. As such, it uses the standard syntax but I did update the XSL transformations to include "(Optional") after the parameter name in the Parameters section of the topic.

Added support for attributes on property getter/setter methods to the C#, C++, VB.NET, F#, and J# syntax generator components.

Made the unsafe code checks consistent across all syntax generators and added a check for the FixedBufferAttribute to the apiIsUnsafeExpression XPath expression.

Added fixed keyword support to the C# and C++ syntax generators.

Added interior_ptr<T> support to the C++ syntax generator. Added a fixup regex to SHFB too so that the comments are included in the member page.

Merged my changes and bug fixes into the MSHCComponent. The changes include support for a sortOrder option on the TOC elements to allow the sort order of the elements to be defined to set the proper placement of the TOC entries when parented to an entry outside of the help file and to parent the API content within a conceptual content folder. Bugs fixed: Duplicate key error under certain conditions and an incorrect XPath expression was letting duplicate metadata through.

Added my JavaScriptDeclarationSyntaxGenerator to SyntaxComponents. Modified FixScriptSharp.xsl to include a scriptSharp element to indicate to the syntax generator that it should apply the casing rules to member names. This allows the added syntax generator to work with normal JavaScript and Script# projects alike.

Merged my changes and bug fixes into the ResolveConceptualLinksComponent:
  • Broken links use the None style rather than the Index style so that it is apparent that they do not work.
  • The inner text from the conceptual link is used if specified.
  • On broken links, when the showBrokenLinkText option is true and there is no inner text, the target value is displayed.
  • Conceptual link targets can include an optional anchor name from within the target such as "#Name".
  • Unnecessary whitespace is removed from the link text.
  • If the companion file contains a <linkText> element and no inner text is specified, its value will be used for the link text rather than the title. This allows for a shorter title or description to use as the default link text.


Updated file masks to use "*.htm?" to find both .htm and .html files. Fixed incorrect check for LCID value. Fixed SubstituteAsciiEquivalents() so that it actually performs the substitutions for encodings other than Windows-1252.

Switched to using EnumerateFiles() which is more efficient for large projects.


Switched to using EnumerateDirectories() and EnumerateFiles() which is more efficient for large projects.

Presentation Styles

Added the new VS2010 style developed by Don Fehr. Consider this a beta release as we work out the bugs. See the VS2010 Presentation Style section above for details.

Applied all of the following fixes and feature enhancements from the Sandcastle Styles patch and some unreported bugs from the discussion pages.

The omitVersionInformation parameter is missing from VS2005\transforms\main_sandcastle.xsl

ResolveArtLinksComponent is wrong in the configs

Enumerated type members no longer contain a description in VS2005 style

The sub-section toggles do not work in Hana and VS2005 because they are not given a unique ID

"this" argument modifier not shown for extension methods

XAML code samples cannot be hidden (VS2005 style)

Cannot link to overloads page

Hana and VS2005 styles generate unnecessary Overloads pages and TOC entries

Unresolved types don't show up in overloaded method signatures in TOC entries and topic titles

Remaining presentation Style Issues

Conceptual: codeEntityReference is sensitive to whitespace

Conceptual: XLinks in relatedTopics section requires explicit text

Support for definition list type is missing.

Conceptual: ddue:copyright processing is broken

ddue:list should support the "nobullet" style

Sections containing nothing but an image or a list of link elements are not rendered

MAML - XSLT Generates Self-Closing Tag for Bookmarks

Some pre elements are missing xml:space="preserve"

FireFox website output issues

Case of Presentation.css is not consistent in transformations. This causes case-sensitive web servers to miss the stylesheet.

vs2005: summary from outer class ends up on inner class member page

Help 1 Sticky Language Filter

Conceptual: Hana style, External link in a token not rendered in relatedTopics

JavaScript syntax section is not shown in the Hana style

Anchor tag styles need to be fixed

Conceptual: All three styles, normalize the space on the abstract

ddue:table handling needs fixing

Rendering of ddue:definitionTable isn't consistent in presentation styles

autoOutline displays "Related Topics" instead of "See Also"

Conceptual: ddue:math should apply templates to its inner text.

Conceptual: Formatting is not applied to some in-line MAML elements

Support linkAlternateText and linkTarget in externalLink

Conceptual: Don't Display Summary in Topic

Prototype syntax sections have unnecessary leading whitespace

Version Builder Issues

Version Builder is broken in the June 2010 release

Conceptual: Hana does not wrap code blocks in <div class="code">

Hana and Prototype styles need to add CHARSET attribute to topics

Conceptual: Hana and Prototype are missing some namespace declarations

ddue:schemaHierarchy and indent templates are missing from Prototype

The Prototype See Also section doesn't have a #seeAlsoSection anchor

seealso tags within an overloads tag not listed

Add missing resource items to Hana and Prototype styles.

APIName Attributes Incorrect (Hana and Prototype)

Support External Hyperlink Target with Appropriate Default

Support term element in bullet and number list types

Support starting number on numbered lists

Add address attribute support to several elements.

Conceptual: Support NamedUrlIndex keywords in metadata

Conceptual: Pass-through HTML (using a markup element) superseded by

Enumeration topics should show the value of each enumeration member

Conceptual: Glossary Improvements

Better implementation of the <note type=""> tag

Better implementation of the ddue:alert element

mediaLink and mediaLinkInline should be handled as separate templates

Conceptual: autoOutline Changes

Auto-generated Bibliography (No dependency on build components)

Add code contract support for VS2005 style

List formatting doesn't look good (all three styles)

Stylesheet updates needed to correct spacing and alignment

Conceptual: Glossary term requires termClass attribute

Conceptual: codeSection template ignores valid code languages

Replace conceptualLink elements in the reference content with anchor links to the actual MSDN pages

Support conceptualLink elements in code XML comments to allow linking to conceptual topics from API member docs

VS2005 CommonUtilities.js fails under MS Help Viewer 2

Unable to Fix

MRefBuilder fails to include certain interop attributes

This does not appear to be correctable. MRefBuilder looks in the custom attributes metadata for attribute info but the missing attributes just don't appear there. It's possible they are included in some other fashion but I haven't been able to find it. If anyone wants to take a second look at this issue to confirm my findings or find out where the info is hidden, feel free to do so.

Non-issues that can be closed

These work items are not related to Sandcastle itself and can be closed (i.e. bugs reported against Sandcastle that are really for the community tools or are user errors).

Failed on localised classes/methods names

Abstract classes help pages have constructor

Sandcastle breaks: chm file never created

SandCastle version out of date

Conceptual: Define in-line MAML element for email semantics
Declined to implement. We never reached a consensus on it's usefulness and it doesn't appear to have attracted any more interest.

Managed C++ generic ICollection<> argument breaks link from code to doc

Remarks and seealso do not work for the project topic

<list type="table"> <remarks> not shown

AssemblyFileVersion attribute is displayed incorrectly

Unhandled NullReferenceException in BuildAssembler

copycode.gif should be CopyCode.gif

Cannot use a hyphen in the title

VS 2010 & .NET 4

Sandcastle doesn't reflectes some classes in FW 4.0 RTM

<inheritdoc> to handle a concrete class with a generic base class that implements an interface

Prototype doesn't render most of the section headers as collapsible sections
Not worth fixing. Deprecated style.

Support Silverlight 5 with WCF RIA Services out of the box

Source code missing

Installer should automatically uninstall previous version

Hierarchical Table of Content PlugIn Issue

After install DXROOT always C:

HHC.exe: Not enough memory error.

Support for .NET 4.0

Inherited members are missing

HTML Help Compiler Stops Working

Documentation is randomly missing from one or more libraries

Unable to view Conceptual Content topics

Missing Page in Website (404 error)

MREFBUILDER : error : Unresolved assembly reference

MRefBuilder does not document type members
The problem here is that without the reference assembly, MRefBuilder does not output the member as an explicitly implemented member (no "#" in the ID and no "implements" info). The member does show up in the reflection data file but without the implementation details, the ApplyVSDocModel.xsl transformation removes it from the reflection data. It probably shouldn't but even if it didn't, the member would still not show up correctly in the documentation. It would appear as a regular member as opposed to an explicitly implemented member. As such, you must add the assembly as a reference so that MRefBuilder can include all of the necessary implementation details.

Issue with Inheritance Hierarchy: does not show all descendants
This is by design. It will only show the immediate descendants of the class, not the entire tree recursively. MSDN is the same. Imagine the tree for a class with a large number of descendants such as System.Windows.Forms.Control or even System.Object itself. Also, that info would have to be present in the reflection file for each class or generated at build time by looking up each descendant recursively. You can drill down into each class to see what descends from it.

Fixed issues that can be closed

These items were fixed in a prior releases of Sandcastle and can be closed.

MRefBuilder fails to find referenced type under certain conditions

Problem with overridden methods in sealed classes

ApplyVSDocModel.xsl loses library information

Conflicting Licenses

Conceptual: VS2005 ddue:span handler breaks code snippets

Prototype root namespaces page does not display at all

Start topic is broken in Prototype model

Prototype conceptual.config invalid XML

EULA/License expired

BuildComponent: Provide standard IDisposable implementation

Bug in conceptualExample\conceptual.config

Invalid K Index entry for constructor APIs
Appears to be fine now so probably fixed in an earlier release.

Last edited Oct 8, 2012 at 4:37 PM by EWoodruff, version 1


No comments yet.