Version 1.9.7.0 was released on April 7th, 2013.
With changes to the core Sandcastle build components, the following cached build components have been rendered obsolete and must be removed from your projects if you are using them:
Cached Framework Comments Index Data
Cached Reflection Index Data
Cached MSDN URL References
Disk-based caching of MSDN content IDs has been built into the core Sandcastle build component and is enabled by default in all help file builder projects. Changes made to enable namespace filtering and loading data in parallel made loading the index data from a serialized cache file slightly less efficient than just indexing the required data files in each build. As such, reflection and comments index data is no longer cached to disk for re-use. Common data is also shared across multiple instances of the build components when possible to significantly reduce the amount of memory required by BuildAssembler when building multiple help file formats.
To further help with memory constraints in very large projects, new caching build components have been added to store reference link target, MSDN content ID, reflection index, and XML comments index data in either an ESENT or a SQL Server database. These help save memory at the expense of some build time. In extreme cases, project data can also be indexed and cached in a database thus freeing up more memory to the topic build process.
The IntelliSense Component and its configuration dialog, the MS Help Attributes Component, and the Show Missing Documentation Component and its resource items have been moved into the Sandcastle Build Components assembly. If you are using the IntelliSense Component in your project, you must delete and re-add it in order to get the latest configuration containing the proper assembly reference. The other two components are handled by the help file builder and no action is required.
Added the SupportsConfiguration property to the IPlugIn interface. This is used to indicate whether or not the plug-in supports configuration when added to the project. If you have developed your own custom plug-ins for the help file builder, you will need to add this property to your plug-ins.
Fixed a bug in the removal of inherited members so that it only removes members of classes matching the parent class and not those of other classes starting with the same name.
Fixed a bug that caused the plug-in and components property pages to not pass a project reference to the component configuration dialogs.
Fixed a bug in the Output window that could cause it to crash under certain circumstances when the standalone GUI was closed.
Fixed a bug in the Topic Previewer window that prevented multiple tokens from being rendered properly when they appeared in the Related Topics section.
Fixed the BuildAssembler configuration template files so that they use the HtmlEncVendorName tag to properly encode vendor names containing restricted characters.
Fixed the standalone GUI so that the property pages contain proper default values for new projects and for properties not present in existing projects when they are loaded. This matches the behavior of the property pages in Visual Studio.
Fixed the Solution Explorer context menu items in the VSPackage so that they are hidden when a SHFB project is unloaded in Visual Studio.
Fixed an odd bug in the MPF project related to adding new items to deeply nested collapsed nodes.
Fixed the presentation style configuration files so that family data is copied in as part of the container data so that the ASP.NET and XAML syntax writers include or exclude syntax sections correctly.
Merged the changes from the MPF 2012 project's code base into the help file builder's copy of the MPF 2010 project. These changes let the project system handle the multi-threaded parts of VS 2012 without causing crashes (i.e. opening the VS 2012 Test Explorer window with a SHFB project loaded). The code is compatible with VS 2010 so one version of the package will still work in both versions of Visual Studio.
Added a check to abort the build if HtmlHelpName contains a period and MS Help Viewer output is being generated. Microsoft Help Viewer does not support periods in the base filename.
Added code to the build engine to adjust the search location for the assembly and XML comments file if the GenerateProjectSpecificOutputFolder MSBuild variable is set to true.
Modified the build engine to get a list of all possible namespaces referenced by the project. This list is passed to the reference link and copy from index build components to reduce the amount of information they have to load. This reduces memory usage and provides a small reduction in the build time.
Reworked how the Help 1 and website keyword index files were generated by the HTML extract tool to provide qualified class names in the titles of common entries (i.e. operators).
Updated the HTML extract tool to process the files in parallel to improve performance.
Applied changes from the related comments indexing classes in BuildAssembler to the comments indexing classes in SandcastleUtils to improve their performance when used by the Entity References window and the GenerateInheritedDocs tool.
Updated the Additional Reference Links Plug-In to set the Configuration and Platform properties on the reference projects. It was also updated to add the additional reflection information files to the GenerateInheritedDocs tool's configuration file.
Updated the GenerateInheritedDocs tool to support loading multiple reflection information files. This allows additional reflection information to be included for undocumented reference assemblies and enables inheriting documentation from members within them.
Added code colorization support to the code blocks rendered in the topic previewer. This helps identify problems with the code such as incorrect comment markers or incorrect language IDs. A Copy link was also added to allow copying the code blocks in the topic previewer to the clipboard. Line numbering is supported but collapsible sections are not.
If they support configuration, build components and plug-ins will now automatically show their configuration dialog when first added to a project. This prevents builds from failing due to missing configuration data in newly added components.
Added the CopyContentFrom member to the ConceptualContentSettings class to allow plug-ins to add content from a temporary project for inclusion in the current build. This prevents the temporary items from getting added to the project being built which is not wanted.
Added the Windows Phone 8.0 framework to the framework definition file.
Reworked the BuildAssembler execution process to allow for parallel execution of component code. Components are still initialized and topics built sequentially for the time being but parallelism can be utilized now and is used in certain components when they are initialized.
Reworked the BuildAssembler message logger to allow for parallel execution of component code without contention for the console when logging messages.
Added a warning count to BuildAssembler which is displayed at the end of the build.
Note
A number of these are breaking changes. However, most people will be unaffected unless they have created custom build components or syntax generators. These changes were necessary in order to make the API more accessible and to make it easier to derive build components from existing ones without having to re-implement a lot of the internal supporting classes.
Deleted CodeReference, LiveExampleComponent, and WdxResolveConceptualLinksComponent as they appear to be for internal Microsoft use and do not appear to have much use for non-Microsoft users.
Deleted the classes in the BuildComponents namespace from the BuildComponents project as they were unused. These were replaced by the like-named classes in the Microsoft.Ddue.Tools namespace.
Deleted IntellisenseComponent2 and replaced IntellisenseComponent with the version from the Sandcastle Help File Builder. Added the IntelliSenseComponent configuration dialog which can be used by front end tools such as the Sandcastle Help File Builder to edit the component's configuration.
Moved InheritDocumentationComponent into the main BuildComponents project and deleted the CopyComponents assembly as it was the only one in it.
Moved the syntax writer classes into the SyntaxComponents assembly with their related classes.
Moved all of the snippet related classes into their own namespace.
Moved all of the target related classes into their own namespace.
The reference link target classes were moved into their own assembly (BuildComponents.Targets.dll). This assembly is versioned independently of the other Sandcastle assemblies so that reference target caches do not have to be rebuilt with each new release of the Sandcastle tools.
Moved all of the command related classes into their own namespace.
Made all of the supporting classes public.
Made all reference link target classes serializable.
Cleaned up and refactored the code where necessary in almost all of build components.
Added a new CopyCommand abstract base class in BuildAssembler to make creating new copy commands possible.
Added a new IndexedCache abstract base class for use by the CopyFromIndexComponent and its subcomponents for the index data. This also allows derived components to implement alternate caching mechanisms.
Made TargetDictionary an abstract base class and added InMemoryTargetDictionary as the basic implementation. This allows alternate implementations that use a different storage mechanism for the target data.
Reimplemented how reference link targets are loaded and stored. This allows for sharing target data independent of link type across multiple instances of ResolveReferenceLinksComponent2 reducing memory requirements and initialization time when building multiple output formats. The new implementation also allows caching of the information.
Reworked the target dictionaries to allow for loading of target information in parallel to speed initialization up a bit.
Renamed the IndexedDocumentCache to InMemoryIndexedCache and reworked it to support filtering by namespace to reduce the amount of reflection data that it needs to load and also added support for loading the index files in parallel.
In CopyFromIndexComponent, added a virtual method to create the index caches, added code to dispose of them when done, and exposed the context via a protected property.
Added a Dispose method to CloneComponent to properly dispose of all components in each branch.
Simplified the FileCreatedEventArgs and updated the HxFGeneraterComponent to make it responsible for figuring out where to put its files.
Added support for MSDN content ID caching to the ResolveReferenceLinksComponent2. The implementation allows derived classes to utilize backing stores other than the serialized binary file used by default as long as the cache type implements IDictionary<string, string>. It also allows sharing the cache across multiple instances of the component.
Regenerated the MTPS Content Service classes. A decision was made to stay with the web service as the authentication issues have well-known solutions (see BuildAssembler.exe.config). Switching to a service type may introduce other authentication issues and since the web service works well enough, it was left as-is.
Added support for defining which namespace targets to load in ResolveReferenceLinksComponent2. This prevents loading unnecessary namespaces saving some memory and initialization time.
ReferenceLinkComponent2 and CopyFromIndexComponent now report cache usage at the end of the build with diagnostic messages. These can be used to help tune the cache sizes if necessary especially in derived caching components.
Added support for a renderReferenceLinks attribute to the SyntaxComponent configuration's syntax element. By default the syntax component will not render links to types in the syntax section (this is not supported anymore by MS Help Viewer 2.0). By adding this attribute to the configuration and setting it to true, you can turn them back on again if wanted.
Added a condition to the SyntaxComponent's Apply method to skip group, project, and namespace pages in which a syntax section is of no use. This allows removal of the IfThenComponent wrapper around it in the configuration files which wasn't using an up-to-date condition anyway.
Updated the Visual Basic and Visual Basic Usage syntax generators to omit the line continuation character by default. It can be enabled by adding the includeLineContinuation attribute to the generator element and setting it to true.
Removed the use of RegexOptions.Compiled in ExampleComponent which greatly improves its overall performance. The significant time and increased memory penalties outweighed any performance benefits over the course of the build.
Updated DisplayComponent to output the content as a diagnostic message using the WriteMessage method rather than just dumping it to the console.
Updated ValidateComponent to include the key in its warning messages.
Moved the MSHelpAttrComponent and ShowMissingComponent from the Sandcastle Help File Builder into the Sandcastle BuildComponents project.
Fixed up various issues in the BuildAssembler projects found by FxCop (too many to list).
Changed the title element in the presentation styles so that it shows the qualified member name. This is required to provide unique titles for index entries. This does have the side-effect of causing member titles in the MS Help Viewer TOC to be qualified with the class name as Help Viewer no longer supports a TOCTitle metadata attribute like Help 2 did. Help for base framework classes exhibits the same behavior so this appears to be by design.
Fixed the VS2010 style so that links work properly in Help 2.
Fixed VS2010\Branding\ps-body.xslt so that it doesn't add a "./" relative URL prefix to non-relative image URLs.
Commented out the templates in VS2010\Branding\ps-body.xslt that were stripping style attributes. These appear to be for use with non-self-branded content which doesn't apply anymore. Allowing the style attributes through fixes the problem of the nobullet list style not working.
Updated all presentation styles so that fields, properties, events, and methods include a return type link even if no returns or value XML comments element is present. This makes it consistent with MSDN and allows for the removal of the type links within the Syntax section itself as the type links for the return value and parameter values are available elsewhere on the page.
Deleted the unused reference and schema build configuration and XSL transformation files from all presentation styles.
Removed the duplicate items from shared_content_mshc.xml leaving only the overridden path elements. The MS Help Viewer configuration files where updated to include the shared_content.xml file ahead of it.
Updated the example and presentation style configuration files to reference InheritDocumentationComponent in the BuildComponents assembly.
Added the ShowMissingComponent resource items to the reference_content.xml file in each presentation style.
Added support for the markup element in main_sandcastle.xsl in each presentation style. This allows a block of HTML or other elements such as include to pass through as-is to the topic. This allows build components to insert content before the TransformComponent runs and prevents it being removed as unrecognized content by the XSL transformations. The conceptual transformations already allow this so this makes the conceptual and reference builds consistent in supporting a markup element.