How do you include Xml Docs for a class library in a NuGet package?

Question

I am creating a NuGet package for a C# class library, and I would like to include generated Xml Documentation with the library. This is my nuspec file:

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

When I build the package with this command:

nuget pack MyLibrary.nuspec

It generates an error. If I remove the line:

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

NuGet.exe successfully creates the nupkg. I can even unzip the package, and verify that the contents are correct. What am I doing wrong? Should the xml file go into a different target directory?

Solution 1

The problem was that I didn't check "Generate Xml Documentation" for the build configuration I was using. That nuspec is correct.

Solution 2

In .NET Core/Standard you can do this by editing the project XML file, for example:

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

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

This will output the documentation as an XML file next to your output assembly.

EDIT: As a side note once you enable GenerateDocumentationFile you will probably get lots of warnings on your public methods for not having added full documentation tags. If you want to disable these warnings simply add in the PropertyGroup:

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

Comments

[Mike Loux]

Good to know. I was trying my hand at using the GUI to create a package, and it was trying to get me to move the XML file to the content folder instead of lib. Didn't seem right, so I wanted to get a second opinion. Glad you had this post. :-)

[Kapé]

<GenerateDocumentationFile> results in a <DocumentationFile> already, so I think only one of both is required, see: docs.microsoft.com/en-us/dotnet/csharp/codedoc

[bytedev]

Specifiying <DocumentationFile> yourself just allows you to output the file where ever you want. If you dont specify it I think it literally puts it in the path I have provided above.

[Aaron Franke]

How do I load the generated file from code so that I can read it? I suppose I would need to know the value in this setting, and I would also need to know the path of the project. I've tried using asm.Location and this gets me inside of bin\Debug\netcoreapp etc.