Important
The Sandcastle tools are now installed as part of the Sandcastle Help File Builder and there is no longer a separate installer for them. As such, you will need to manually remove the prior release of the Sandcastle tools. Leaving them installed will not cause any issues as the new release is located in a different folder. However, removing them will avoid any confusion in the future.

The majority of the following changes will only affect those that have created custom build components, syntax generators, plug-ins, and presentation styles. If you have, carefully read the following items as you will need to update your components to work with the new Managed Extensibility Framework based implementation.

• Consolidated the Sandcastle Help File Builder and Sandcastle tools under a single, common folder structure. These changes were necessary in order to simplify deployment and support changes to the component model.

• Since the tools have been consolidated under a single folder, the DXROOT environment variable is no longer needed. All tools now use the common SHFBROOT environment variable instead where needed.

• Removed support for the SHFBCOMPONENTROOT environment variable as its functionality is handled by the new ComponentPath project property.

• Updated all build components, syntax generators, plug-ins, and presentation styles so that they are implemented using the Manged Extensibility Framework (MEF). A lot of code was moved into a new Sandcastle.Core library that holds the base classes and MEF implementation classes common to all of the other projects in the tool set. This change allows for dynamic discoverability of components at runtime without the need for special configuration files or file naming conventions. It also allows for the use of project-specific components located within a help file project's folder or one that it refers to through the new ComponentPath property.

• Changed the syntax generator IDs to their actual language names so that they are displayed using the language name in the help file builder. This should be transparent to most projects but if you have BuildAssember configuration files you will need to update the syntax generator IDs in them.

• Switched to a date-based version numbering scheme (YYYY.MM.DD.RR) and updated all tools to use a common version number. Changes were also made to the versioning attributes to minimize the need to rebuild third party components with each new release of the tools. In future, it should only be necessary to rebuild third party components if a breaking changes was made requiring an update to the version number used in the strong name of the dependency assemblies.

• Removed the SandcastlePath project property and all references to it as it is no longer needed. It may show up in the User Defined Properties property page. If so, it can be removed from there.

• The help file builder presentation style resource item files have been moved into each presentation style so that the presentation styles are self-contained.

• The help file builder stop word list files have been moved into the Shared\StopWordList folder under the presentation style folder so that the localizable resources are all in one common location.

• Removed the ApplyVisibilityProperties build step as visibility properties are applied to the reflection information by MRefBuilder now. The ApplyVisibilityProperties() method was modified to take a filename so that plug-ins can use it to remove members from reflection files generated by other means.

• Moved the TransformReflectionInfo build step to run ahead of the GenerateNamespaceSummaries build step to allow generation of group topics for use in the namespace summary editor dialog in a partial build.

• Redefined the partial build in the build engine to allow stopping it after generating reflection information or after the document model XSL transformation and grouping options have been applied.

• The following obsolete and deprecated help file builder build components have been deleted so that they did not have to updated for use with MEF. If you still have them in older projects, they will need to be removed, re-added, and re-configured as needed:

  • CachedCopyFromIndexComponent - Superseded by the base components and the ESent/SQL caching components.

  • CachedResolveReferenceLinksComponent - Superseded by the base components and the ESent/SQL caching components.

  • IntelliSenseComponent - Moved to the BuildAssembler components project.

  • MSHelpAttrComponent - Moved to the BuildAssembler components project.

  • PostTransformComponent - Code block handling moved to the code block component and logo support moved to the XSL transformations.

  • ShowMissingComponent - Moved to the BuildAssembler components project.

  See the prior version release notes for more details.

• Fixed the project class so that it does not incorrectly try to update the tools version and mark the project as dirty under Visual Studio 2013.

• Fixed the BuildHelp task and standalone GUI so that all warnings regardless of format are output to the console when verbose logging is disabled.

• Fixed the framework XML comments file enumerator method so that it ignores folders that exist but contain no XML comments files.

• Fixed the Sandcastle HTML extract tool so that it finds the HxLink.css reference regardless of the element's attribute order.

• Fixed the Version Builder plug-in so that it finds the correct XML comments file when the GenerateProjectSpecificOutputFolder MSBuild option is used.

• Fixed the standalone GUI so that it loads per project user state properly.

• Fixed the build log viewer so that it transforms the log correctly under Visual Studio.

• Added support for installing and removing MS Help Viewer content in Help Viewer 2.1 from the standalone GUI and VSPackage. Updated the example scripts to show how to do it as well.

• Updated the standalone GUI to use the evaluated output path value if it contains MSBuild variables. This allows it to clean and display the output under such conditions.

• Updated the build engine to run the Sandcastle tools as MSBuild tasks.

• Added support for a ComponentPath project property used to specify the location of project-specific build components, syntax generators, plug-ins, and presentation styles. If not specified, the project's folder alone is used.

• Added support for the "No-PIA embedded interop types" visibility option.

• Exposed the ReferenceOutputAssembly property on project references. If set to false, the project reference will only be used for MSBuild dependency determination and will not be used as a reference for MRefBuilder. This allows MSBuild to determine the correct project build order when building projects in a solution in parallel.

• Added F# to the standard set of syntax filters to match MSDN. Note that if you have been using the standard set (C#, VB.NET, C++), you will gain F# by default. Turn it off in the Syntax Filters property on the Help File properties page if you do not want it included in the topics.

• Added namespace grouping support in the form of two new properties located on the Help File property page: NamespaceGrouping and MaximumGroupParts. Note that the selected presentation style must support namespace grouping for these properties to be effective. Only the VS2005 and VS2010 styles support namespace grouping in this release.

• Updated the Namespace Summaries dialog to allow editing of namespace group summaries.

• Deprecated the Hierarchical TOC plug-in as its functionality has been replaced by the namespace grouping options. It is still available for presentation styles that do not support MS Help Viewer output or namespace grouping (Prototype and Hana).

• Removed the Expand All button from the website index pages as it was not very useful and could cause a heavy load on the web server.

• Applied changes to the web table of contents style from Sam Harwell.

• Minimized the use of the SHFBROOT environment variable where possible. It is still needed in some places to allow for XCOPY deployment of the tools. It is possible to run without it defined if you create a SHFBROOT project property that points to the tools. See the XCOPY/NuGet Build Server Deployment topic for details.

• Added code the VSPackage to allow using a locally defined SHFBROOT project variable to set the SHFBROOT environment variable if it does not exist. This allows using it without the SHFBROOT environment variable defined.

• Added template projects for C# and VB.NET in the Documentation subcategory used to create plug-ins, build components, syntax generators, and presentation style components. The template code contains the necessary MEF attribute and/or factory class to produce a valid component.

Other Resources