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?

@ColonelPanic updated question with command and link to docs. — John Nelson, May 15 '15 at 14:26
Thanks John. I am packaging a csproj directly `nuget pack library.csproj` (I don't have a nuspec), but the fix works the same. — Colonel Panic, May 15 '15 at 14:34

score 113 · Accepted Answer · edited Oct 30 '14 at 20:43

113

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

enter image description here

edited Oct 30 '14 at 20:43

Jerther

5,558
8
40
59

answered Mar 07 '11 at 01:07

John Nelson

5,041
6
27
34

6

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. :-) – Mike Loux Jan 01 '12 at 15:41
1

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. – Aaron Franke Nov 23 '21 at 00:25
Ah, thank you for the screenshot. This box has to be also check in **Release** mode. Easy to miss :-(. – astrowalker Oct 05 '22 at 08:37

bytedev · Answer 2 · 2020-01-28T03:33:15.687

34

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>

edited Jan 28 '20 at 03:33

answered Sep 30 '19 at 10:13

bytedev

8,252
4
48
56

6

`` results in a `` already, so I think only one of both is required, see: https://learn.microsoft.com/en-us/dotnet/csharp/codedoc – Kapé Jan 10 '20 at 10:01
1

Specifiying `` 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. – bytedev Jan 10 '20 at 10:14

score 2 · Answer 3 · answered Nov 01 '22 at 13:34

The easiest solution is to simply add the first half of @bytedev's answer. This defaults to the correct location and will be packaged correctly.

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

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

3 Answers3

Linked