如何在 NuGet 包中包含类库的 Xml Docs？答案

【问题标题】：How do you include Xml Docs for a class library in a NuGet package?如何在 NuGet 包中包含类库的 Xml Docs？
【发布时间】：2020-08-22 09:28:56
【问题描述】：

我正在为 C# 类库创建一个 NuGet 包，并且我想将生成的 Xml 文档包含在该库中。这是我的 nuspec 文件：

<?xml version="1.0" encoding="utf-8"?>
<package>
  <metadata>
    <id>MyLibrary</id>
    <version>1.0.0.0</version>
    <authors>John Nelson</authors>
    <language>en-US</language>
    <description>A C# class library</description>
  </metadata>
  <files>
    <file src="..\..\build\MyLibrary.dll" target="lib\Net40" />
    <file src="..\..\build\MyLibrary.xml" target="lib\Net40" />
  </files>
</package>

当我build the package with this command:

nuget pack MyLibrary.nuspec

它会产生错误。如果我删除该行：

<file src="..\..\build\MyLibrary.xml" target="lib\Net40" />

NuGet.exe 成功创建 nupkg。我什至可以解压缩包，并验证内容是否正确。我究竟做错了什么？ xml文件是否应该进入不同的目标目录？

【问题讨论】：

你使用什么命令来构建包？
@ColonelPanic 使用命令和文档链接更新了问题。
谢谢约翰。我直接打包了一个 csproj nuget pack library.csproj（我没有 nuspec），但修复工作相同。

标签： c# nuget nuget-package

【解决方案1】：

问题是我没有检查我正在使用的构建配置的“生成 Xml 文档”。那个 nuspec 是正确的。

【讨论】：

很高兴知道。我正在尝试使用 GUI 创建一个包，它试图让我将 XML 文件移动到内容文件夹而不是 lib。好像不太对，所以想征求一下意见。很高兴你有这篇文章。 :-)
如何从代码中加载生成的文件以便阅读？我想我需要知道这个设置中的值，我还需要知道项目的路径。我试过使用asm.Location，这让我进入bin\Debug\netcoreapp等。

【解决方案2】：

在 .NET Core/Standard 中，您可以通过编辑项目 XML 文件来做到这一点，例如：

<PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

<PropertyGroup>
    <DocumentationFile>bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml</DocumentationFile>
</PropertyGroup>

这会将文档作为 XML 文件输出到您的输出程序集旁边。

编辑： 附带说明一下，一旦启用GenerateDocumentationFile，您可能会在公共方法上收到很多警告，因为您没有添加完整的文档标签。如果您想禁用这些警告，只需添加PropertyGroup：

<NoWarn>$(NoWarn);1591</NoWarn>

【讨论】：

<GenerateDocumentationFile> 已经产生了<DocumentationFile>，所以我认为两者中只有一个是必需的，请参阅：docs.microsoft.com/en-us/dotnet/csharp/codedoc
自己指定<DocumentationFile> 只允许您将文件输出到您想要的任何位置。如果您不指定它，我认为它实际上是把它放在我上面提供的路径中。