Documentation disappears in NuGet package

Question

I wrote a class library in C# that I need to push to a private NuGet server (v3.4.1.0). I decorated my classes and methods with XML documentation comments.

XML documentation file option is checked on the Build tab of the project properties panel, the project builds successfully and the xml file gets generated on the project's root folder with the same name as the assembly.

In the .csproj file the related section looks like this:

<PropertyGroup>
  <DocumentationFile>absolutePathTo\assemblyName.xml</DocumentationFile>
</PropertyGroup>

IntelliSense (VS2019 16.9.0) recognises the documentation and shows it properly even in other projects under the same solution.

When I generate the NuGet package it gets created in the project's bin\Debug folder. If I open it as a zip archive the DLL and the documentation XML can be found in the lib\netstandard2.1 folder having matching names.

Once I install this package to another project from the private NuGet server it works properly but loses the complete documentation. IntelliSense does not show my comments anymore and the assembly metadata seems not to have it either.

Could anyone support me on this one?

Answer 1

That is normal. For xml document, it is special under new-sdk style projects. The xml document could only be copied into the non-sdk net framework projects but new-sdk net core projects cannot. More similar to this issue I handled before.

So you should try these steps additionally to get what you want:

1) enter these node under csproj file of your nuget project.

<ItemGroup>
        <None Include="xxx\absolutePathTo\assemblyName.xml"(the path of the xml file under your project folder) Pack="true">
            <PackageCopyToOutput>true</PackageCopyToOutput>
        </None>
</ItemGroup>

2) after that, re-pack your nuget project and before you install the new version, please clean nuget caches first or just delete all files under C:\Users\xxx\.nuget\packages

Answer 2

Personally, I let Visual Studio handle things for me. If you right-click in the project, and choose Properties, In the Build -> Output area, you should see a checkbox under Documentation file labelled Generate a file containing API documentation.. When you check this, a new option appears underneath: XML documentation file path. But the file selector is labelled Optional path for the API documentation file. Leave blank to use the default location..

FYI: The default location is alongside your EXE / DLL that is generated when you build your project.

When you next build your code (for anyone else reading, I assume you've got the Generate NuGet package on build in the Package area checked too) it will also package up the XML documentation into the NuGet package generated.

From the perspective of users of this new package, Visual Studio will pick up on the XML Documentation inside.