Version 2021.11.7.0

  Important

This release supports both .NET Framework (MSBuild.exe) and .NET Core (dotnet.exe) builds. Many significant breaking changes were made in order to provide this support.

All third-party build components, plug-ins, presentation styles, and syntax generators built against v2021.4.9.0 and earlier must be updated for use with the latest release. Unlike past releases, this will require more rework than usual. However, the benefits are components that will work with both build types and simpler deployment of the components as NuGet packages. See the Component Migration Support topic for more information.

See the Known Issues and Limitations topic for known issues with .NET Core builds.

This release is a minor update to version 2021.10.23.0 which originally contained these changes.

Breaking Changes

  • Updated all build engine components to target .NET 4.7.2 and .NETCoreApp 3.1. The latter allows for builds using the dotnet.exe tool. The core libraries, build components, plug-ins, and presentation styles target .NET Standard 2.0 so that they are universal.

  • Restructured the SHFBROOT folders to allow for the tool version and platform-specific code to be cleanly separated. See the Help File Builder Build Engine topic for details.

  • Separated Windows platform-specific code out into separate assemblies. The Sandcastle.Platform.Windows assembly contains the shared code. Reworked all build components and plug-ins to separate the configuration UIs into separate Windows platform-specific assemblies. This allows the components themselves to be used with both .NET Framework and .NET Core builds while allowing the IDEs to still configure them interactively.

  • All build tasks were moved from SandcastleBuilder.Utils to their own assembly (SandcastleBuilder.MSBuild).

  • Consolidated the tools and components into common namespaces and merged the help file builder build components into the main build components assembly.

  • The Add Namespace Groups tool was removed. The code was merged into the build engine under a new build step (BuildStep.AddNamespaceGroups).

  • The Version Builder tool was removed and the code from it was merged into the related plug-in were it runs directly now at build time.

  • The XSL Transform tool and the related production XSL transformations were removed. The XSL transformation processing was moved into the build engine in three new build steps: BuildStep.ApplyDocumentModel handles the processing formerly in ApplyVsDocModel.xsl, BuildStep.AddApiTopicFilenames handles the processing formerly in AddFilenames.xsl, and BuildStep.GenerateApiTopicManifest handles the processing formerly in ReflectionToManifest.xsl. Along with BuildStep.AddNamespaceGroups, these new build steps replace BuildStep.TransformReflectionInfo which was removed.

    The processing formerly in CreateVSToc.xsl is handled by new code in the build engine that runs under the existing build step BuildStep.GenerateIntermediateTableOfContents. These changes should allow for better extensibility of the related build steps in the future.

  • Updated all presentation styles to use the code-based interfaces for applying the document model to the reflection information file and generating the intermediate table of contents. These replace the old properties that specified the related XSL transformations to use. Custom presentation styles are free to use the default implementations or supply their own. It is also now possible for plug-ins to replace them at runtime as long as the replacements meet the requirements of the presentation style.

  • Removed BuildStep.GenerateHelpFormatTableOfContents and BuildStep.GenerateHelpFileIndex as they effectively did nothing anymore.

  • Removed the BuildAssembler build components DisplayComponent, InheritDocumentationComponent (not used by the help file builder to generate inherited documentation), PlatformsComponent, SnippetComponent, TaskGrabberComponent, and ValidateComponent as they were never used.

  • Updated all Visual Studio component template projects so that they work with the updated build engine. The template projects were also updated to use the new SDK format and generate their output as NuGet packages. This makes them easier to find and use and no longer requires a common component path setting be used in the help file builder projects to locate them.

  • Updated the build engine to search for build components, plug-ins, presentation styles, and syntax generators added to the project as NuGet packages by looking for their SHFBComponentPath build property items. The component path project property, common application data, and local application data folder locations are still supported but are not necessary when components are added as NuGet packages.

  • Due to changes in the folder structure of the tools, some component and plug-in configurations may need updating. In most cases, simply opening the configuration form and saving the configuration should correct these issues. If there are still problems after doing that, it may be necessary to remove the component from the project, add it back, and set the configuration options again.

Build Components and Tools

  • Fixed the Show Missing Component so that it handles parameter names containing single quotes which can occur in F# code.

  • Added the InternalAndPrivateIfExternal visibility setting to control whether or not internal members from other assemblies and private members of base type are included. It is set to false by default to exclude them.

  • All build component and plug-in configuration forms were updated to use WPF for better high DPI scaling support on 4K displays. The standalone GUI hosts all of the WPF controls and UI forms but is a Windows Forms application at its core. That probably will not change anytime soon.

  • All reflection data NuGet packages were republished with updated build properties so that they support the new SHFBComponentPath item used to locate components in NuGet packages.

  • The AjaxDoc plug-in has been deprecated. AjaxDoc itself has been deprecated in favor of JSDoc. The plug-in is also dependent on Windows platform-specific features and cannot be used with .NET Core builds.

Presentation Styles

  • Added a new logoUrl transform argument property to the VS2010 and VS2013 presentation styles. This allows you to specify a URL to navigate to when the logo is clicked.

Sandcastle Help File Builder

  • Fixed the API content placement option so that it works again in site map files.

  • Updated the standalone GUI and Visual Studio package to support adding package references to help file builder projects for build components, plug-ins, presentation styles, and syntax generators interactively with a search dialog box. The component packages are shown in a separate node in the project/solution explorer tool window. This option can also be used to add the tools package and reflection data packages to the project for build server support.

  • Updated the Visual Studio package to install the MAML schemas rather than installing them separately through the guided installer. This prevents them from being lost when Visual Studio is updated.

  • Added support for Visual Studio 2022. Because Visual Studio 2022 is a 64-bit application the help file builder package for it is installed separately from the Visual Studio 2017/2019 version. Although tested as much as possible, due to the large number of features in the project system, there may be issues. If any are found, please open an issue on the project site so that they can be investigated.

See Also

Other Resources