Sandcastle Help File Builder Changelog

What's new in Sandcastle Help File Builder 2024.2.18.0

Feb 19, 2024

Help 1 compiler check and instructions on where to download it and how to install it if needed
Sandcastle Help File Builder and Tools v2024.2.18.0
SHFB Visual Studio Extension Package including MAML schemas (VS 2017 or later)
An option to install MAML snippets in Visual Studio to provide insertion of common MAML elements in topics while editing

New in Sandcastle Help File Builder 2023.7.8.0 (Jul 9, 2023)

New in Sandcastle Help File Builder 2023.3.4.0 (Mar 5, 2023)

New in Sandcastle Help File Builder 2022.12.30.0 (Jan 1, 2023)

New in Sandcastle Help File Builder 2022.10.15.0 (Oct 16, 2022)

New in Sandcastle Help File Builder 2022.8.14.0 (Aug 15, 2022)

New in Sandcastle Help File Builder 2022.2.6.0 (Feb 6, 2022)

New in Sandcastle Help File Builder 2022.1.22.0 (Jan 23, 2022)

New in Sandcastle Help File Builder 2021.11.7.0 (Nov 7, 2021)

New in Sandcastle Help File Builder 2021.10.23.0 (Oct 31, 2021)

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.

New in Sandcastle Help File Builder 2021.4.9.0 (Apr 11, 2021)

New in Sandcastle Help File Builder 2021.4.5.0 (Apr 6, 2021)

New in Sandcastle Help File Builder 2021.3.29.0 (Mar 30, 2021)

Sandcastle Help File Builder:
Removed all MSBuild assemblies from the distribution and updated the standalone GUI and all tools to use the MSBuild Locator to find a copy of MSBuild to use. This should remove the dependency on a specific version of the MSBuild tools in the standalone GUI. As long as some version of the MSBuild Tools is installed (2017 or later), it should work as expected.
Added the source URI to XML exception information in build errors to help identify the file causing the problem.
Fixed handling of properties in the property pages of help file builder project files so that if a property such as OutputPath is overridden by an import, it uses the correct copy from the help file builder project for editing.
Modified the order of XML comments file processing so that XML comments files added to the help file builder project as documentation sources will always override XML comments files from projects containing matching members. This allows the help file builder project comments file to replace or add to comments in the documentation source project comments file. This is useful for substituting comments files for different languages.
Changes in this release should resolve all issues related to automatically finding the implicit package references for .NET Standard 2.1 and .NET 5.0 projects when used as documentation sources. It should now be possible to use projects as documentation sources for all platform types without the need for manually adding references to assemblies in NuGet packages.
Made adjustments to which platform types can be documented together within the same help file builder project. In general, platforms that have all of their core types in mscorlib or netstandard are compatible (e.g. all .NET Framework or all .NET Standard 2.x but the two cannot be mixed in the same documentation project). All platforms that redirect their core types to System.Runtime or other assemblies are also typically compatible (e.g. .NET Standard 1.x, .NET Core, and .NET 5.0). Mixing platforms from the two sets or with any combination of other platform types is typically not compatible. The help file builder will detect the common issues and disallow them (error BE0070).
There may be certain combinations that are still not compatible with each other and will result in invalid documentation or a build failure. MRefBuilder to is able to detect a few of these cases and will report an error or warning in such cases. Any such issues will have to be addressed in a future update.
As noted above, a proper reflection data set for .NET Core/.NET Standard/.NET 5.0 or later was added. This replaces the old Cross-Platform reflection data set which should be considered obsolete and should not be used anymore as the framework version in the help file builder project.
A new TargetFramework property was added to documentation sources. If set to a recognized target framework value (e.g. net40, netstandard20, net5.0, etc.), this is used to determine which assembly to use when extracting assembly and comments file information from projects that use multi-targeting. If not set, the build engine will make an attempt to determine a common target framework based on all projects given as documentation sources. If one can be found, it will be used. If a common target framework cannot be determined, the first target framework in each project will be used.

New in Sandcastle Help File Builder 2020.3.6.0 (Sep 24, 2020)

New in Sandcastle Help File Builder 2016.5.28.0 (May 29, 2016)

New in Sandcastle Help File Builder 2015.10.10.0 (Nov 4, 2015)

New in Sandcastle Help File Builder 2015.7.25.0 (Jul 28, 2015)

Deprecated Features Removed:
Effective with this release, the following changes were made to remove deprecated features that are no longer supported:
Removed unused tools: AggregateByNamespace, ChmBuilder, DBCSFix, MergeXml, SegregateByAssembly
Removed the /internal MRefBuilder command line option.
Removed the obsolete platform configuration options from the MRefBuilder configuration file.
Removed the Prototype style and Microsoft Help 2 production XSL transformations.
Removed the deprecated presentation styles: Prototype, Hana, and VS2005
Removed the Hierarchical TOC plug-in. It did not work with MS Help Viewer output and was superseded by the namespace grouping support in the presentation styles.
Removed support for the Microsoft Help 2 file format and all related project properties: HtmlHelp2xCompilerPath, CollectionTocStyle, MSHelp2SdkLinkType, IncludeStopWordList, PlugInNamespaces, and HelpAttributes.
Removed the CppCommentsFixup property and all related code. Use the Member ID Fix-Ups Plug-In instead.
Removed support for topic (.topic) file transformation and the TopicTransform build action.
Removed the file system based additional content model used to add HTML topics to the table of contents. HTML files can still be included but a site map file must be added to the project to define their layout in the table of contents.
Removed all HTML file transformation options (code import, code colorizing, replacement tags, etc.). HTML files can still be included and referenced via a site map file but they will not receive any transformation.
Removed support for HTML files from the content layout file editor. Only MAML topics can appear in a content layout file.
Removed support for the project item metadata element ExcludeFromToc.
Removed the old project format converters and the New Project from Other Format option in the standalone GUI and Visual Studio package. I could not guarantee they worked well now anyway and they were getting in the way of other changes I want to make to the build engine.
Dropped support for Visual Studio 2010 and 2012 from the Visual Studio package.
Dropped support for installing the schemas and snippets in Visual Studio 2008-2012 in the guided installer.
Breaking Changes:
If you use the ESent or SQL Server data caching components, they will need to be removed and added back to your projects in order to obtain changes made to their configuration elements. If you have created custom build components, syntax generators, plug-ins, or presentation styles, carefully read the following items as you may need to update your components based on these changes. If you need help in determining how to update a component so that it can be used with the new build engine, please open an issue at the project site on GitHub.
Updated all projects to use .NET 4.5 and made it the minimum framework version in the guided installer.
Changed the build engine so that it can be ran in the background as an asynchronous task rather than requiring a separate thread.
Removed lots of obsolete code from the build engine and changed the SandcastleProject class so that it is a read-only wrapper around the underlying MSBuild project. This prevents inadvertent changes to the underlying project during builds and allows building sub-projects without first having to clone the sub-project in case it is already in the global project collection.
Reworked documentation source component enumeration to simplify usage.
Reworked conceptual content item enumeration and added the ability to add conceptual content items directly to the build process instance without having to use a temporary project instance from which the items are copied to the build process.
Moved the manual visibility and API filter methods from the build engine into a new Manual Visibility/API Filter Plug-In. If your plug-in made use of the old methods in the build engine that manually applied the API filter and/or visibility options, remove the related code and note in your plug-in's documentation and description that the new plug-in should be used in conjunction with it.
The BuildAssembler configuration files in any custom presentation styles will need to be updated by replacing any references to {@SHFBFolder}Data\{@TargetFrameworkIdentifier} with {@FrameworkReflectionDataFolder}. This will allow them to find the reflection data files.
Documentation:
The Sandcastle Tools help file has been removed. All of its former content has been merged into this help file. Additional topics have been added to document the underlying Sandcastle tools.
Help File Builder
Fixed the HelpLibraryManagerLauncher tool so that it adds the default catalog name to the command line arguments if one is not explicitly specified.
Merged changes from Sam Harwell to correct issues with the extended XML comment element auto-completion in Visual Studio 2015.
Removed loading of the reflection information file in the build engine and replaced it with XML stream axis methods which greatly reduces memory usage in the build engine for large builds.
Reworked how the default topic was determined. This corrects an issue that caused it to not determine the default topic and fail the build under certain conditions.
Moved clearing the prior web/markdown content to the start of the build where the other format output is deleted. This allows other output generated by the build such as IntelliSense comments files to be placed in the output folder without being lost when the web/markdown content is generated.
Moved the Help File Version property to the Help File property page. It does not have to be in the form of a version number anymore.
Added a new Visibility category option to support documenting public compiler generated types and members. Private, internal, and protected compiler generated members are always excluded as before.
Modified the build engine so that it utilizes the new reflection data set dictionary to find and load information about the available frameworks. This effectively allows framework information to be treated like any other project-specific component. See the Reflection Data Manager Tool topic for more information on generating framework reflection data.
Added separate NuGet reflection data packages for each of the framework types. This works around the NuGet package size limitation and allows you to install the core help file builder NuGet package and only the reflection data for the frameworks that you actually need. See the XCOPY/NuGet Build Server Deployment topic for more information.
Sandcastle Tools:
Fixed a case in the AddNamespaceGroups tool where it would not always create groups correctly under certain conditions (submitted by dgedge33).
Fixed the extension method parameter comparisons in the MRefBuilder extension method add-in so that it does not add extension methods to types with matching method signatures.
Fixed the API filter in MRefBuilder so that an internal type in one assembly does not hide a public type of the same name in another assembly if the internal one is seen first.
Fixed MRefBuilder so that internal interfaces are not listed on types that implement them.
Fixed VersionBuilder so that when the rip option is enabled, it correctly removes extension methods when they no longer appear in the latest release.
Added support for including public compiler generated types and members in the MRefBuilder visibility options.
Added the Reflection Data Manager tool which is now used to define reflection data set files and build the reflection data for the various frameworks.
Added support for running SegregateByAssembly as an MSBuild task.
Presentation Styles:
Fixed the keyword lookup script in the VS2013 presentation style so that it initializes the word dictionary object correctly to prevent keywords being interpreted as property names (i.e. "length").
Fixed the VS2013 presentation style so that the content does not go under the vertical scrollbar in the Help 1 and MS Help Viewer formats.
Merged a change from Drew Gross that closes an XSS vulnerability in the legacy website script used by the VS2010 presentation style.
Added the missing CodeExample.png image to the Open XML presentation style.
Added an includeEnumValues transformation argument to all presentation styles. If set to true, the default, a column for the numeric value of each field is included in enumerated type topics. If set to false, the numeric value column is excluded.
Updated the order of the sections on the member list pages in all presentation styles to more closely match the order on MSDN. Also updated the table of contents transformation to order the type subtopics so that they're consistent with the order in the member list pages.

New in Sandcastle Help File Builder 2015.5.2.0 (May 4, 2015)

New in Sandcastle Help File Builder 2015.1.12.0 (Jan 13, 2015)

New in Sandcastle Help File Builder 2014.12.20.0 (Dec 22, 2014)

New in Sandcastle Help File Builder 2014.2.15.0 Beta (Feb 19, 2014)

New in Sandcastle Help File Builder 1.9.8.0 (Oct 17, 2013)

Changes made in this release:
Sandcastle:
Moved the MemberName and HashedMemberName naming method code into a new AddFilenames.xsl transformation file along with the GUID naming method code.
Deleted AddGuidFilenames.xls and AddFriendlyFilenames.xsl transformations as their functionality is now handled by AddFilenames.xsl.
Breaking Change: The MemberName naming method differs from the old Sandcastle "friendly names" method. This brings it in line with the SHFB has always worked. It will only affect people that used to Sandcastle tools directly and only then if they relied on direct links to the previously generated names. Use the transformation argument /arg:namingMethod=MemberName or /arg:namingMethod=HashedMemberName to use the new naming methods. The default if not specified is Guid.
Applied a patch from gfraiteur to remove the GUID topic ID requirement in ResolveConceptualLinksComponent. Bear in mind that GUIDs are still preferred as they are guaranteed to be unique which is important for Help 2 and MS Help Viewer content which are merged into a collection. Duplicate IDs across multiple sets of content would cause linking issues in the collections.
Added changes from Stazzz to the Version Builder tool to merge information about additional extension methods even when the type and method are defined in different assemblies.
Added support for the .NETFramework 4.5.1, .NETCore 4.5.1, and .NETPortable 4.6 frameworks.
Sandcastle Help File Builder:
Fixed the determination of the default topic so that it searches for a file in nested topics when the parent topic is an empty container node.
Fixed documentation source project file handling so that it favors the TargetName property over the AssemblyName property so that it works with C++ projects that have a different assembly name from the project filename.
Fixed documentation source project file handling to account for the GenerateProjectSpecificOutputFolder property being set to true which modifies how the OutDir property is set for the build.
Fixed the Assembly Binding Redirection plug-in so that it fully qualifies redirection configuration filenames when written to MRefBuilder.config.
Fixed the Additional Reference Links and Version Builder plug-ins so that they correctly clone the subprojects to avoid modifying the underlying MSBuild project which may be loaded in Visual Studio. This prevents the changes they make to the subprojects from propagating to the Visual Studio copy.
Adjusted how child processes are killed when a build is aborted to try and prevent killing unrelated processes from a separate, concurrent build.
Enabled window selection commands for use during a build in the standalone GUI. Also enabled switching between project property categories in the Properties window during a build to allow seeing what values are in effect.
Removed the ModifyHelpTopicFilenames build step as naming is now handled entirely by the new AddFilenames.xsl file in Sandcastle.

New in Sandcastle Help File Builder 1.9.2.0 (Mar 2, 2011)

New in Sandcastle Help File Builder 1.8.0.2 Beta (Sep 3, 2009)