Important
You will need to delete the content ID cache in order for this change to have any effect. See the User Configuration Settings and Cache Files section of the Special Folder Locations topic for details.
Sandcastle Help File Builder Documentation
Version 2014.11.22.0
Release notes for version 2014.11.22.0.
Breaking Changes
The first two changes affect all users. The remaining changes will only affect those that have created custom build components, syntax generators, plug-ins, and presentation styles. Carefully read the following items as you will need to update your components based on these changes.
Moved the colorizer files from the Sandcastle Builder GUI project to the Presentation Styles project where they are a better fit. This changes the location of the colorizer files and places them under the PresentationStyles\ folder. If you have added the Code Block Component to your project, you will need to remove it and re-add it or update the configuration to add the "PresentationStyles\" folder ahead of the "Colorizer\" folder in the configuration file location options.
Added code to the Resolve Reference Links Component and Copy From Index Command to check for and use broken explicitly implemented interface (EII) member IDs if the correct one is not found. This works around a bug in the base framework XML comments file member IDs and the MSDN content service IDs for certain inherited EII members.
Moved the syntax generator resource items to the syntax generator BuildAssembler project. This allows the syntax generators to be more self-contained and allows them to be created without requiring changes to the presentation styles.
Added a new ResourceItemFileLocation property to the syntax generator factory interface. This is implemented to return the path to the resource item file associated with the syntax generator containing its localized text for titles, messages, metadata, etc. This allows creation of self-contained syntax generators that require no modifications to the presentation styles with which they will be used.
Updated the Open XML, VS2010, and VS2013 presentation styles so that they are no longer dependent on the syntax generator items and IDs.
MS Help 2 (HxS) Format Support Deprecated
Effective with this release, support for the MS Help 2 (HxS) help file format used in Visual Studio 2008 and earlier has been deprecated. It is just too cumbersome to maintain a separate environment with an older version of Visual Studio and its SDKs in which to test this obsolete help format. Going forward, no further updates or fixes will be made to support it. Any new presentation styles created in the future will not support it either.
Help File Builder
A NuGet package is now available (EWSoftware.SHFB) to allow for build server deployments and local project copies of the tools that can be checked into source control.
Fixed the Version Builder plug-in so that it correctly generates the version IDs used in the configuration file and the label resource items. It is now possible to have "prior" projects that use different framework labels with a version number that matches the "current" project.
Fixed the Additional Reference Links and Version Builder plug-ins so that they correctly apply the Configuration and Platform properties to the sub-projects to ensure they are evaluated properly in project properties when the sub-projects are loaded.
Fixed the VSPackage IntelliSense provider by adding "langword" as a prefix to the language keyword entries to prevent an odd crash in VS 2013.
Merged changes from Sam Harwell to enable the Visual Studio C# documentation completion provider to work properly if the Roslyn package is installed which uses a different implementation of IntelliSense.
Fixed the Lightweight TOC plug-in so that it adds some script to the default topic to expand the root node when the first node has children. This prevents it from looking like only one namespace was documented because the root node is collapsed.
Fixed the Lightweight TOC plug-in so that it transforms the help title property value to ensure substitution tags in the value are replaced.
Fixed the DBCS Fix plug-in so that it copies the Help 1 content to the output folder for inclusion in the localized copy of the content.
Fixed the XPath Reflection File Filter plug-in so that it runs before transforming the reflection file content and generating the BuildAssembler manifest file.
Applied a fix from Kalyan00 to the Sandcastle HTML Extract tool so that it correctly saves files in the localized and original locations with the proper encodings.
Set the maximum degree of parallelism in the Sandcastle HTML Extract tool to 20 threads per processor. This is configurable but is not currently exposed. It can be adjusted by adding a MaxDegreeOfParallelism property to the HTML extract project template and passing it to the task if needed.
As suggested by Kaylan00, the DBCS Fix plug-in has been changed so that the path to the SBAppLocale tool is optional. If not specified, the plug-in will issue a warning but will run. In such cases, only the localization fixes applied by the Sandcastle HTML Extract tool will be in effect.
Added support for NamespaceGroupDoc classes in XML comments files to add documentation to namespace group topics.
Added the Member ID Fix-Ups Plug-In to allow fixing up member IDs in XML comments files that do not match the reflection data due to quirks in the various compilers. This can be used in place of or in conjunction with the C++ Fix-Up project property.
Added the IntelliSense Only Plug-In that can be used to suppress the help file build steps and produce only the IntelliSense XML comments files when used in conjunction with the IntelliSense Component. This is useful for supporting projects that need IntelliSense XML comments files but do not contribute content to the help file directly (i.e. those in the Version Builder plug-in configuration).
Added support for installing the VSPackage in Visual Studio 2015 Preview and added support for the .NET Framework versions 4.5.2 and 4.5.3.
Documentation
Added information to the XML Comments Guide about using NamespaceGroupDoc classes.
BuildAssembler and Build Components
Fixed a bug in the Syntax Component so that it does not crash if a syntax generator does not specify any alternate IDs.
Updated the syntax generators to write out method parameter attributes.
MRefBuilder
Fixed MRefBuilder so that it properly matches types and methods with generic parameters under certain specific conditions. Thanks to Jared Moore for reporting the issue with a test case.
Fixed MRefBuilder so that it filters out duplicate member IDs from derived interfaces that re-implement base members using the "new" keyword. Thanks to rpcode for reporting the issue with a test case.
Added a new namer component for Windows Store and Windows Phone frameworks that renames certain core types that the compiler changes when building assemblies. This ensures that the reflection data matches the XML comments which contain the expected type names. The new namer component is used automatically when generating reflection data using a Windows Store or Windows Phone framework version.
Added code to write method parameter attribute elements to the reflection information file.
Added code to write out the value of literal (constant) fields to the reflection information file.
Presentation Styles
Fixed the copyright replacement tags in the SHFB content files so that they use the HTML encoded text.
Fixed an invalid end element in the German and Russian language versions of the enumerationOverviewXamlSyntax element.
Fixed the VS2010 and VS2013 presentation styles so that code blocks with line numbers and/or collapsible sections are copied to the clipboard without those elements.
Fixed the code contracts templates so that the inherited property member IDs in reference links are rendered correctly.
Removed an extraneous comma in the VS2013 branding-Website.js file which was causing problems in Internet Explorer (reported by baerbradford).
Merged a few style changes into the VS2013 website style sheet from Sam Harwell related to the resize/drag divider.
Added support for including conceptual links in overloads elements.