Click or drag to resize
Sandcastle Help File Builder

References

The MRefBuilder tool may not resolve references to all assemblies used by a target, especially those found in the Global Assembly Cache (GAC). As such, it needs a hint to find the files and load them when needed (the /dep command line option). The References project node is used to specify a list of dependencies used by the MRefBuilder tool when it generates reflection information for the documentation source assemblies. Dependency information allows inherited members to be listed for a type but topics will not be generated for them and the information will not appear in the table of contents of the help file.

Adding a Reference

To add a reference, right click on the References project node and select Add File/Project Reference... or Add GAC Reference.... These options can also be selected from the File | Project Explorer | References menu. Files can also be dragged and dropped on the node from Windows Explorer. The following reference types are supported in the project.

  • File Reference - Select an assembly to use as the reference.

  • Project Reference - Select a Visual Studio project to use as a reference. In this case, the output assembly of the project is used as the reference unless the ReferenceOutputAssembly property is set to false (see below).

  • GAC Reference - Select an entry from the Global Assembly Cache to use as the reference.

  • COM Reference - COM references are also supported. However, they cannot be added via the standalone GUI. As an alternative, you can add the COM-callable wrappers that Visual Studio creates as file references.

Tip Tip

Given that solutions and projects are supported as documentation sources, you may find it easier to add them as documentation sources instead of the assemblies, comments, and references that they contain. When a solution or project is used, these items are imported from them automatically at build time.

Tip Tip

If you have one or more folders containing reference assemblies that you would like to scan and include at build time, you can use the Wildcard References Plug-In

Editing a Reference

When selected, file and project references allow you to edit the HintPath property to specify the referenced file. All other references have read-only properties. To change them, remove them and add the desired references in their place. Project references also contain a ReferenceOutputAssembly property. If set to true (the default), the project's output assembly will be used as a reference. If set to false, the reference will be ignored. This is useful for defining project dependencies that MSBuild can use to determine the build order of projects within a solution without including the project's assembly as an actual reference.

Note Note

If using environment variables in the hint path, use the MSBuild format rather than percent signs so that they are expanded correctly (i.e. $(MyVar)\Reference.dll).

Removing a Reference

To remove a reference, right click on it and select the Remove option. This can also be selected from the File | Project Explorer | References menu.

See Also