Click or drag to resize
Sandcastle Help File Builder

Version Builder Plug-In

This plug-in is used to generate version information for assemblies in the current project and other projects related to the same product that can be merged into the current project's help file topics. A separate Version Information section is created in each topic that can list one or more frameworks and/or versions in which the member appears. When the plug-in is used, the version number in the assembly information message added by the build component is omitted. Topics such as the namespace list, class member lists, and overloads lists do not contain a version information section.

The configuration options consist of a framework label and a version number for the current project and a list of other projects that will be built and have their API information merged with the current project. Note that these will only produce a partial build, enough to generate reflection information. XML comments files for the documented assemblies are optional. In the configuration, each additional project is assigned a framework label and a version number to uniquely identify it. The framework labels can be identical to the current project or they can be unique or matched between the other projects. The framework label controls how the version information is grouped. Both are free-form text so you can enter any value to identify the framework and version. The order of the projects in the configuration is not relevant. Version information is sorted by version number in descending order within framework label at the time the help file is actually built. For example:

  • Current project label: Windows Forms Controls, Version: 2.1

  • Other Project 1 label: Windows Forms Controls, Version: 1.3.5

  • Other Project 2 label: Compact Framework Controls, Version: 1.3.2

  • Other Project 3 label: Compact Framework Controls, Version: 2.3.1

Depending on the presentation style selected, this would produce a Version Information section in each member topic similar to the following:

Version Information

Compact Framework Controls
Supported in: 2.3.1, 1.3.2

Windows Forms Controls
Supported in: 2.1, 1.3.5

If the framework label is common to all versions being documented, you can leave it blank. However, this may affect the display of the version information in some styles which expect to have a framework label value.

If checked, the Remove old APIs no longer in latest versions option will cause the version builder tool to remove all API members that no longer appear in the latest version within each set of assemblies with a common framework label value. If left unchecked (the default), all members from all versions will be included in the help file.

Since the plug-in uses help file builder projects to generate the other version information, you are free to mix projects built against different .NET framework versions, ones that use different API filters specific to that version, ones that use a different set of dependencies, or that contain other project settings specific to the related version. As noted, the additional projects only go through a partial build, enough to generate reflection information. As such, the following project properties are ignored in the other projects:

  • Build category: BuildAssemblerVerbosity, CleanIntermediates, DisableCodeBlockComponent, HelpFileFormat, IndentHtml, KeepLogFile

  • Help File category: All properties

  • Help 1/Website category: All properties

  • MS Help Viewer category: All properties

  • Summaries category: All properties

  • Missing Tags category: All properties

  • Paths category: HtmlHelp1xCompilerPath

  • Components category: All properties

  • Plug-Ins category: All plug-ins that function after the last partial build step.

  • Transform Arguments category: All properties

XML comments files from the other versions are included in the current project's build so that members not appearing in all projects are still documented correctly. Where there are XML comments common to multiple versions, those from the current project will always take precedence. As noted above, XML comments files are optional. If omitted, no comments will be associated with the given assembly.

See Also

Other Resources