Version 2022.8.14.0

This release contains significant breaking changes related to how the presentation styles are implemented. All XSL transformations have been removed and a new code-based API is now used to generate all topics. This makes it much easier to extend and modify presentation styles with simple plug-ins and build components rather than cloning and modifying an entire presentation style and working with cumbersome XSL transformations. Such components will work with whatever presentation style is selected.

Many of the build tools have been merged into the build engine and now run in process rather than out of process as MSBuild tasks. This will affect custom plug-ins that relied on modifying the related build scripts for those tools. See the Build Components and Tools section below for details.

All custom build components and plug-ins will need to be updated to use the latest NuGet packages. The constructor for all build components will need to be updated to accept a parameter of the type IBuildAssembler rather than BuildAssemblerCore. See the Component Migration Support topic for information on how to update custom components created for use with version v2021.4.9.0 and earlier for use with the latest release of the help file builder.

• Help 1 (CHM) and Help Viewer (MSHC) Support Deprecated
• Presentation Styles
  • General Changes
  • Default2022 Presentation Style
  • Open XML Presentation Style
  • Markdown Presentation Style
  • VS2010 and VS2013 Presentation Styles
• Build Components and Tools
• Sandcastle Help File Builder

With this release, support for the Help 1 (CHM) and Help Viewer (MSHC) formats is deprecated. With the end of support for Internet Explorer, it seems unlikely that either of the help viewers for these formats will receive any future support or updates from Microsoft as they both use the Internet Explorer control to display the help content. This makes it difficult if not impossible to support the latest HTML features in the new presentation style. The VS2010 presentation style has been removed and the VS2013 presentation style is now considered the legacy presentation style. It is the only presentation style that will support generation of Help 1 or Help Viewer output. All future presentation styles will only support website, Open XML, or Markdown output.

The HTML Help Workshop used to compile Help 1 files no longer appears to be available from Microsoft. A copy is available from the project website if you still need it. See the Installation Instructions topic for a link.

In the event that the MSHC Help Viewer is updated to use something newer such as the WebView2 control that does support the latest HTML features, support will be added back for that format.

The following changes were made to the presentation styles.

General Changes

• All presentation styles have been rewritten to use the new code-based API that is much easier to extend and modify without having to clone and implement a full presentation style. The new API contains support for adding, removing, and reordering sections as well as adding new element handlers via standard help file builder plug-ins. Topic templates are supported to define the general structure of the topics and can be replaced via plug-ins to alter the overall topic layout. This can also be applied at the element level and is currently used by the alert/note, code block, and syntax section element handlers.

• Minor updates were made to the styling and topic layout of all existing presentation styles to make them more consistent with each other and so that common element handlers could be used for all of them where possible.

• Support for the code contracts elements was removed from all presentation styles as the related Microsoft project appears to have been abandoned. Support for these elements may be provided in a separate component package as an example of how to use the new API at a later date.

• The icons, style sheets, and scripts paths were removed from the resource items and made properties on the transformation class so that they can be modified more easily by plug-ins.

• All presentation style resource items have been merged into a single, shared set that is used by all presentation styles. All unused resource items (about 50% of them) were removed.

• Removed the HelpFileBuilderTokens.tokens file as it only contained the auto-outline token and auto-outlining is supported directly within MAML topics. The reference in the presentation style BuildAssembler configuration files was also removed.

• Removed the BuildAssemblerVerbosity substitution tag and the reference to it in the presentation style configuration files.

• Removed the component locations element from the presentation style BuildAssembler configuration files as it is no longer used.

• Added a BibliographyDataFile transformation argument in all presentation styles to support the bibliography and cite elements natively. This replaces the plug-in used in prior versions for bibliography support.

• Added a RobotsMetadata transformation argument in all presentation styles to allow adding an optional robots metadata value to all topics (e.g. noindex, nofollow).

• Added an EnumMemberSortOrder transformation argument in all presentation styles to allow specifying how enumeration members are sorted (by value or by name).

• Added a FlagsEnumValueFormat transformation argument in all presentation styles to allow specifying the format of flags enumeration values (integer value, hex value, or bit flags).

• Added a FlagsEnumSeparatorSize transformation argument in all presentation styles to allow specifying the separator group size for flags enumeration values (0, 4, or 8). This determines where separators are placed in the formatted value (e.g. 0b0000_0000, 0x1234_ABCD). If set to zero, no separators will be inserted.

• Extended the markup element with a contentType attribute that can be used to define for what output format the content should be rendered (Html, OpenXml, or Markdown).

• Extended the note and alert elements with a new todo note type for To Do lists. Also added support for an optional title attribute to allow overriding the note/alert title.

• Found various inconsistencies on when types were and were not qualified in the various topic sections. Updated them to be consistent with how Microsoft Docs qualifies names for the most part.

• Fixed up some inconsistencies in the formatting of the syntax section code generated by the syntax components.

• For website presentation styles, the minimum search keyword length was reduced to two characters. The ASPX search pages were modified to allow "contains" searches so that it will find partial keyword matches.

Default2022 Presentation Style

This is the new default presentation style. It only produces website output and has been written to use a more modern style with a responsive layout that should work well on any device from mobile to widescreen desktop displays. The topic and section layout is similar to that of Microsoft Docs.

• Topic structure and styling is implemented using Bulma and Font Awesome.

• Code colorizing is handled client-side using highlight.js.

• It uses a slightly different TOC structure from the VS2013 presentation style consisting of a breadcrumb trail at the top of the page and a hierarchical table of content that shows an appropriate fragment of the overall table of contents based on the selected topic.

• A RootBreadcrumbTitleText transformation argument is available to set the root breadcrumb title.

• A CollabsibleSections transformation argument is available to allow turning off rendering of collapsible section headers within the topics.

Open XML Presentation Style

• Fixed the Open XML file generator so that it produces a valid archive file that works with the updated .NET Framework packaging types.

• Member list pages are now suppressed in the Open XML output as they did not serve any useful purpose and were repetitive.

Markdown Presentation Style

• Fixed up some issues with how the markdown was rendered under certain conditions.

VS2010 and VS2013 Presentation Styles

• The VS2010 presentation style has been removed. It was simply too old and the VS2013 presentation style is close enough in format to it that it didn't make sense to keep it going forward. Use the VS2013 presentation style if you need support for Help 1 or Help Viewer output. See the Help 1/Help Viewer section above for related information.

• Updated the VS2013 icon image name casing to match how the presentation style renders them now.

• Updated member list rendering to show the extension method icon for extension methods in their containing type to match IntelliSense.

• Corrected the casing in the .\tools path in the help file builder NuGet package properties file so that it works correctly on Linux-based systems.

• Added ProgIdAttribute to the attribute filter in the MRefBuilder.config file so that it is included in the syntax sections.

• Updated MRefBuilder to add type hierarchy information for structures.

• Fixed the extension methods MRefBuilder add-in so that it correctly associates extension methods with a nullable, reference, or nullable reference type parameter with the actual related type so that they show up in the type's topic.

• The BuildAssembler code has been moved in to SandcastleBuilder.Utils and is called directly from within the build engine. The related BuildTopics.proj template was removed.

• Build component constructors are now passed an IBuildAssembler interface reference used to interact with the build engine.

• A new BuildAssembler property was added to BuildComponentCore that allows build components to interact with the build engine.

• The static Data property in BuildComponentCore was removed and an instance-based Data property was added to the IBuildAssembler interface.

• The LogLevel enumeration was removed and replaced with the MessageLevel enumeration as it contained duplicate values. The MessageLevel.Ignore enumeration value was removed as it was unused. The MessageLevel enumeration was also moved to the Sandcastle.Core namespace so build components will need to add a using statement for it if they log messages.

• Added BuildAssemblerConfigurationFile and BuildAssemblerManifestFile properties to BuildProcess. These should be used in place of the hard-coded sandcastle.config and manifest.xml filenames.

• Removed the Sandcastle HTML Extract tool and moved the code into the build engine. The related ExtractHtmlInfo.proj template was removed.

• A new HtmlExtractTool property was added to the build engine to allow plug-ins to adjust how the tool runs.

• Removed the Open XML file generator task and moved the code into the build engine. The related BuildOpenXmlFile.proj template was removed.

• Removed the markdown generator task and moved the code into the build engine. The related GenerateMarkdownContent.proj template was removed.

• Removed generation of the website keyword index file (WebKI.xml) file as it is not longer used anywhere.

• Update the IntelliSense build component to include remarks elements. These are shown by Visual Studio 2022 in the quick info tips now.

• Fixed an issue with the package reference resolver so that it correctly finds package reference assemblies whether or not the version number contains or does not contain the trailing zeros in the version numbers.

• Added a notopic attribute to the root group API entry (G:) generated by the namespace grouping code when the root namespace container option is disabled. This prevents the topic ID from being incorrectly included in the topic manifest.

• Removed the HTML to MAML converter tool from the tools distribution. It has been moved into its own project repository.

• Removed the web code providers assembly from the tools distribution. It has been moved into its own project repository.

• Removed the bibliography support plug-in. It has been replaced by a BibliographyDataFile transformation argument in all presentation styles to support the bibliography and cite elements natively.

• Removed the AjaxDoc plug-in, Script# plug-in, Manual Visibility/API Filter plug-in, and the ESent and SQL data cache components. These will be distributed as one or more separate legacy component NuGet packages at a later date.

• The presentation style project templates have been temporarily removed from the Visual Studio package. Updated presentation style project templates will be added to a future release.

• Due to a breaking change in the version of MSBuild deployed with Visual Studio 2022 17.3, the standalone GUI is restricted to using a version of MSBuild for Visual Studio 2017, 2019, or a version of 2022 less than 17.3. If you do not have Visual Studio 2017 or 2019 installed, install the related version of the build tools instead. See the installation instructions for a link.

Other Resources