Add output DebugSymbolsFiles to ResolvePackageAssets

[ocallesp]

fixes #1458

DebugSymbolsFiles outputs the list of absolute path to symbols files (.pdb) from runtime assemblies.
ReferenceDocumentationFiles outputs the list of absolute path to xml files that enables debugging features.

The change:
Added DebugSymbolsFiles and ReferenceDocumentationFiles and ResolvePackagesAssets was modified to read/write DebugSymbolsFiles and ReferenceDocumentationFiles from/to the cache file.

The debug symbols files will be copied to the output directory when CopyDebugSymbolFilesFromPackages quals to true.

The reference documentation files will be copied to the output directory when CopyDocumentationFilesFromPackages quals to true.

---

For manual testing, I was using this sample project #1383 and checking that the pdb are copied to the output directory of the consumer.

[dsplaisted]

Thanks @ocallesp, this is a good start. Can you rebase and retarget this PR to the release/7.0.1xx branch?

Other feedback:

• I think there should be separate output items on the task for the PDB and XML files. The XML files should only be included in the publish output if PublishReferencesDocumentationFiles is true (I think that for the build output they should always be included).
• The XML files should come from the compile assets in the project.assets.json file, not the runtime assets.

Here's a sample assets file:

  "targets": {
    "net7.0": {
      "LibraryTest/1.0.0": {
        "type": "package",
        "compile": {
          "ref/net7.0/LibraryTest.dll": {
            "related": ".xml"
          }
        },
        "runtime": {
          "lib/net7.0/LibraryTest.dll": {
            "related": ".pdb"
          }
        }
      },
      "Newtonsoft.Json/4.5.4": {
        "type": "package",
        "compile": {
          "lib/net40/Newtonsoft.Json.dll": {
            "related": ".pdb;.xml"
          }
        },
        "runtime": {
          "lib/net40/Newtonsoft.Json.dll": {
            "related": ".pdb;.xml"
          }
        }
      }
    }
  },

[ocallesp]

Thanks @ocallesp, this is a good start. Can you rebase and retarget this PR to the release/7.0.1xx branch?

Other feedback:

• I think there should be separate output items on the task for the PDB and XML files. The XML files should only be included in the publish output if PublishReferencesDocumentationFiles is true (I think that for the build output they should always be included).
• The XML files should come from the compile assets in the project.assets.json file, not the runtime assets.

Here's a sample assets file:

  "targets": {
    "net7.0": {
      "LibraryTest/1.0.0": {
        "type": "package",
        "compile": {
          "ref/net7.0/LibraryTest.dll": {
            "related": ".xml"
          }
        },
        "runtime": {
          "lib/net7.0/LibraryTest.dll": {
            "related": ".pdb"
          }
        }
      },
      "Newtonsoft.Json/4.5.4": {
        "type": "package",
        "compile": {
          "lib/net40/Newtonsoft.Json.dll": {
            "related": ".pdb;.xml"
          }
        },
        "runtime": {
          "lib/net40/Newtonsoft.Json.dll": {
            "related": ".pdb;.xml"
          }
        }
      }
    }
  },

If we apply this change to release/7.0.1xx branch, does the pipeline/insertions also apply this change to main ?

[dsplaisted]

If we apply this change to release/7.0.1xx branch, does the pipeline/insertions also apply this change to main ?

Yes, the code will eventually flow forward to later branches.

[dsplaisted]

Looking good so far.

[ocallesp]

@dsplaisted
Copying pdb and xml to output and publish directories are now disable by default.

• The debug symbols files will be copied to the output directory when CopyDebugSymbolFilesFromPackages quals to true.

• The reference documentation files will be copied to the output directory when CopyDocumentationFilesFromPackages quals to true.

[ocallesp]

@dsplaisted changes done as suggested.

[dsplaisted]

Looking very good, and pretty close to done I think. Thanks!

[dsplaisted]

@baronfel, What do you think about the property names CopyDebugSymbolFilesFromPackages and CopyDocumentationFilesFromPackages? Should we consider something like CopyPdbFilesFromPackages and CopyXmlFilesFromPackages? The current names try to match the existing PublishReferencesDocumentationFiles property.

Also pinging @dotnet/dotnet-cli in case anyone else has feedback.

[baronfel]

I'm ok with the current names - I'd rather align with the existing terminology to stay consistent. The PublishDocumentationFile(s) and PublishReferencesDocumentationFiles properties don't seem to be documented yet, so when this changes I'll bundle documenting them and these new properties in a single PR to dotnet/docs so that we're up-to-date and maybe get some SEO on the change.

I also agree with the plan to not enable the flag by default in this release, due to timing. We should explore turning it on for 7.0.200 and beyond, though - I think the existence of the PublishReferencesDocumentationFiles property and it being set to true by default is a strong enough signal to change this mid-release-cycle rather than waiting for the 8.0.x SDK series.

[dsplaisted]

2 minor comments, looks good otherwise.

[dsplaisted]

This should probably use invariant comparison

Suggested change

	if (fileExtension.ToLower() == extension)
	if (fileExtension.ToLowerInvariant() == extension)

[dsplaisted]

This isn't really the right error message here. Do we need to log a warning at all here?