Click or drag to resize
Sandcastle Help File Builder

Additional Reference Links Plug-In

This plug-in is used to add additional reference link targets to the Reflection Index Data and Resolve Reference Links build components so that index links can be created to other third party help topics in a Microsoft Help Viewer collection or to additional online help content. Id links are only used by Microsoft Help Viewer files. The Msdn link type can be used to create links to additional online content such as for SharePoint libraries, etc. The None link type can also be specified to render the references as non-clickable labels. This may be of use in reducing the number of warnings about unresolved reference links in a build but is not really needed as unresolved links are automatically rendered as non-clickable labels.

This component is also helpful if you create separate Microsoft Help Viewer files for each assembly in a project. By referencing the other related assembly help projects with this plug-in, you can ensure that the links to API topics in the other help files will work. For example, consider a product consisting of the following assemblies.

  • MyCompany.MyProduct.Base.dll

  • MyCompany.MyProduct.Windows.Forms.dll

  • MyCompany.MyProduct.Web.Controls.dll

The Windows Forms and the Web Controls assemblies both reference types found in the base assembly. If you want to segregate the help for each assembly into its own help file, you can create one help file builder project for each assembly. In the projects for the Windows Forms and the Web Controls assemblies, you would add this plug-in and reference the project for the base assembly.

Configuration Options

The configuration options consist of a list of other projects that will be built and have their reference link 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. A link type is associated with each project in the configuration (Id to produce Microsoft Help Viewer links, Msdn to produce URLs that link to online content, or None to produce non-clickable labels). The order of the projects in the configuration is not relevant.

Since the plug-in uses help file builder projects to generate the reference information, you are free to mix projects built against different .NET framework versions, ones that use different API filters specific to that project, ones that use a different set of dependencies, or that contain other project settings specific to the related project. 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 projects are included in the current project's build so that inherited members are still documented correctly. Where there are XML comments common to multiple projects, 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