9

I am using a NuGet package which has an XML documentation file.

But when I include the package in a .NET Core 2.2 app, the comments are not available with IntelliSense.

Is there something I'm missing either in the package or in my app to be able to see the documentation with IntelliSense?

Using VisualStudio 2017, Windows 10.

Update for Clarity

The NuGet package is a .NET Standard 1.3 class library. In Visual Studio when I build the project, I include the options to generate the package and documentation file. In the project file, I see the following PropertyGroup:

<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'">
    <DocumentationFile>C:\Users\[username]\[local path]\CommonEntities\CommonEntities\CommonEntities.xml</DocumentationFile>
</PropertyGroup>

When I open the package, I can see in the lib/netstandard1.3/ directory that CommonEntities.xml is included along with MakanalTech.CommonEntities.dll.

But, I'm wondering why the xml file has dropped the full name from MakanalTech.CommonEntities.xml as it is in the project to just CommonEntities.xml in the package. Maybe this is the cause of the issue?

The issue is then when I include the package as a dependency in another project, none of the XML comments/documentation are visible. So I can't hover over a type to see its description, and if I peek definition none of the comments/documentation are in the definition.

Class Library Product https://i.stack.imgur.com/oBk0v.jpg (can't post images yet)

Peeking at definition from other project: https://i.stack.imgur.com/62dYO.jpg

kmcconnell
  • 331
  • 4
  • 14
  • Hi, what do you mean the comments not available with intellisense, could you please share how did you invoke it? If you want to display the XML documentation file inside you application, please check this similar issue: https://stackoverflow.com/questions/52880687/how-to-share-source-code-via-nuget-packages-for-use-in-net-core-projects/52885223#52885223 , replace xx.cs file with the XML documentation file. – Sara Liu - MSFT Oct 22 '18 at 08:50
  • When I build and pack the project in Visual Studio, I include the checkbox to generate the documentation file. So the XML file is in the project and included in the .csproj file. However, I now see the DocumentationFile reference is local only to my machine which is pointless for anyone else using the project. I will take as look at the latest package to see what it contains in the .nuspec file. I am just using Visual Studio to pack the project and not creating it manually. So my assumption is that it's packing everything it needs and I don't need to manually edit the .nuspec every release. – kmcconnell Oct 23 '18 at 09:41
  • I updated the question with what I see is actually happening. – kmcconnell Oct 23 '18 at 14:50

2 Answers2

11

Finally found the issue from this post. This seems quite buggy from Visual Studio 2017 not to handle this correctly and automatically.

In the .csproj file, I removed <DocumentationFile>[filepath-to-xml]</DocumentationFile> and added <GenerateDocumentationFile>true</GenerateDocumentationFile>.

I then repacked the library, cleared my nuget cache, and rebuilt the new project where it's included, and now I have all the XML documentation visible.

kmcconnell
  • 331
  • 4
  • 14
2

NuGet package XML documentation not visible in .NET Core 2.2 app

Just like what have you found that "in the lib/netstandard1.3/ directory that CommonEntities.xml is included along with MakanalTech.CommonEntities.dll.", the .xml file in the lib folder, then according to the document From a convention-based working directory:

enter image description here

Only the .dll file will be added as reference, .xml file will be copied to the project folder. That is the reason why the XML documentation not visible in .NET Core 2.2 app.

Besides, since you are using .netstandard project, .xml file will blocked be copied to the project folder automatically by the nuget issue 4837.

To resolve this issue, we have to create the .nuspec file with option contentFiles to include the .xml file and add this file to the project, please check the detail info from other thread.

But if you do not want to manually edit the .nuspec every release, you can use a post-build event to pack the nuget package automatically,like:

nuget pack "$(.NuspecFilePath)\xxx.nuspec"

Or you can add the .xml file to the project manually from the package directly, that package is in the path: C:\Users\<UserName>\.nuget\packages.

Hope this helps.

Leo Liu
  • 71,098
  • 10
  • 114
  • 135
  • 1
    I don't quite follow what you're saying, but it did lead me down some extra search paths to [this](https://stackoverflow.com/a/48664173) answer. – kmcconnell Oct 25 '18 at 10:01