问从DocFx包中检索NuGet元数据

EN

如果在metadata配置中指定程序集，DocFx将在同一个目录(来源)中查找documentation。但是，问题在于，当您包含NuGet引用时，项目的bin文件夹中没有包含XML，即使它包含在NuGet包中。因此，虽然DocFx能够识别结构，但它无法识别文档。

TL;DR:为了解决这个问题，您可以配置msbuild将XML复制到bin文件夹，确保DocFx能够访问它(示例)。详情如下。

背景

默认情况下，当引用NuGet包时，包将被下载、解压缩并缓存在以下位置：

%UserProfile%\.nuget\packages\{Package}\{Version}\

注意:这显然是一个Windows目录；位置将因操作系统而异。

这将包括例如，

\lib\net6.0\{AssemblyName}.dll
\lib\net6.0\{AssemblyName}.xml

构建.NET项目时，{AssemblyName}.dll将复制到项目的bin目录，而不是{AssemblyName}.xml。由于您已经指示DocFx查看您的项目的bin文件夹，因此它无法收集文档。

天真的解决办法

显而易见的解决办法是直接从NuGet缓存中获取元数据。这可以很容易地通过调整docfx.json配置来实现，如下所示：

{
  "metadata": [
    {
      "src": [
        {
          "files": "bin/Release/net6.0/{AssemblyName}.dll",
          "src": "C:\\Users\\{User}\\.nuget\\packages\\{Package}\\{Version}\\lib\\net6.0\\"
        }
      ],
      "dest": "api/{AssemblyName}"
    }
  ]
  …
}

当然，这很管用。但是它也是一个非常脆弱的解决方案，对于生产代码来说是不可行的。最值得注意的是，DocFx不识别%UserProfile%别名，因此必须将{User}硬编码到配置中。这不仅对于每个开发人员来说是不同的，而且在构建服务器上也是不同的。在非Windows环境中，这甚至是不考虑因素的。

更好的解决办法

考虑到这一点，更好的解决方案是指示msbuild将bin文档与程序集一起复制到bin文件夹。幸运的是，这非常容易，正如在如何在csproj构建输出中包含Nuget包中的XML文档中讨论的那样。在您的csproj文件中，只需添加以下内容：

<Project>
  <Target Name="_ResolveCopyLocalNuGetPkgXmls" AfterTargets="ResolveReferences">
    <ItemGroup>
      <ReferenceCopyLocalPaths Include="@(ReferenceCopyLocalPaths->'%(RootDir)%(Directory)%(Filename).xml')"
      Condition="'%(ReferenceCopyLocalPaths.NuGetPackageId)'!='' and Exists('%(RootDir)%(Directory)%(Filename).xml')" />
    </ItemGroup>
  </Target>
</Project>

这种方法的主要优点是它依赖msbuild变量来抽象NuGet缓存的位置、包名、版本号和目标文件夹。因此，这应该适用于任何机器或操作系统。

这样，DocFx将成功地在程序集旁边找到XML文档，并将其包含在生成的yml元数据中。