Adding an item list with the list of copied files from CopyArtifacts target (#617)

MatthieuMEZIL · web-flow · commit 92245f658668 · 2025-04-25T13:01:10.000-07:00
* Adding an item list with the list of copied files from CopyArtifacts target

* Addressing PR comments:
- Simplifying the usage for customers
- Updating the documentation
diff --git a/src/Artifacts.UnitTests/ArtifactsTests.cs b/src/Artifacts.UnitTests/ArtifactsTests.cs
@@ -304,6 +304,40 @@ public void InvalidDestinationFolderShouldLogAnErrorRegardingDestinationFolder()
             Assert.Contains($"Failed to expand the path \"{artifactPaths}", consoleLog);
         }
 
+        [Theory]
+        [InlineData(null)]
+        [InlineData("")]
+        [InlineData("SomethingCustom", true)]
+        public void ListCopiedFiles(string itemName, bool expectListCopiedFiles = false)
+        {
+            CreateFiles(
+                Path.Combine("bin", "Debug"),
+                "foo.dll",
+                "foo.pdb");
+
+            DirectoryInfo artifactsPath = new DirectoryInfo(Path.Combine(TestRootPath, "artifacts"));
+
+            string outputPath = $"{Path.Combine("bin", "Debug")}{Path.DirectorySeparatorChar}";
+
+            ProjectCreator.Templates.ProjectWithArtifacts(
+                path: Path.Combine(TestRootPath, "ProjectA.csproj"),
+                outputPath: outputPath,
+                artifactsPath: artifactsPath.FullName,
+                copiedArtifactsItemName: itemName)
+                    .Target("LogCopiedFiles", afterTargets: "CopyArtifacts")
+                        .TaskMessage($"{itemName} contains %({itemName}.Identity)")
+                    .Save()
+                    .TryBuild(out bool result, out BuildOutput buildOutput)
+                    .TryGetPropertyValue("ListCopiedFilesCount", out string listCopiedFilesCount);
+
+            result.ShouldBeTrue(buildOutput.GetConsoleLog());
+
+            if (expectListCopiedFiles)
+            {
+                buildOutput.Messages.ShouldContain(i => i.StartsWith($"{itemName} contains"));
+            }
+        }
+
         [Theory]
         [InlineData(null)]
         [InlineData(true)]
diff --git a/src/Artifacts.UnitTests/CustomProjectCreatorTemplates.cs b/src/Artifacts.UnitTests/CustomProjectCreatorTemplates.cs
@@ -44,6 +44,7 @@ public static ProjectCreator ProjectWithArtifacts(
                     string artifactsPath = null,
                     string targetFramework = "net472",
                     bool? appendTargetFrameworkToOutputPath = true,
+                    string copiedArtifactsItemName = null,
                     Action<ProjectCreator> customAction = null,
                     string path = null,
                     string defaultTargets = null,
@@ -70,6 +71,7 @@ public static ProjectCreator ProjectWithArtifacts(
                 .Property("AppendTargetFrameworkToOutputPath", appendTargetFrameworkToOutputPath.HasValue ? appendTargetFrameworkToOutputPath.ToString() : null)
                 .Property("OutputPath", $"$(OutputPath)$(TargetFramework.ToLowerInvariant()){Path.DirectorySeparatorChar}", condition: "'$(AppendTargetFrameworkToOutputPath)' == 'true'")
                 .Property("ArtifactsPath", artifactsPath)
+                .Property("ArtifactsCopiedFilesItemName", copiedArtifactsItemName)
                 .CustomAction(customAction)
                 .Target("Build")
                 .Target("AfterBuild", afterTargets: "Build")
diff --git a/src/Artifacts.UnitTests/RobocopyTests.cs b/src/Artifacts.UnitTests/RobocopyTests.cs
@@ -825,6 +825,70 @@ public void CoWExceptionFallsBackToCopy(bool win32ExWithSharingViolation)
                     customMessage: buildEngine.GetConsoleLog());
         }
 
+        [Fact]
+        public void ListCopiedFilesIsOffByDefault()
+        {
+            DirectoryInfo source = CreateFiles("source", "bar.txt");
+
+            DirectoryInfo destination = new DirectoryInfo(Path.Combine(TestRootPath, "destination"));
+            BuildEngine buildEngine = BuildEngine.Create();
+
+            Robocopy copyArtifacts = new ()
+            {
+                BuildEngine = buildEngine,
+                Sources =
+                [
+                    new MockTaskItem(source.FullName)
+                    {
+                        ["DestinationFolder"] = destination.FullName,
+                        [nameof(RobocopyMetadata.IsRecursive)] = "false",
+                    },
+                ],
+                Sleep = _ => { },
+            };
+
+            copyArtifacts.Execute().ShouldBeTrue(buildEngine.GetConsoleLog());
+            copyArtifacts.NumFilesCopied.ShouldBe(1);
+
+            copyArtifacts.CopiedFiles.Length.ShouldBe(0);
+        }
+
+        [Fact]
+        public void ListCopiedFilesCanBeEnabled()
+        {
+            DirectoryInfo source = CreateFiles(
+                "source",
+                "bar.txt",
+                "foo.txt");
+
+            DirectoryInfo destination = new DirectoryInfo(Path.Combine(TestRootPath, "destination"));
+            BuildEngine buildEngine = BuildEngine.Create();
+
+            Robocopy copyArtifacts = new ()
+            {
+                BuildEngine = buildEngine,
+                Sources =
+                [
+                    new MockTaskItem(source.FullName)
+                    {
+                        ["DestinationFolder"] = destination.FullName,
+                        [nameof(RobocopyMetadata.IsRecursive)] = "false",
+                    },
+                ],
+                ListCopiedFiles = true,
+                Sleep = _ => { },
+            };
+
+            copyArtifacts.Execute().ShouldBeTrue(buildEngine.GetConsoleLog());
+            copyArtifacts.NumFilesCopied.ShouldBe(2);
+
+            copyArtifacts.CopiedFiles.Length.ShouldBe(2);
+            copyArtifacts.CopiedFiles.All(
+                f => new[] { "foo.txt", "bar.txt" }.Any(
+                    fileName => f.ItemSpec == Path.Combine(destination.FullName, fileName)
+                                && f.GetMetadata("SourceFile") == Path.Combine(source.FullName, fileName))).ShouldBeTrue();
+        }
+
         private sealed class MockFileSystem : IFileSystem
         {
             private int _numCloneFileCalls;
diff --git a/src/Artifacts/README.md b/src/Artifacts/README.md
@@ -150,6 +150,7 @@ The following properties control artifacts staging:
 | `ArtifactsShowDiagnostics` | Enables additional logging that can be used to troubleshoot why artifacts are not being staged | `false` |
 | `ArtifactsShowErrorOnRetry` | Logs an error if a retry was attempted.  Disable this to suppress issues while copying files | `true` |
 | `DisableCopyOnWrite` | Disables use of copy-on-write links (file cloning) even if the filesystem allows it. | `false` |
+| `ArtifactsCopiedFilesItemName` | Specifies an item name which receives the list of files that were copied. | |
 | `CustomBeforeArtifactsProps ` | A list of custom MSBuild projects to import **before** artifacts properties are declared. |
 | `CustomAfterArtifactsProps` | A list of custom MSBuild projects to import **after** Artifacts properties are declared.|
 | `CustomBeforeArtifactsTargets` | A list of custom MSBuild projects to import **before** Artifacts targets are declared.|
@@ -166,6 +167,20 @@ To change the default file match for artifacts, set the `DefaultArtifactsFileMat
 
 <br />
 
+To get the list of copied files, set the `ArtifactsCopiedFiles` property:
+```xml
+<PropertyGroup>
+  <ArtifactsCopiedFilesItemName>MyCopiedArtifact</ArtifactsCopiedFilesItemName>
+</PropertyGroup>
+
+<Target Name="LogAllCopiedArtifacts" AfterTargets="CopyArtifacts">
+  <Message Text="Copied @(MyCopiedArtifact->Count()) artifact(s):" />
+  <Message Text="  %(MyCopiedArtifact.Identity)" />
+</Target>
+```
+
+<br />
+
 The `<Artifact />` items specify collections of artifacts to stage.  These items have the following metadata:
 
 | Metadata | Description | Default |
diff --git a/src/Artifacts/Tasks/Robocopy.cs b/src/Artifacts/Tasks/Robocopy.cs
@@ -36,6 +36,7 @@ public class Robocopy : Task
         private readonly ConcurrentDictionary<string, Dictionary<string, FileInfo>> _destinationDirectoryFilesCopying = new (concurrencyLevel: 1, capacity: 31, Artifacts.FileSystem.PathComparer);  // Map for destination directories to track files being copied there in parallel portion of copy. Concurrent dictionaries to get TryAdd(), GetOrAdd().
         private readonly ActionBlock<CopyJob> _copyFileBlock;
         private readonly HashSet<string> _sourceFilesEncountered = new (Artifacts.FileSystem.PathComparer);  // Reusable scratch space
+        private readonly ConcurrentBag<ITaskItem> _copiedFiles = new ();
 
         private TimeSpan _retryWaitInMilliseconds = TimeSpan.Zero;
         private int _numFilesCopied;
@@ -78,6 +79,18 @@ public Robocopy()
         [Required]
         public ITaskItem[] Sources { get; set; } = Array.Empty<ITaskItem>();
 
+        /// <summary>
+        /// Gets or sets a value indicating whether to collect the list of copied files.
+        /// When false, the CopiedFiles output parameter will be empty.
+        /// </summary>
+        public bool ListCopiedFiles { get; set; }
+
+        /// <summary>
+        /// Gets the list of files that were successfully copied.
+        /// </summary>
+        [Output]
+        public ITaskItem[] CopiedFiles => _copiedFiles.ToArray();
+
         /// <summary>
         /// Gets or sets a value indicating whether to disable copy-on-write linking if the links are available.
         /// </summary>
@@ -266,6 +279,14 @@ private void CopyFileImpl(FileInfo sourceFile, FileInfo destFile, RobocopyMetada
                         destFile.Attributes = FileAttributes.Normal;
                         destFile.LastWriteTimeUtc = sourceFile.LastWriteTimeUtc;
                         Log.LogMessage("{0} {1}{2} to {3}", cowLinked ? "Created copy-on-write link" : "Copied", originalSourcePath, replacementSourceFile is null ? string.Empty : $" (actually {replacementSourceFile.FullName})", destPath);
+
+                        if (ListCopiedFiles)
+                        {
+                            TaskItem copiedFile = new (destPath);
+                            copiedFile.SetMetadata("SourceFile", originalSourcePath);
+                            _copiedFiles.Add(copiedFile);
+                        }
+
                         Interlocked.Increment(ref _numFilesCopied);
                     }
                     else
diff --git a/src/Artifacts/build/Microsoft.Build.Artifacts.Common.targets b/src/Artifacts/build/Microsoft.Build.Artifacts.Common.targets
@@ -27,14 +27,20 @@
           Condition="'$(EnableArtifacts)' != 'false'"
           AfterTargets="$([MSBuild]::ValueOrDefault($(CopyArtifactsAfterTargets), 'AfterBuild'))"
           DependsOnTargets="$(CopyArtifactsDependsOn)">
+    <PropertyGroup>
+      <_ArtifactsListCopiedFiles Condition="'$(ArtifactsCopiedFilesItemName)' != ''">true</_ArtifactsListCopiedFiles>
+    </PropertyGroup>
     <Robocopy
       RetryCount="$([MSBuild]::ValueOrDefault($(ArtifactsCopyRetryCount), $(CopyRetryCount)))"
       RetryWait="$([MSBuild]::ValueOrDefault($(ArtifactsCopyRetryDelayMilliseconds), $(CopyRetryDelayMilliseconds)))"
       ShowDiagnosticTrace="$(ArtifactsShowDiagnostics)"
       ShowErrorOnRetry="$([MSBuild]::ValueOrDefault($(ArtifactsShowErrorOnRetry), 'true'))"
       DisableCopyOnWrite="$([MSBuild]::ValueOrDefault($(DisableCopyOnWrite), 'false'))"
       Sources="@(Artifact)"
-      Condition="@(Artifact->Count()) > 0" />
+      ListCopiedFiles="$(_ArtifactsListCopiedFiles)"
+      Condition="@(Artifact->Count()) > 0">
+        <Output TaskParameter="CopiedFiles" ItemName="$(ArtifactsCopiedFilesItemName)" Condition="'$(ArtifactsCopiedFilesItemName)' != ''" />
+      </Robocopy>
   </Target>
 
   <Target Name="RobocopyFiles"
@@ -48,6 +54,9 @@
       ShowErrorOnRetry="$([MSBuild]::ValueOrDefault($(RobocopyShowErrorOnRetry), 'true'))"
       DisableCopyOnWrite="$([MSBuild]::ValueOrDefault($(DisableCopyOnWrite), 'false'))"
       Sources="@(Robocopy)"
-      Condition="@(Robocopy->Count()) > 0"/>
+      ListCopiedFiles="$(_ArtifactsListCopiedFiles)"
+      Condition="@(Robocopy->Count()) > 0">
+      <Output TaskParameter="CopiedFiles" ItemName="$(ArtifactsCopiedFilesItemName)" Condition="'$(ArtifactsCopiedFilesItemName)' != ''" />
+      </Robocopy>
   </Target>
 </Project>
