Add new output DebugSymbolsFiles to ResolvePackageAssets

DebugSymbolsFiles outputs the list of absolute path to symbols files
for runtime assemblies which can be either pdb and/or xml.

The change:
ResolvePackagesAssets was modified to read/write DebugSymbolsFiles
from/to the cache file and it was inserted after ContentFilesToProcess
because the list of Item groups is ordered alphabetically.

Since we need to copy this debug symbols to the output director,
the task parameter output for DebugSymbolsFiles is appended to
ReferenceCopyLocalPaths.

There is some minor code cleanup not related to this bug.

Author: ocalles

src/Tasks/Common/MetadataKeys.cs

@@ -131,5 +131,12 @@ internal static class MetadataKeys
         public const string IsVersion5 = "IsVersion5";
         public const string CreateCompositeImage = "CreateCompositeImage";
         public const string PerfmapFormatVersion = "PerfmapFormatVersion";
+
+        // Debug symbols
+        public const string RelatedProperty = "related";
+        public const string XmlExtension = ".xml";
+        public const string XmlFilePath = "XmlFilePath";
+        public const string PdbExtension = ".pdb";
+        public const string PdbFilePath = "PdbFilePath";
     }
 }

src/Tasks/Microsoft.NET.Build.Tasks/ResolvePackageAssets.cs

@@ -12,7 +12,6 @@
 using Microsoft.Build.Framework;
 using Microsoft.Build.Utilities;
 using NuGet.Common;
-using NuGet.Frameworks;
 using NuGet.ProjectModel;
 using NuGet.Versioning;
 
@@ -156,8 +155,16 @@ public sealed class ResolvePackageAssets : TaskBase
         [Required]
         public string DotNetAppHostExecutableNameWithoutExtension { get; set; }
 
+        /// <summary>
+        /// True indicates we are doing a design-time build. Otherwise we are in a build.
+        /// </summary>
         public bool DesignTimeBuild { get; set; }
 
+        /// <summary>
+        /// Enable publishing XML documentation
+        /// </summary>
+        public bool PublishReferencesDocumentationFiles { get; set; }
+
         /// <summary>
         /// Full paths to assemblies from packages to pass to compiler as analyzers.
         /// </summary>
@@ -231,6 +238,24 @@ public sealed class ResolvePackageAssets : TaskBase
         [Output]
         public ITaskItem[] PackageDependencies { get; private set; }
 
+        /// <summary>
+        /// List of symbol files (.pdb) related to NuGet packages.
+        /// </summary>
+        /// <remarks>
+        /// Pdb files to be copied to the output directory
+        /// </remarks>
+        [Output]
+        public ITaskItem[] DebugSymbolsFiles { get; private set;}
+
+        /// <summary>
+        /// List of xml files related to NuGet packages.
+        /// </summary>
+        /// <remarks>
+        ///  The XML files should only be included in the publish output if PublishReferencesDocumentationFiles is true
+        /// </remarks>
+        [Output]
+        public ITaskItem[] DebugXmlFiles { get; private set; }
+
         /// <summary>
         /// Messages from the assets file.
         /// These are logged directly and therefore not returned to the targets (note private here).
@@ -311,6 +336,8 @@ private void ReadItemGroups()
                 ApphostsForShimRuntimeIdentifiers = reader.ReadItemGroup();
                 CompileTimeAssemblies = reader.ReadItemGroup();
                 ContentFilesToPreprocess = reader.ReadItemGroup();
+                DebugSymbolsFiles = reader.ReadItemGroup();
+                DebugXmlFiles = reader.ReadItemGroup();
                 FrameworkAssemblies = reader.ReadItemGroup();
                 FrameworkReferences = reader.ReadItemGroup();
                 NativeLibraries = reader.ReadItemGroup();
@@ -443,6 +470,7 @@ internal byte[] HashSettings()
                     }
                     writer.Write(TargetFramework);
                     writer.Write(VerifyMatchingImplicitPackageVersion);
+                    writer.Write(PublishReferencesDocumentationFiles);
                 }
 
                 stream.Position = 0;
@@ -510,7 +538,7 @@ private static BinaryReader CreateReaderFromDisk(ResolvePackageAssets task, byte
                 BinaryReader reader = null;
                 try
                 {
-                    if (File.GetLastWriteTimeUtc(task.ProjectAssetsCacheFile) > File.GetLastWriteTimeUtc(task.ProjectAssetsFile))
+                    if (IsCacheFileUpToDate())
                     {
                         reader = OpenCacheFile(task.ProjectAssetsCacheFile, settingsHash);
                     }
@@ -537,6 +565,8 @@ private static BinaryReader CreateReaderFromDisk(ResolvePackageAssets task, byte
                 }
 
                 return reader;
+
+                bool IsCacheFileUpToDate() => File.GetLastWriteTimeUtc(task.ProjectAssetsCacheFile) > File.GetLastWriteTimeUtc(task.ProjectAssetsFile);
             }
 
             private static BinaryReader OpenCacheStream(Stream stream, byte[] settingsHash)
@@ -651,6 +681,8 @@ internal sealed class CacheWriter : IDisposable
 
             private const string NetCorePlatformLibrary = "Microsoft.NETCore.App";
 
+            private const char RelatedPropertySeparator = ';';
+
             public CacheWriter(ResolvePackageAssets task)
             {
                 _targetFramework = task.TargetFramework;
@@ -776,6 +808,8 @@ private void WriteItemGroups()
                 WriteItemGroup(WriteApphostsForShimRuntimeIdentifiers);
                 WriteItemGroup(WriteCompileTimeAssemblies);
                 WriteItemGroup(WriteContentFilesToPreprocess);
+                WriteItemGroup(WriteDebugSymbolsFiles);
+                WriteItemGroup(WriteDebugXmlFiles);
                 WriteItemGroup(WriteFrameworkAssemblies);
                 WriteItemGroup(WriteFrameworkReferences);
                 WriteItemGroup(WriteNativeLibraries);
@@ -1091,6 +1125,57 @@ private void WriteContentFilesToPreprocess()
                     });
             }
 
+            private void WriteDebugSymbolsFiles()
+            {
+                WriteDebugItems(
+                    p => p.RuntimeAssemblies,
+                    MetadataKeys.PdbExtension);
+            }
+
+            private void WriteDebugXmlFiles()
+            {
+                if (_task.PublishReferencesDocumentationFiles)
+                {
+                    WriteDebugItems(
+                        p => p.CompileTimeAssemblies,
+                        MetadataKeys.XmlExtension);
+                }
+            }
+
+            private void WriteDebugItems<T>(
+                Func<LockFileTargetLibrary, IEnumerable<T>> getAssets,
+                string extension)
+                where T : LockFileItem
+            {
+                foreach (var library in _runtimeTarget.Libraries)
+                {
+                    if (!library.IsPackage())
+                    {
+                        continue;
+                    }
+
+                    foreach (T asset in getAssets(library))
+                    {
+                        if (asset.IsPlaceholderFile() || !asset.Properties.ContainsKey(MetadataKeys.RelatedProperty))
+                        {
+                            continue;
+                        }
+
+                        string itemSpec = _packageResolver.ResolvePackageAssetPath(library, asset.Path);
+
+                        asset.Properties.TryGetValue(MetadataKeys.RelatedProperty, out string relatedExtensions);
+
+                        foreach (string fileExtension in relatedExtensions.Split(RelatedPropertySeparator))
+                        {
+                            if (fileExtension.ToLower() == extension)
+                            {
+                                WriteItem(Path.ChangeExtension(itemSpec, extension), library);
+                            }
+                        }
+                    }
+                }
+            }
+
             private void WriteFrameworkAssemblies()
             {
                 if (_task.DisableFrameworkAssemblies)

src/Tasks/Microsoft.NET.Build.Tasks/targets/Microsoft.PackageDependencyResolution.targets

@@ -290,13 +290,16 @@ Copyright (c) .NET Foundation. All rights reserved.
       SatelliteResourceLanguages="$(SatelliteResourceLanguages)"
       DesignTimeBuild="$(DesignTimeBuild)"
       ContinueOnError="$(ContinueOnError)"
-      PackageReferences="@(PackageReference)">
+      PackageReferences="@(PackageReference)"
+      PublishReferencesDocumentationFiles="$(PublishReferencesDocumentationFiles)">
 
       <!-- NOTE: items names here are inconsistent because they match prior implementation
           (that was spread across different tasks/targets) for backwards compatibility.  -->
       <Output TaskParameter="Analyzers" ItemName="ResolvedAnalyzers" />
       <Output TaskParameter="ApphostsForShimRuntimeIdentifiers" ItemName="_ApphostsForShimRuntimeIdentifiersResolvePackageAssets" />
       <Output TaskParameter="ContentFilesToPreprocess" ItemName="_ContentFilesToPreprocess" />
+      <Output TaskParameter="DebugSymbolsFiles" ItemName="ReferenceCopyLocalPaths" />
+      <Output TaskParameter="DebugXmlFiles" ItemName="ReferenceCopyLocalPaths" />
       <Output TaskParameter="FrameworkAssemblies" ItemName="ResolvedFrameworkAssemblies" />
       <Output TaskParameter="FrameworkReferences" ItemName="TransitiveFrameworkReference" />
       <Output TaskParameter="NativeLibraries" ItemName="NativeCopyLocalItems" />