Release notes for version 2019.3.29.0.
The following reflection data sets are no longer deployed with the Sandcastle Help File Builder and no longer appear as an option in the Framework Version project property. However, if you need them, these data sets are still available via NuGet packages. If you need to install one of the packages:
Add the package to one of the documentation source projects so that it is available in the .\packages folder. Set the help file builder project's Component Path property to the package folder and it will locate the additional reflection data set files. If needed, force a package restore to ensure it is present.
Download the package from the link below and extract the content to a subfolder in the build components folder. You will need to create the components folder if it has not been used before. Components placed here are available automatically to all help file builder projects.
Another option is to extract the package content to a subfolder within the help file builder project folder. Components placed in a project subfolder are available to that project but no others.
Whichever option you choose, you may need to close and reopen the project properties window to see them as a framework version option after they are installed.
Options removed (download the NuGet packages here: EWSoftware NuGet Packages):
EWSoftware.SHFB.NETMicroFramework
.NET Micro Framework versions 4.2, 4.3, and 4.4
EWSoftware.SHFB.NETCore
.NET for Windows Store Apps
.NET for Windows Store Apps (8.1)
EWSoftware.SHFB.NETPortable
.NET Portable Library versions 4.0 (Legacy), 4.5, 4.6, 5.0, and 5.0 (NuGet)
EWSoftware.SHFB.Silverlight
Silverlight versions 3.0, 4.0, and 5.0
EWSoftware.SHFB.UniversalWindows
.NET for Universal Windows
.NET for Universal Windows (NuGet)
EWSoftware.SHFB.WindowsPhone
.NET for Windows Phone
.NET for Windows Phone Silverlight (8.1)
EWSoftware.SHFB.WindowsPhoneApp
.NET for Windows Phone Store Apps (8.1)
EWSoftware.SHFB.NETFramework
To reduce clutter, the following .NET Framework versions have been removed but are available in this package along with the version options noted below: 1.0, 1.1, 2.0, 3.0, 3.5, 4.0 Platform Update 1 (KB2478063), 4.5, 4.5.1, 4.6, 4.6.1, 4.7, 4.7.1.
.NET Framework versions 4.0, 4.5.2, 4.6.2, 4.7.2, and 4.8 are still available as framework version options by default. As noted above, the removed options are still available in the NuGet package if needed. This may not be necessary as the older options will redirect to the nearest available option and you should not see any difference.
Important
The Cross-platform (.NET Core/.NET Standard) option is still included with the help file builder and the .NET Framework NuGet package. However, you should consider this option deprecated and use the new .NET Core/.NET Standard/.NET 5.0+ option instead as it will handle the current .NET Core and .NET Standard versions as well as .NET 5.0 and later. It also contains a proper set of reflection data so that inherited framework member information will be accurate.
Added support for reading portable PDB files in MRefBuilder so that source context information is available for .NETCore/.NETStandard assemblies that use that format for their PDB files.
Fixed MRefBuilder so that it writes out a new defaultValue element rather than a nullValue element for value type parameters (structures) with a null default value assigned (e.g. public Task ConnectAsync(CancellationToken cancellationToken = default)).
Updated the syntax writers to handle the new defaultValue element. Note that this may be a breaking change for custom syntax writers if their language supports the default keyword on parameters as they will not recognize the new element and will ignore it in cases like the example above resulting in a blank to the right of the equals sign.
Updated the C# and Visual Basic syntax writers to use the nullable type syntax rather than the full nullable type name for nullable types (e.g. double? rather than Nullable<double>).
Added support to MRefBuilder to generate nullable state attributes on types to indicate nullable reference types. The syntax writer for C# was updated to generate nullable reference types when generating the syntax section (e.g. public string? FindSomething(IEnumerable<string?>, IEqualityComparer<string?>? keyComparer = null).
If you have custom syntax writers for languages that also support nullable reference types you will need to update them by handling the new nullable attribute on the type element when rendering type references.
Added the value element to the IntelliSense build component as it is now shown in the quick info in Visual Studio 2019 16.6 and later.
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 2019), 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.
Fixed a duplicate ID issue with collapsible regions in colorized code.
Updated JQuery in the VS2013 presentation style to version 3.5.1.
Updated all anchor links generated by the presentation styles and tools to include a rel="noopener noreferrer" attribute to prevent reverse tabnapping
Corrected the casing of the listheader element in the list XML comments example in the XML comments guide.