Version, April 2013

Sandcastle Tools

Collapse image Expand Image Copy image CopyHover image

[This is preliminary documentation and is subject to change.]

Version was released on April 7th, 2013.

MRefBuilder Tools

Added the Windows Phone 8.0 framework to the framework definition file.

BuildAssembler Tools

  • Reworked the BuildAssembler execution process to allow for parallel executon 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 executon 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.

Build Components


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 reimplement 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).

Presentation Styles

  • 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.

See Also

Other Resources