Important
Be sure to move your logo image file to an .\Icons subfolder in your project and set its BuildAction to Content so that it is included properly. See the transform component argument descriptions for more information.
Sandcastle Help File Builder Documentation
Version 1.9.6.0
Version 1.9.6.0 was released on December 16th, 2012.
Breaking Changes
The configuration of the Code Block Component has been changed. As such, if you have added it to your projects to override the default configuration, you must remove it, add it again, and reconfigure it so that the configuration elements are up to date.
Moved the various parts of the Post-Transform Component processing into the presentation style XSL transformations and the Code Block Component. The Post-Transform Component is now obsolete and, if you have added it to your project, it must be removed. Make a note of the configuration settings for the logo option if you are using it and transfer those values to the new transform component arguments on the Transform Component Arguments property page.
If you have created your own presentation style, it will no longer be picked up by the presentation style property. You will need to create a definition file for it. This was necessary to break the dependencies the help file builder had on the existing presentation styles and their names. See the Creating a Presentation Style Component topic and the related walkthrough on creating a custom presentation style for more information.
The FindingTools build step was removed and its processing was moved to be part of the Initializing build step due to the need to locate framework and presentation style configuration files during initialization. If you have custom plug-ins that rely on the removed build step, you will need to update them accordingly.
Help File Builder
Fixed the SandcastleProject class so that it reuses existing MSBuild project instances if the project being loaded is already in the global collection. This prevents it from trying to unload a shared instance owned by MSBuild when disposed.
Fixed issues with invalid characters in the vendor name project property.
Fixed the MAML to Flow Document Converter so that it no longer locks image files that it adds to the preview documents which was preventing them from being updated in the project.
Fixed the XML comments file search so that the local system language does not override the language defined in the project when searching for localized versions of the .NET Framework XML comments files.
Fixed up comment colorizer rules for VB.NET, VBScript, and Python so that they do not add an extra line after end of line comments.
Fixed the Code Block Component so that it doesn't match shorter region names in longer ones that start with the shorter name that occur before it.
Fixed the IntelliSense Component so that it uses a case-insensitive comparer for the assembly names in the writer dictionary to prevent it from trying to create the same file twice when the names differ only by case.
Fixed the Topic Previewer and Entity References windows so that they retain the help file builder project reference when a non-help file builder project is selected in the same solution.
Updated the Help 2 build task to suppress all informational warnings and updated the MS Help Viewer build task to reduce the number of informational messages it produces. This significantly reduces both build time and log file size for projects with a large number of topics.
Updated the Code Block Component to convert the lang attribute to language so that the XSL transformations work as expected (they use language throughout to determine the language).
Moved the code element's title attribute handling to the presentation styles and greatly simplified the Code Block Component code which allows it to work without any knowledge of the document structure for any given presentation style.
Updated all build components to include the topic key in warning and error messages when available. This provides more context when the BuildAssembler verbosity level is set to Warnings and Errors or Errors Only.
Updated the build process so that it handles substitution tags in the HtmlHelpName property value. This allows insertion of other property values such as HelpFileVersion into the help filename value.
Removed the Version Information Component as the version number information is now included by the presentation style XSL transformations.
Removed the BrandingPackageName and SelfBranded project properties. Sandcastle presentation styles are either self-branded or not and cannot switch between the two states so exposing these properties no longer made sense.
Added support for .winmd documentation sources. I'm not sure if this was worthwhile as a majority of the user written code in the assembly is marked as compiler generated and thus does not show up in the help file. I may need an option to include compiler generated code. We'll see how the feature is used and if it is an issue.
Rewrote the standalone GUI's Project Properties window to use the property page user controls from the Visual Studio Package. This makes the property descriptions and usage consistent between the two.
Added the StandardStyles.presentation configuration file which defines the standard Sandcastle presentation styles available for use. Support for 3rd party presentation styles is also available. See the Creating a Presentation Style Component topic for more information.
Updated the build engine and project management tools to use the presentation style configuration files (standard and custom) for all presentation style related settings. The build engine no longer has any internal dependencies on the presentation styles or their names which will make adding new presentation styles much easier.
Added a new TransformComponentArguments property to the project along with a corresponding property page. This allows editing the TransformComponent arguments defined in the presentation style configuration file (i.e. for logo support).
Added support for the ignoreIfUnresolved element in the Assembly Binding Redirection plug-in.
The Topic Previewer Window now supports the display of imported code blocks.
Added the HTML Encode Selected Text command to the Visual Studio text editor's context menu when editing HTML, MAML topics, and other XML files. This allows you to HTML encode the selected text rather than doing it by hand.
Added support for the conceptualLink XML comments TOC entry format in the Entity References tool window.
Changed the default for the BuildAssembler Verbosity project property from All Messages to Only Warnings and Errors.
Reduced the build log output when copying website files from all file names to just a file count as it progresses to reduce the volume of output on large help files.
MRefBuilder Tool
Fixed MRefBuilder so that it does not exclude System.Xml and System.Data from the framework assembly cache.
Updated the Frameworks.xml file to reference the December 2011 Silverlight Toolkit for Silverlight 5 rather than the older April 2010 version for Silverlight 4.
Merged changes from ComponentOne that prevent additional cases that cause a crash when documenting obfuscated assemblies.
BuildAssembler Tool and Components
Added support for topic key and message parameters in the message logging methods in BuildAssembler.
Updated all build components to include the topic key in warning and error messages when available.
Updated TransformComponent to raise a ComponentEvent with a TransformedTopicEventArgs parameter that contains the topic key and the transformed topic document. This allows components that ran earlier in the stack to perform tasks after the topic has been converted to HTML. This eliminates the need for a post-transform component as the component that ran earlier can handle the post-transform processing itself.
Production Transforms
Updated CreatePrototypeToc.xsl with a rootNamespaceContainer parameter that can be set to true to have it generate a root namespace container node like the transformation for the other presentation styles.
Updated ApplyVSDocModel.xsl and ApplyPrototypeDocModel.xsl to include assembly version number information in the API member data.
Presentation Styles
Fixed up the casing on the scripts\ and styles\ folder references so that they are all consistent and will not cause casing issues on UNIX based web servers.
Fixed VS2005 CommonUtilities.js so that the <see langword="XXX" /> elements work properly. The prior Help Viewer 2.0 fix broke their handling in the other help formats.
Moved Shared\Content\syntax_content.xml and the files in Shared\Transforms\ into each of the presentation styles so that they are all self-contained. This will make cloning a presentation style to customize it easier. There was already a significant amount of duplication anyway so merging the few files that were shared does not make much difference in terms of maintenance.
Removed the unused files in Shared\Scripts.
Updated all presentation styles to include assembly version number information in the API topics.
Updated all presentation styles to handle the title attribute on code elements.
Added a condition to hide the language selector in the Prototype presentation style if there is only one language.
Fixed handling of the preliminary XML comment element in all presentation styles so that it renders the content if specified.
Added a transformation template in all presentation styles to get the code language so that it is consistent in all places that need it for the language filter.
Added logo support to all presentation style XSL transformations. The VS2010 style now supports all of the logo placement options to match the other styles.
Updated the XSL transformations so that they do not output an empty Abstract Help 2 metadata element for certain cases such as when it only contains a non-breaking space character.
Merged changes from ComponentOne into the VS2005 style to prevent the unnecessary borders on the page headers in MS Help Viewer 1.0.
Added support for the event XML comments element in all presentation styles. This was a custom element implemented by NDoc that never made it into Sandcastle. It renders a section called Events containing a table listing events that can be raised by the method and a description for how the event can be raised.
Extras
Added MAML snippet definitions for the common block and inline elements and a related page to the guided installer to copy them to the local snippets cache for the various Visual Studio versions.
Updated the Sandcastle MAML guide to remove references to the Sandcastle Help File Builder components and features that have been moved into the Sandcastle build components and presentation style XSL transformations.
Started to document the Sandcastle tools by adding this help file. The content and images in the general information and architecture topics was originally created by Dave Sexton as part of the wiki content on the Sandcastle Styles project site on CodePlex.
As of this release, it is still a work in progress. More information on the various tools and components will be added as time permits.
Added the Sandcastle XML Comments Guide help file to provide a comprehensive set of documentation on the XML comments elements and how they are used with Sandcastle.