MRefBuilder (EXE)

  • Article

I my previous blog I discussed Sandcastle.config in detail. Sandcastle process uses three executables:

  • MRefBuilder: Reflects over managed assemblies to produce an XML-formatted reflection information file.
  • BuildAssembler: Collates information from comment files and reflection information files into a set of HTML pages.
  • XslTransform: Applies XSL transforms to XML files. This executable is used to generate and manipulate auxiliary data files.

The MRefBuilder application reflects over a set of managed assemblies and creates an XML output file containing information about the APIs found in those assemblies. APIs are namespaces, types, and members defined in the assembly. Reflection data includes, but is not limited to: visibility, return types, parameter names and types, inheritance data, whether a class is abstract or sealed, etc. The output of MRefBuilder is consumed by the reference build component stack when creating API reference documentation.

The invocation syntax for MRefBuilder is as follows:

          MRefBuilder.exe dll /dep:dep /out:out /namespaces- /internal-

Here dll is the path to an assembly to reflect over. More than one dll path may be specified, and each dll path may be a wildcard path corresponding to multiple assemblies.

The /dep option specifies a dependency assembly to load. (A dependency assembly is an assembly upon which one of the reflected assemblies depends; i.e. the dll assembly was compiled with a reference to the dep assembly.) Multiple /dep options are allowed, and each option may specify a wildcard path corresponding to multiple assemblies.

The /out option species a path to an output file; if no /out option is specified, output is sent to the console.

The /namespaces (not available in July CTP) option specifies whether namespaces are included in the output; by default they are. The Boolean /namespaces option enables the componentized build scenario. In that scenario, MRefBuilder would be run with /namespaces- on each assembly. The resulting reflection data would be used to generate separate HxS documentation, without namespace topics, for each assembly. Then a separate tool would be run over all the assembly reflection data files together to produce a namespace reflection data file, listing all the namespaces and their corresponding members in all assemblies. This namespace reflection data file would then be used as input to generate one more CHM/HxS containing only namespace topics.

The /internal (not available in July CTP) option specifies whether APIs visible only inside the assembly are included in the output; by default they are not.

If a required dependency assembly is missing, MRefBuilder will report the name and version information of the missing assembly and of the assembly that depended on it. This error condition is fatal.

MRefBuilder uses the Common Compiler Infrastructure (CCI) reflection library to do its work.

The schema of MRefBuilder output is complex. Fundamentally, the structure is just a list of APIs:

<apis>

          <api id=”cer” />

                   <!-- many child elements containing

reflection data on cer -->

          </api>

          <!-- more api elements -->

</apis>

There are, however, many possible descendents of each api element, each providing different reflection data. Just which descendents may appear depends on the kind of API described.

The format for reflection data produced by MRefBuilder is very important and the reflection data is consumed by the following:

  • A BuildComponent in the component stack for reference builds.

  • A transform that produces the BuildAssembler manifest for reference builds.

  • A transform that produces the HxT table of contents for reference builds.

We are currently looking at the naming convention and will probably rename MRefBuilder to Mreflector for Sandcastle RTW. We also expect the Sandcastle reflection data format to be targeted not only by MReflector, but also by unmanaged reflection tools (for example, a UReflector tool that parses IDL or header files) and SReflector (for generating schema documentation). In order to make it easier for other to target the reflection data format, we plan to supply an XML schema file that defines the format.