 | 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 2 collection, Microsoft Help Viewer collection, or to additional online MSDN content. Index links are only used by Microsoft Help 2 files. Id links are only used by Microsoft Help Viewer files. The Msdn link type can be used to create links to additional online MSDN 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 2 or 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 OptionsThe 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 (Index to produce Help 2 index links, Id to produce Microsoft Help Viewer links, Msdn to produce URLs that link to online MSDN 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 2 category: All properties
MS Help Viewer category: All properties
Summaries category: All properties
Missing Tags category: All properties
Paths category: HtmlHelp1xCompilerPath, HtmlHelp2xCompilerPath
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