Assembly Binding Redirection Plug-In
This plug-in is used to add assembly binding redirection support to the MRefBuilder configuration file. With this in place, it is possible to document assemblies that use binding redirection to reference assemblies of a different version than the ones they were built against. It is also possible to add assembly names to ignore if they are unresolved which is useful in certain situations where the named dependency assembly is unavailable (i.e. the Crystal Reports keycode decoder assembly).
Configuring the Plug-In
Once added to the project, this plug-in must be configured. The first tab is used to enter binding redirection information. The second tab is used to enter assemblies to ignore if unresolved. The Use the GAC to resolve unknown assembly references option at the top of the dialog box can be checked to have the resolver try to find the assembly in the Global Assembly Cache before attempting to use the redirections. If an appropriate version is found there, it will be used and the redirections will not be checked.
Binding Redirection Configuration Options
The configuration consists of one or more entries that define how to redirect an assembly reference or an application configuration file from which the settings should be imported. A list box at the top of the Binding Redirections tab lists the current definitions. Click the Add button to the right of the list box to add a new item. The property grid at the bottom of the tab is used to edit each entry's settings. Click the Delete button to the right of the list box to delete an entry. Each entry consists of the following configuration options:
Option | Description |
|---|---|
ConfigurationFile | This option allows you to specify a configuration file from which the binding redirection settings are imported. This should be an application or web configuration file (i.e. App.exe.config or Web.config) that contains an assemblyBinding section that defines the dependent assemblies and how they should be redirected. If specified, all other configuration options are ignored. The value can contain replacement tags to specify the path to the file (i.e. {@ProjectFolder}..\bin\MyApp.exe.config). |
AssemblyName | The assembly name that will be redirected. Specify only the name of the assembly. Do not include a path or extension. |
PublicKeyToken | Specify the public key token of the assembly. If left blank, "null" is assumed. |
Culture | Specify the culture of the assembly. If left blank, "neutral" is assumed. |
OldVersion | Use this to specify the old version that will be redirected. If the OldVersionTo property is left blank, this will be used as the single version to redirect. This can be a version value from 0.0.0.0 to 65535.65535.65535.65535. |
OldVersionTo | To redirect a range of assembly versions, enter the starting version number in the OldVersion property and the ending version number in this property. If this property is left blank, only the version specified in OldVersion is redirected. This can be a version value from 0.0.0.0 to 65535.65535.65535.65535. |
NewVersion | This defines the new assembly version to which the old versions are redirected. |
Ignore If Unresolved Entries
This tab is used to enter one or more assembly names to ignore if they are unresolved. By default, it contains two entries: one for the Crystal Reports BusinessObjects.Licensing.KeycodeDecoder assembly and another for the Visual Studio Microsoft.VisualStudio.TestTools.UITest.Playback assembly. Both of those are not distributed and can cause documentation projects that include them indirectly through other reference assemblies to fail when built.
Type the name of an assembly to add without a path or extension, just the name reported by the MRefBuilder tool when it fails due to the missing assembly. Click the Add button to add it to the list. Select an entry and click the Delete button to remove an entry.
Caution
This option is only to be used in the event that you do no have the named assembly and do not care about missing information for it in your help file. It is always better to find the reference assembly and add it as a reference in the documentation project rather than to ignore it altogether. Doing so may result in missing information in the help file. This option is truly a last resort if there is no possible way to obtain a copy of the missing reference assembly.