ASP.NET Web API帮助页面为F＃记录类型生成不完整的文档

Question

ASP.NET Web API帮助页面项目不会为用作Web API控制器操作的参数或结果类型的F＃记录类型生成完整的文档。列出了成员，但XML注释中的摘要信息未显示在生成的文档中。我该如何解决这个问题？

实施例

考虑将以下F＃记录类型用作Web API操作方法的参数或结果类型：

[<CLIMutable>]
type ExampleRecord = {

    /// Example property.
    Prop : int

预期输出

此类型生成的帮助页面文档应包含此成员的说明列中的摘要信息。

Name  │ Description       │ Type    │ Additional information
══════╪═══════════════════╪═════════╪═══════════════════════
Prop  │ Example property. │ integer │ None.

实际输出

我们实际看到的是摘要信息完全不存在。

Name  │ Description │ Type    │ Additional information
══════╪═════════════╪═════════╪═══════════════════════
Prop  │             │ integer │ None.

具体细节

此问题与以下特定技术有关：

• Microsoft ASP.NET Web API帮助页面v5.1.1;
• Visual Studio Professional 2013（更新1）;和
• F＃3.1编译器。

尽管有自我回答，但我们已经开放了更好的解决方案，因为我目前所做的并没有真正减少芥末。

Answer 1

更新： doubled namespace issue has been fixed。未来的读者可能需要调整下面的代码。具体而言，您可能需要将"${namespace}${namespace}${class}"更改为"${namespace}${class}"。不要说我没有警告你！

---

问题出现是因为与F＃记录类型的XML文档生成方式有关的两个错误：

1. ＆＃34;当F＃编译器生成文档文件时，它实际上记录了内部字段而不是记录成员的公共属性。＆＃34; - Axel Habermaier

   < / LI>

2. 生成的XML中的namespace of a record member is doubled。

除非对Visual Studio 2013（或者可能只是F＃编译器）进行更新，否则最好的修复方法可能是清理生成的XML的构建后操作。现在，我有一个临时修复，涉及更改获取成员文档的方法。在Areas/HelpPage/XmlDocumentationProvider中，找到带签名的方法：

public string GetDocumentation(MemberInfo member)

...并将定义替换为：

public string GetDocumentation(MemberInfo member)
{
    string selectExpression;
    bool isRecord = FSharpType.IsRecord(member.DeclaringType, FSharpOption<BindingFlags>.None);

    if (isRecord)
    {
        // Workaround for a bug in VS 2013.1: duplicated namespace in documentation for record types.
        Regex matchTypeName = new Regex(@"(?<namespace>(?:[_\p{L}\p{Nl}]+\.)*)(?<class>[_\p{L}\p{Nl}]+)$");
        string classExpression = matchTypeName.Replace(GetTypeName(member.DeclaringType), "${namespace}${namespace}${class}");
        string memberExpression = String.Format(CultureInfo.InvariantCulture, "{0}.{1}", classExpression, member.Name);
        selectExpression = String.Format(CultureInfo.InvariantCulture, FieldExpression, memberExpression);
    }
    else
    {
        string expression = member.MemberType == MemberTypes.Field ? FieldExpression : PropertyExpression;
        string memberName = String.Format(CultureInfo.InvariantCulture, "{0}.{1}", GetTypeName(member.DeclaringType), member.Name);
        selectExpression = String.Format(CultureInfo.InvariantCulture, expression, memberName);
    }

    XPathNavigator propertyNode = _documentNavigator.SelectSingleNode(selectExpression);
    return GetTagValue(propertyNode, "summary");
}

这是一个非常临时的解决方法！如果您更新Web API帮助页面包，它将被覆盖，如果修复了上述错误，将会破坏。我非常感谢任何寻求更好解决方案的帮助。