Missing xml documentation for targeting packs

[omajid]

The targeting packs in .NET 5 include the assemblies (.dll files) and documentation (.xml) files. For example, the Microsoft.NETCore.App.Ref targeting pack includes System.Collections.dll as well as System.Collections.xml (the documentation).

$ tar tf dotnet-microsoft-built-sdk-5.0.100-rc.1.20452.10.tar.gz | grep 'Microsoft.NETCore.App.Ref.*System.Collections.[a-z]'
./packs/Microsoft.NETCore.App.Ref/5.0.0-rc.1.20451.14/ref/net5.0/System.Collections.dll
./packs/Microsoft.NETCore.App.Ref/5.0.0-rc.1.20451.14/ref/net5.0/System.Collections.xml

But this information is missing for some packages, such as System.IO.Pipelines

$ tar tf dotnet-microsoft-built-sdk-5.0.100-rc.1.20452.10.tar.gz | grep System.IO.Pipelines
./packs/Microsoft.NETCore.App.Ref/5.0.0-rc.1.20451.14/ref/net5.0/System.IO.Pipelines.dll
./shared/Microsoft.NETCore.App/5.0.0-rc.1.20451.14/System.IO.Pipelines.dll

Originally reported at dotnet/source-build#1686

[dagood]

This belongs in dotnet/runtime--I confirmed System.IO.Pipelines.xml also doesn't exist in https://www.nuget.org/packages/Microsoft.NETCore.App.Ref/5.0.0-rc.1.20451.14, which dotnet/sdk has no hand in. (Targeting packs are produced from the same repo as the runtime pack + runtime that matches it.)

[ghost]

Tagging subscribers to this area: @buyaa-n, @krwq, @jeffhandley
See info in area-owners.md if you want to be subscribed.

[BrennanConroy]

Pipelines isn't in NetCore.App anymore, but this is an issue in AspNetCore.App

[BrennanConroy]

cc @Pilchie This might be something we want to do for RTM

[omajid]

@BrennanConroy are you sure about aspnet vs runtime? Preview 7 (your screenshot) says this is in AspNetCore.App, but in RC1, this is in NETCore.App. Did it move again after RC1?

[Pilchie]

Yes, it moved back to AspNetCore.App after RC1.

@dotnet/aspnet-build can someone take a look?

[dougbu]

1. See from the 3.0.1 and 3.1.8 copies of Microsoft.AspNetCore.App.Ref that this is not a regression
2. Same problem applies to all ref/ assemblies that we do not get from the Microsoft.Extensions.Internal.Transport bundle (those are fine)
3. System.IO.Pipelines package (for example) does not contain an XML file in the same folder as the ref/ assembly

@ericstj should number 3 be false i.e. should the doc file be in the same folder as the ref/ assembly❔ If not, the project creating the bundles for our targeting packs may be able to hack something using the implementation assemblies but I'm not positive all are visible in that project.

[ericstj]

This appears to be a regression from 3.1 in the case of System.IO.Pipelines. In 3.1 we included (and should include) reference XML next to reference assembly. Are you seeing the same for all packages, or just Pipelines? I checked System.Diagnositcs.EventLog and Registry and they looked OK to me. I opened a bug to track the Pipelines issue: dotnet/runtime#42479

I think you should be fine to pull the XML from the nuget package for the others, and we should fix this for pipelines.

[dagood]

• See from the 3.0.1 and 3.1.8 copies of Microsoft.AspNetCore.App.Ref that this is not a regression

I filed #26068 about this for 3.1.8, it seems like a bug. We also saw it in 3.1.3 but didn't quite report it here in aspnetcore at the time.

[dougbu]

@ericstj I didn't check the other packages. Thanks. So, System.IO.Pipelines is a separate case that'll require a dotnet/runtime fix to enable the scenario to be patched up.

The larger issue is: We never had the correct msbuild gobbledygook to get the XML files from the packages where we get "loose" ref/ assemblies. But, we can add that code in a generic way (I hope) and pick up the documentation from all ~12 packages we reference. Shouldn't be too difficult since we include their ref/ assemblies in Microsoft.AspNetCore.App.Ref and the XML files will (soon) all sit beside those assemblies.

[dougbu]

@dagood back-porting the fix to 3.1 for #26068 shouldn't be horrendous.

[dougbu]

@Pilchie I'm not going to get to this 'til Monday and doubt other @dotnet/aspnet-build members are hankering for a weekend project. That puts this into 3.1.10 and 5.0 RTM. Am I correct bot fixes should meet the bar given the missing documentation files worsen the ASP.NET Core development experience in every IDE on every platform❔

[wtgodbe]

Looking at this today

[dougbu]

@wtgodbe I believe this issue can be closed. We can use #26068 to track your 3.1 change. Correct❔

[wtgodbe]

Yes