Version, October 2012

Sandcastle Tools

Collapse image Expand Image Copy image CopyHover image

[This is preliminary documentation and is subject to change.]

Version was released on October 2nd, 2012. This was the first official release after merging the Sandcastle tools with the Sandcastle Help File Builder project.

General Changes

  • Added /arg:project=Project to the Generic.targets file in the Reflection target to include a root namespace container in the manifest. This works around an issue with the web output from the example GUI failing if there is more than one namespace in the documented assemblies.


    If you want to build website output, using the Sandcastle Help File Builder is recommended as it has better support for website output than the example GUI.

  • Merged changes from Dany R. into the HTML to MAML Converter to support image alignment, topic ID and revision number metadata, and optional movement of leading topic text into the introduction element.

  • Thanks to Alex Sherman and Sergey Zhurikhin for the Russian translations of the Sandcastle resource item files that have been added to the language pack.

MRefBuilder Tool

  • Added code to Duplicator.VisitTypeReference() so that it doesn'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 (still with me?).

  • Added a check condition in RecordExtensionMethods() to prevent a crash in an odd case where a potential extension method has no parameters.

  • Added support for defining assemblies to ignore if unresolved. This is useful for ignoring assemblies that cannot be resolved for which you do not have a copy such as the Crystal Reports BusinessObjects.Licensing.KeycodeDecoder assembly. See the MRefBuilder.config file for an example definition (the ignoreIfUnResolved child element of the resolver element).

  • Added a new Frameworks.xml file for MRefBuilder to use in loading framework assembly information. This new style of framework definition is enabled by using the framework and version attributes on the platform element in the MRefBuilder.config file. This ensures that the reflection information is accurate for the selected framework type and version.

    The framework and version attribute values correspond to one of the framework sets defined in the Frameworks.xml file. Using this method allows for automatic referencing of core framework assemblies as well as automatic binding redirection from older versions to the defined version for all assemblies in the framework's assembly set (i.e. automatically redirecting the RIA SDK dependencies from the Silverlight 4 versions to the Silverlight 5 versions when producing information for a Silverlight 5 project that uses the RIA SDK). In other words, you no longer need to specify the dependencies or define binding redirections for the standard framework assemblies.

XslTransform Tool

Added an UnauthorizedAccessException check to ignore temporary files that may be locked when attempting to delete them (i.e. virus scanners have them open).

Build Components

  • Made a couple of fixes to BrandingComponent that allows the content to show up in Help Viewer 2.0 that comes with Visual Studio 2012.

  • In the MSHCComponent:

    • Removed the ContentType metadata as it is output by the XSL transformations.

    • Changed SelfBranded to Microsoft.Help.SelfBranded for Help Viewer 2.0 support. Help Viewer 1.0 does not care which name you use for self-branded content but Help Viewer 2.0 requires the qualified name or it attempts to brand the content which causes some odd display issues.

    • Removed the VS2005 header table fix code as it was not needed anymore. It is already handled by the script used in the presentation style (see below).

  • Added an extra slash to the ms-xhelp links generated by ResolveConceptualLinksComponent and ResolveReferenceLinksComponent2 so that they work properly with Help Viewer 2.0. Without it, Help Viewer 2.0 renders invalid links for some reason.

Presentation Styles

  • Replaced conceptualLink elements with anchor links to the corresponding MSDN topics in the VS2010 style's resource item files.

  • Removed the style attribute from VS2010\Branding\ps-codesnippet.xslt as it was causing issues with FireFox and Chrome when viewing website output. The attribute appears to be unnecessary and its removal does not appear to affect the results.

  • Added a case for using the currently defined target attribute value on an external link in VS2010\Branding\ps-instrumentedLink.xslt so that it honors the user-defined link target rather than always forcing it to _blank.

  • Fixed a bug in Presentation\VS2010\Branding\ps-instrumentedLink.xslt that caused local links to be rendered with an incorrect URL in Help Viewer 2.0.

  • Removed the background attribute from the nsrBottom table element in the VS2005 style as it was breaking the language filter links at the top of the page in Help Viewer 2.0. The script sets the background so it was not needed anyway.

  • Fixed various other issues in the VS2005 and VS2010 presentation styles to get them to work properly with Help Viewer 2.0.

  • Fixed the VS2005 and VS2010 presentation styles so that F1 keywords work properly when looking up API members via F1 in Visual Studio with MS Help Viewer.

  • Merged the collapsible section changes for MAML content from Microsoft into the Prototype style (Sandcastle work item #2269).

  • The dev10.mshc file from Visual Studio 2010 is no longer required. Due to differences in the way Help Viewer 2.0 works and the fact that the file is not part of Visual Studio 2012, a temporary file of the same name has been included with a set of transformations necessary to get the content built with Sandcastle. A future release will probably get rid of it altogether in favor of integrating its various parts directly into the presentation style.

See Also

Other Resources