如何在NuGet包中包含类库的Xml文档？

Question

我正在为一个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>

当我运行这个命令构建包时：

nuget pack MyLibrary.nuspec

它会生成一个错误。如果我删除这一行：

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

NuGet.exe成功创建了nupkg。我甚至可以解压缩包并验证内容正确。我做错了什么？XML文件应该放到不同的目标目录中吗？

- John Nelson

---

你使用什么命令来构建软件包？ - Colonel Panic

@ColonelPanic更新了问题，并附上了命令和文档链接。 - John Nelson

谢谢John。我正在直接打包一个csproj文件，使用命令nuget pack library.csproj（我没有nuspec文件），但修复方法是一样的。 - Colonel Panic

Answer 1

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

- John Nelson

---

好的，我明白了。我试着使用GUI创建一个包，但它让我把XML文件移到内容文件夹而不是lib文件夹中。感觉不对，所以我想听听第二个意见。很高兴你有这篇文章。 :-) - Mike Loux

我该如何从代码中加载生成的文件以便读取它？我想我需要知道这个设置中的值，还需要知道项目的路径。我尝试使用 asm.Location，这让我进入了 bin\Debug\netcoreapp 等目录。 - Aaron Franke

啊，感谢提供截图。这个框也必须在发布模式下检查。很容易忽略 :-(。 - astrowalker

Answer 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>

- bytedev

---

<GenerateDocumentationFile> 会生成 <DocumentationFile>，因此我认为只需要其中之一，参见：https://learn.microsoft.com/en-us/dotnet/csharp/codedoc - Kapé

指定自己的<DocumentationFile>只是允许您将文件输出到任何位置。如果不指定，我认为它会按照上面提供的路径字面意义地放置该文件。 - bytedev

Answer 3

最简单的解决方案是只需添加@bytedev答案的前半部分。这将默认为正确的位置并且将被正确打包。

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

- DLeh