Reflection Data Manager Tool
This tool is used to create reflection data set definition files for the various .NET frameworks
and to build the reflection information files used by the other Sandcastle tools. Reflection data set definition
files have an extension of .reflection.
Command Line Parameters
This tool can be executed from the command line to build reflection information for a given
framework version. If no command line parameters are specified, a form will open that allows you to load and
edit reflection data set files and build them interactively. The following parameters are available.
- /platform:platformName
Required. Specify the platform to use for the build. This should be one of the well-known
platform type IDs: .NETCore, .NETFramework,
.NETMicroFramework, .NETPortable,
Silverlight, WindowsPhone, or
WindowsPhoneApp
- /version:version
Optional. Specify the version to use for the build. If not specified, the most recent version
for the specified platform is used. Typically, this should be omitted so that the reflection data is generated
off of the most recent version available.
- /path:dataSetPath[,dataSetPath,dataSetPath,...]
Optional. Specify one or more additional paths to search for reflection data set files if
necessary in a comma-separated list. By default, the tools folder and the common application data folder are
searched for reflection data set files automatically. Use this option to specify a path containing a file
not found in one of those standard locations such as a definition file for a new framework version.
ReflectionDataManager.exe /platform:.NETFramework /version:4.6
When ran with no command line parameters, a form will open that allows you to load and edit
reflection data set definition files. By default, the form is set up to create a new file. The following menu
options are available:
New - Clear any currently loaded reflection data set definition file settings and
create a brand new file.
Open - Open an existing reflection data set definition file.
Save - Save the current reflection data set definition file.
Save As - Save the current reflection data set definition file to a new name.
Build Reflection Data - Build the reflection information for the currently loaded
reflection data set definition file. See the Building Reflection Data
section below for more information.
The reflection data set definition consists of the following information:
Platform ID - Select the platform ID with which the definition is associated. This
will be one of the standard platform type IDs: .NETCore, .NETFramework,
.NETMicroFramework, .NETPortable,
Silverlight, WindowsPhone, or
WindowsPhoneApp. These match the target framework identifier property values used in
related Visual Studio project files.
Version ID - Enter the framework version with which the definition file is associated.
These match the target framework version values used in related Visual Studio project files.
Title - Enter a title for the definition file that uniquely identifies it. This is
used by build tools such as the Sandcastle Help File Builder to offer a list of framework versions to use when
building documentation projects.
Notes - If necessary, enter any notes about the definition file that may be useful to
those using it. It can be left blank.
Assembly Locations - The most important part of the definition file are the assembly
locations. The bottom half of the form allows you to add one or more locations that will be searched for
assemblies and their related XML comments files.
Click the Add button to add a new framework location. Enter a path in the
Assembly Location text box or use the "..." button to select a path. Once you select a path
or tab out of the text box, the list of available assemblies will be loaded into the list box. The path can
contain environment variables such as ProgramFiles(x86). Any such
variables will be resolved when searching for assemblies and comments files. Only the given path is searched.
Any subfolders it contains are not searched. If necessary, subfolders can be added as additional locations.
Each assembly is preceded by a checkbox. If checked, the given assembly is included in the
definition set. If unchecked, the assembly will be ignored and will not be parsed to generate reflection
information. This is useful if the folder contains unmanaged assemblies or managed assemblies that contain no
useful information. If editing an existing file and new assemblies have been added to the folder or old ones
removed, clicking the Refresh button will update the list based on the assemblies that currently exist
in the specified folder.
To remove an assembly location, click the Remove button. To navigate between location
entries, use the Previous and Next buttons.
Reflection data set definition files should be saved into a folder that will be used to contain
the related reflection information generated by building it. The folder can contain multiple definition files if
they are for different versions of the same platform. For example, all of the .NETFramework
definition files are grouped into a folder along with the reflection data for the latest version.
The build process will delete any existing .xml files from the folder
containing the definition file being built and will copy the new reflection information files to the same
location.
When the Build Reflection Data option is chosen, a new form opens. From there, you can
define some additional build parameters and generate the reflection information files. The build parameters are
as follows:
Ignored Namespaces - Use this section to enter a list of ignored namespaces. Any
namespace in this list will be omitted from the generated reflection information. This is useful for omitting
namespaces that contain no useful public types.
Ignored Unresolved Assembly Identities - Use this section to enter the identities of
assemblies that cannot be resolved and should be ignored when generating reflection information. Enter only the
name part of the identity (i.e. Microsoft.Windows.Design.Extensibility).
Binding Redirections - Use this section to enter assembly binding redirections to
allow resolving of assemblies that reference a different version than the one available. Enter the information
from the assembly's strong name. The Name part is required along with the Old Version to be
redirected and the New Version to use in its place. The Culture will default to neutral if not
specified. The Public Key Token will default to null if not specified.
To add an entry, select the blank row at the end and start typing in the values. To delete an
entry, click on the row header and hit the Delete key.
Click the Build button to generate the reflection information files. The build progress
is shown in the text box in the lower half of the form. Once finished, you will find the reflection information
files in the same location as the definition file.
