Version 1.8.0.1 (Beta 1)

Version 1.8.0.1 was released on February 4th, 2009.

• Breaking Changes
• Other Changes in This Release

• All projects and components are now built using the .NET Framework 3.5 SP1. As such, you must have the .NET Framework 3.5 SP1 installed to use the help file builder and components. It can still build help files for any framework version from .NET 1.1 to .NET 3.5.

• When a custom build component was added to the project in prior releases, attributes from the component node other than the ID, type, and assembly were not included in the project's copy of the configuration. This problem has been corrected. The only component affected by this fix is the Cached MSDN URL References component. If you use it in your projects, you should delete it and re-add it in the ComponentConfigurations project property so that it picks up the locale and link target attributes in order to use the appropriate settings for them during a build.

• The IDs on the HierarchicalTocPlugIn and the TocExcludePlugIn changed. You will need to delete them from the PlugInConfigurations project property and add them back in to pick up the new IDs.

• The location of user-defined template files and build component cache files has changed. They are now stored in the Local Application Data folder rather than the Common Application Data folder. However, the custom build components and plug-ins will themselves still reside in the Common Application Data folder. You should remove and add the three cached build components to the project file so that they use the new location. Any existing cache files can be moved to the new local data folder. This change was made to avoid problems with security and clashes with modified template and cache files when multiple people use the same PC. See the Special Folder Locations topic for more information.

• Relative hint paths on reference items are now converted to full paths at build time so that they are located correctly.

• Added ExtensionAttribute to the MRefBuilder attribute filter and excluded it from the DocumentAttributes property processing so that extension methods are documented correctly.

• Fixed a bug in the Help 1 build project template that caused it to use the table of contents definition file for the index.

• Fixed a bug that caused the Output Deployment plug-in to fail if a folder did not already exist when deploying to a file path.

• Added " " (space), "*", and "?" to the characters replaced with an underscore by the MemberName naming method code to prevent save failures when the help topics are saved.

• Paths to the comments files in sandcastle.config are now expanded fully before being written to it to prevent issues with environment variables expanding differently when the build engine runs as a 32-bit MSBuild process but the build step project runs as a 64-bit MSBuild process.

• Added code to turn off the read-only attribute on MAML topics when they are copied to the working folder.

• Added code to the Post-Transform Component so that see tags within code blocks are converted to links when the Code Block Component's keepSeeTags option is used. A prior release broke it due to changes needed to get the components to colorize code in conceptual builds. Note that the referenced target names must be fully qualified in order to get resolved.

• Fixed a bug in the Show Missing Documentation component that caused it to fail if an auto-documented constructor's signature contained unencoded special XML characters.

• If the DocumentSealedProtected property is set to False, it now removes inherited protected members too.

• Added the ShowMissingIncludeTargets project property. This is used to add a "missing" message if an <include> tag is found in the comments for a topic indicating a missing file or invalid XPath query. However, it's really only useful for C# generated XML comments files (don't ask).

• Added the UserDefinedProperties project property to the Build category. This allows you to add or edit user-defined MSBuild project properties that can be used to hold additional information or for use in substitution tags within other help file builder project properties.

• Added support for CustomBeforeSHFBTargets and CustomAfterSHFBTargets properties that can define custom projects containing property or target overrides imported and evaluated before and after the help file builder targets respectively. These can be defined on the command line to import the custom targets and property overrides.

• Substitution tag replacement (i.e. {@PropName}) now includes support for using any property name defined in the project. This includes user-defined MSBuild properties not recognized as help file builder properties and all global properties defined in the MSBuild build engine (reserved properties, environment variables, etc.).

• The HelpFileVersion project property is now a string value. This allows you to specify user-defined MSBuild project properties to define the value (i.e. {@Version} or {@Major}.{@Minor}.{@Build}.{@Revision}). The end result must still evaluate to a valid four-part version number. If not, a build error will occur (BE0066).

• Added an optional execution priority value to the ExecutionPoint object so that plug-ins can set an execution priority for each build step. It is used to determine the order in which the plug-ins will be executed. Those with a higher priority value will be executed before those with a lower value. Those with an identical priority may be executed in any order within their group. If not explicitly defined, the default priority value is 1000.

• Added the SandcastleBuilder.MRefBuilder assembly which contains the BindingRedirectResolver component used by the Assembly Binding Redirection plug-in. The resolver component can be used in other third-party tools and standalone build scripts.

• Added the Before Building user preference that lets you specify how to handle project and document changes prior to building the help file or previewing a topic.

• Added the following new plug-ins:

  • Assembly Binding Redirection Plug-In

  • Bibliography Support Plug-In

  • XPath Reflection File Filter Plug-In - Thanks to Eyal Post for donating the code upon which this plug-in is based.

• Thanks to Jeroen Vos for providing up to date information on using the Sandcastle Help File Builder v1.8.0.0 or later with Visual Studio Team Foundation Server 2008 SP1.

Other Resources