以编程方式检索 xml 文档注释 [关闭]

Question

Visual Studio 做到了；反射器做到了；现在我也想这样做:)

我想检索某些框架程序集中的某些成员的 XML 文档（即mscorlib.dll、System.dll 等）。我认为这将涉及：

• 查找程序集的 XML 文件，
• 导航到适当命名的子元素，并且
• 检索所需项目（<summary>、<remarks> 等）

框架程序集的 XML 文件保存在哪里？关于破译 XMLDOC 命名方案的任何要点？是否有任何库可以简化此过程？

Answer 1

查找 xml

对于 assembly.dll，它被命名为 assembly.xml，但由 Framework SDK 安装，运行时本身不包含 .xml 文件。用户不需要 API 文档。

位置有点复杂。它可以与 dll 并排放置在以当前语言环境命名的子目录中（例如 C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\en），甚至可以在附近的某个奇怪目录中。我建议以运行时查找附属程序集的方式搜索它。

查找元素

要查找元素，您应该从元数据中准备所谓的“xml-doc ID”。 AFAIR 它记录在 C# 语言规范中，并在 MSDN 中有所记录。见Processing XML documentation。

Answer 2

基于Ilya's response：

查找 xml

.NET fallback locations（忽略 GAC 和其他不相关的子目录）

static FileInfo GetXmlDocFile( Assembly assembly ) {
  string assemblyDirPath = Path.GetDirectoryName( assembly.Location );
  string fileName = Path.GetFileNameWithoutExtension( assembly.Location ) +".xml";

  return GetFallbackDirectories( CultureInfo.CurrentCulture )
    .Select( dirName => CombinePath( assemblyDirPath, dirName, fileName ) )
    .Select( filePath => new FileInfo( filePath ) )
    .Where( file => file.Exists )
    .First( );
}

static IEnumerable<string> GetFallbackDirectories( CultureInfo culture ) {
  return culture
    .Enumerate( c => c.Parent.Name != c.Name ? c.Parent : null )
    .Select( c => c.Name );
}

static IEnumerable<T> Enumerate<T>( this T start, Func<T, T> next ) {
  for( T item = start; !object.Equals( item, default(T) ); item = next( item ) )
    yield return item;
}

static string CombinePath( params string[] args ) {
  return args.Aggregate( Path.Combine );
}

查找元素

Processing XML Documentation

static XElement GetDocMember( XElement docMembers, MemberInfo member ) {
  string memberId = GetMemberId( member );
  return docMembers.Elements( "member" )
    .Where( e => e.Attribute( "name" ).Value == memberId )
    .First( );
}

static string GetMemberId( MemberInfo member ) {
  char memberKindPrefix = GetMemberPrefix( member );
  string memberName = GetMemberFullName( member );
  return memberKindPrefix + ":" + memberName;
}

static char GetMemberPrefix( MemberInfo member ) {
  return member.GetType( ).Name
    .Replace( "Runtime", "" )[0];
}

static string GetMemberFullName( MemberInfo member ) {
  string memberScope = "";
  if( member.DeclaringType != null )
    memberScope = GetMemberFullName( member.DeclaringType );
  else if( member is Type )
    memberScope = ((Type)member).Namespace;

  return memberScope + "." + member.Name;
}

使用示例

Type type = typeof( string );

var file = GetXmlDocFile( type.Assembly );
var docXml = XDocument.Load( file.FullName );
var docMembers = docXml.Root.Element( "members" );

var member = type.GetProperty( "Length" );
var docMember = GetDocMember( docMembers, member );

Answer 3

我在 CodePlex 上维护 Jolt.NET 项目，并实现了一项功能来执行这项任务。有关详细信息，请参阅Jolt 库。

本质上，该库允许您使用System.Reflection 中的元数据类型（即MethodInfo、PropertyInfo 等...）以编程方式定位和查询XML doc cmets 文件以查找程序集。

Answer 4

试试DocsByReflection。

// From method.
var methodInfo = typeof(Stub).GetMethod("MethodWithGenericParameter");
var methodDoc = DocsService.GetXmlFromMember(methodInfo);

Answer 5

这是一个现成的库，可让您做到这一点：NuDoc http://kzu.to/nudoc

例如，阅读 mscorlib 上的整个文档，就像这样简单：

var members = Reader.Read(typeof(string).Assembly);

您可以稍后使用简单的访问者处理结果，如网站上所示。

我正在利用该库生成一个 API 站点，该站点使用 Markdown 托管在 GitHub 中，理想情况下是在每次构建时自动生成，甚至可能用于 wiki，以便它可以更新并往返于代码 :) .

Answer 6

XML 文件的命名与程序集的文件完全一样，除了不同的“xml”扩展名，并且必须与程序集本身位于同一目录中。

不过，无法帮助您解决其他两个问题。 AFAIK，你自己一个人……