Release notes for version 2014.1.26.0 Beta
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. Although combined, the Sandcastle tools can still be used independently of the help file builder as in prior releases.
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.
Presentation styles are now implemented as MEF components as well. As with the other build components, this allows for the same dynamic discoverability at runtime and project-specific presentation styles.
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 BuildAssembler 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 example SandcastleGUI project since it is out of date and serves no real purpose anymore. Use the Sandcastle Help File Builder standalone GUI or Visual Studio Package instead if you need a project management system.
Removed the Examples folder since they were out of date and cannot be built properly from the installed location. I will create better standalone build examples and distribute them separately so that they can be downloaded and built from a usable location at a later date.
Updated several of the tools to allow running them as MSBuild tasks and removed the PowerShell scripts. They were out of date and I know very little about PowerShell so support for them would be problematic. In any event, since the tools have been updated to run as MSBuild tasks, it makes better sense to standardize on MSBuild projects rather than PowerShell scripts.
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.
Fixed a bug in the SegregateByNamespace tool so that it does not fail for namespaces containing characters that are not legal in a filename.
Added conditions to the two document model transformations to favor AssemblyInformationalVersionAttribute if present for the version information. If not, the existing behavior is used (AssemblyVersionAttribute plus AssemblyFileVersionAttribute value if present). It was also marked as a required attribute in the MRefBuilder configuration files.
Added the AddNamespaceGroups tool which adds namespace groups to the reflection information file. The grouping information is used to implement the namespace grouping option in the document model transformations and presentation styles.
Deleted several unused transformations from the production transforms folder.
Added a workaround to allow documenting the compiler generated public types in WINMD assemblies that actually represent user code.
Fixed a couple of bugs in MRefBuilder found while regenerating the reflection data using the .NETFramework 4.5.1 assemblies and testing it with the .NETCore 4.6 assemblies.
Removed the protectedSealed and noPIA configuration elements from MRefBuilder.config.
Added the visibility element to MRefBuilder.config to control API member visibility in the output. The options it contains are equivalent to the Sandcastle Help File Builder options of the same name and are now handled by MRefBuilder.
Deprecated support for the /internal MRefBuilder command line option. The new visibility configuration element provides finer grained control over member visibility in the output.
Added code to output the interop metadata so that the syntax components can add the interop attributes to the declarations (ComImport, StructLayout, FieldOffset, PreserveSig, and DllImport).
Fixed BrandingComponent so that it applies the language specific text fix-up on elements in syntax sections which the branding transformations miss for some reason. This was only noticeable on members and properties that return a nested type and resulted in multiple separators between the parts of the qualified type name.
Applied a patch to ResolveReferenceLinksComponent from Stazzz to write out nested XML elements within the link's inner XML.
Updated IntelliSenseComponent to export code contracts XML comments elements (requires, ensures, ensuresOnThrow, pure, invariant, getter, and setter).
Added code to the syntax components to output the interop attributes to the declarations based on the metadata (ComImport, StructLayout, FieldOffset, PreserveSig, and DllImport).
Deleted ScriptSharpSyntaxGenerator. The JavaScript syntax generator has been used in its place for quite some time.
The SyntaxComponent is now exposed as a configurable component. It allows you to enable rendering of reference links in the syntax section and to edit the configuration of those syntax generators that support it such as the Visual Basic and Visual Basic Usage syntax generators.
Added namespace grouping support to the VS2005 and VS2010 presentation styles. When enabled, it mimics the nested layout of the namespaces on MSDN that have a common root.
Fixed the tab border and footer background image handling in the VS2010 style so that they work in all output formats.
Fixed branding.js in VS2010 so that the proper tab is selected when switching topics in website output.
Removed dev10.mshc and extracted the content into the .\branding folder. The configuration files reference it from there now.
Removed the external link icon from all external links in the VS2010 style.
Fixed the incorrect devlang and null keywords for F# in the VS2010 style.
Removed the label attribute from the language element passed to the XSL Transform Component in the languages parameter as it is not needed now.
Merged the Sandcastle Help File Builder shared content into each presentation style so that they are self-contained.
Moved the stop word lists from the Sandcastle Help File Builder into the Shared\StopWordList folder in the presentation style project so that all localizable resources are kept together in one project.
Simplified the naming of the help file builder shared content files and stop word lists to be just the language that they represent.
Added a boilerplate threadsafety condition to all presentation styles used when the threadsafety XML comments element is used without any options.
Added async, await, let!, async/await, and async/let! as langword options on the see XML comments element in the VS2005 and VS2010 styles.
Updated the BuildAssembler configuration files to propagate the preliminary XML comments element from types to all of their members. This marks all members of the type as preliminary without having to add the element to each member's comments.
Added the maxVersionParts transformation argument to the VS2005 and VS2010 presentation styles. This is used to specify the maximum number of assembly version parts to show in API member topics. Set it to 2, 3, or 4 to limit it to 2, 3, or 4 parts or leave it blank for all parts including the assembly file version value if specified.