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
– John Nelson, Commented May 15, 2015 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
– Colonel Panic, Commented May 15, 2015 at 14:34

Jerther · Accepted Answer · 2014-10-30 20:43:31Z

116

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, 2014 at 20:43

Jerther

6,0559 gold badges44 silver badges63 bronze badges

answered Mar 7, 2011 at 1:07

John Nelson

5,1616 gold badges29 silver badges34 bronze badges

Sign up to request clarification or add additional context in comments.

3 Comments

Mike Loux Over a year ago

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. :-)

Aaron Franke Over a year ago

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.

greenoldman Over a year ago

Ah, thank you for the screenshot. This box has to be also check in Release mode. Easy to miss :-(.

bytedev · Accepted Answer · 2020-01-28 03:33:15Z

41

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, 2020 at 3:33

answered Sep 30, 2019 at 10:13

bytedev

9,2384 gold badges56 silver badges62 bronze badges

2 Comments

Kapé Over a year ago

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

bytedev Over a year ago

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.

DLeh · Accepted Answer · 2022-11-01 13:34:38Z

6

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>

answered Nov 1, 2022 at 13:34

DLeh

24.6k17 gold badges95 silver badges141 bronze badges

Collectives™ on Stack Overflow

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

3 Answers 3

3 Comments

2 Comments

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

3 Answers 3

3 Comments

2 Comments

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related