Compartilhar via

MRefBuilder (EXE)

  • Artigo

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.

Comments

  • Anonymous
    August 13, 2006
    Hi Aram,
    Wanted to let you know I released a new version of the free add-in suit, including sandcastle support. Now with easy to use msi installer.

    <a href="http://www.codeplex.com/Wiki/View.aspx?ProjectName=SandcastleAddIn">add-in msi on codeplex</a>

    I'm also wondering if it would be possible to include custom xml, like tasks for example, in my code and find them back in the documentation afterwards by adjusting the xsl. Didnt try it yet, but was just a thought... (now done before compiling)
    Cheers,
    Frank

  • Anonymous
    August 13, 2006
    sry, no html needed :'(
    http://www.codeplex.com/Wiki/View.aspx?ProjectName=SandcastleAddIn

  • Anonymous
    August 13, 2006
    Frank,
    Thanks a lot anf this is awesome. I will check out your codeplex project.

    Anand..

  • Anonymous
    August 16, 2006
    The comment has been removed

  • Anonymous
    August 16, 2006
    Not from reflection but you can certainly not document them. I will look into this further and will provide an anaswer.

    Anand..

  • Anonymous
    August 17, 2006
    They are not documented with XML, but still appear as protected members of the class since the designer is a partial class with the code behind.

  • Anonymous
    August 18, 2006
    Using MRefBuilder I stumbled upon a problem in one of my assemblies. MRefBuilder crashed with an unhandled NullReferenceException and the following stacktrace:
    at Microsoft.Ddue.Tools.Reflection.DocStudioNamer.WriteType(TypeNode type, TextWriter writer)
    at Microsoft.Ddue.Tools.Reflection.DocStudioNamer.GetTypeName(TypeNode type)
    at Microsoft.Ddue.Tools.ManagedReflectionWriter.WriteStartTypeReference(TypeNode type)
    at Microsoft.Ddue.Tools.ManagedReflectionWriter.WriteParameter(Parameter parameter)
    at Microsoft.Ddue.Tools.ManagedReflectionWriter.WriteParameters(ParameterList parameters)
    at Microsoft.Ddue.Tools.ManagedReflectionWriter.WriteMember(Member member, TypeNode type)
    at Microsoft.Ddue.Tools.ManagedReflectionWriter.VisitMember(Member member)
    at Microsoft.Ddue.Tools.Reflection.ApiVisitor.VisitMembers(MemberList members)
    at Microsoft.Ddue.Tools.ManagedReflectionWriter.VisitType(TypeNode type)
    at Microsoft.Ddue.Tools.Reflection.ApiVisitor.VisitTypes(TypeNodeList types)
    at Microsoft.Ddue.Tools.ManagedReflectionWriter.VisitNamespace(Namespace space)
    at Microsoft.Ddue.Tools.Reflection.ApiVisitor.VisitNamespaces(NamespaceListspaces)
    at Microsoft.Ddue.Tools.ManagedReflectionWriter.VisitNamespaces(NamespaceList spaces)
    at Microsoft.Ddue.Tools.Reflection.ApiVisitor.VisitApis()
    at Microsoft.Ddue.Tools.MRefBuilder.Main(String[] args)

    Poking around a bit I found out the following method was to blame:
    protected R CallWebService<R, A>(ServiceRequestDelegate<R, A> requestMethod, A requestArgs){

    the delegate was defined as
    public delegate R ServiceRequestDelegate<R, A>(A requestArgs);
    inside the class.
    Moving the declaration outside the class scope solved the problem.
    Hope this helps finding the bug and provides a workaround for people running into the same problem.

  • Anonymous
    August 20, 2006
    Installation and Layout

    Sandcastle CTP can be downloaded from http://www.microsoft.com/downloads/details.aspx?FamilyId=E82EA71D-DA89-42EE-A715-696E3A4873B2&amp;amp;displaylang=en...

  • Anonymous
    November 02, 2006
    I'm trying to use the MRefBuilder on a group of assemblies, but one of my assemblies have a dependency to a third party assembly. The third party assembly has compile time dependency to Microsoft.Ink assembly which i have not installed. When i run MRefBuilder, the result is the following error message: Error: Unresolved assembly reference: Microsoft.Ink (Microsoft.Ink, Version=1.7.2600.2180, Culture=neutral, PublicKeyToken=31bf3856ad364e35) required by Infragistics2.Win.UltraWinInkProvider.Ink17.v5.3 Is there any way/setting to indicate that only information in my own assemblies is relevant for the reflection process, thus forcing MRefBuilder to only analyze my own assemblies for the output file?

  • Anonymous
    November 02, 2006
    The comment has been removed

  • Anonymous
    June 27, 2007
    In April I blogged about Bertrand Leroy 's, cool document extraction tool (ScriprDoc 1.0) that will generate

  • Anonymous
    February 18, 2014
    I have been trying to use sand castle for our project(mvc). But it is continuously giving reference  error. MRefBuilder : error : Unresolved assembly reference: System.Core (System.Core, Version=2.0.5.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e, Retargetable=Yes) required by AutoMapper [C:codeOurProjectsandcastleHelpWorkingGenerateRefInfo.proj] I couldn't fix that after referring to the system.core When I tried removing AutoMapper.dll , it showed another error saying unresolved reference to system.web.mvc version 1.0.0.0, even after referencing this file I have been trying to figure out what is going wrong for days and I am unable fix it yet Please help :(