Merge branch 'main' into darc-main-476ee6a5-de68-485b-811e-e4d207ff5a3e

mthalman · web-flow · commit a6223e97fa18 · 2026-03-10T15:13:52.000-05:00
diff --git a/.github/instructions/csharp.instructions.md b/.github/instructions/csharp.instructions.md
@@ -10,12 +10,18 @@ For all new C# code:
 
 - Use file-scoped namespaces.
 - Use collection expresions - write `[1, 2, 3]` and not `new List<int> { 1, 2, 3 }`.
-- Use `var` for local variable declarations.
+- Use explicit type declarations instead of `var` for local variables.
 - Use switch expressions and pattern matching.
 - Use string interpolation (`$"Hello, {name}!"`) instead of `string.Format` or concatenation.
 - Use `"""triple-quoted strings"""` for multi-line string literals. These can be interpolated as well.
 - Use expression-bodied members for simple getters and setters.
 
+## Naming
+
+- Avoid single-letter variable names, except for simple loop counters (e.g. `i`, `j`).
+- Avoid abbreviations or acronyms in names, except for widely known and accepted abbreviations (e.g. `Id`, `Url`, `Http`).
+- Prefer clarity over brevity - a longer descriptive name is better than a short ambiguous one.
+
 ## Code Design Rules
 
 - Use immutable records instead of classes for DTOs.
@@ -24,6 +30,7 @@ For all new C# code:
 - Reuse existing methods or services as much as possible.
 - Use composition over inheritance.
 - Use LINQ instead of for loops when working with collections.
+- Place private nested types at the end of the containing class.
 
 ## Error Handling & Edge Cases
 
diff --git a/eng/docker-tools/templates/variables/docker-images.yml b/eng/docker-tools/templates/variables/docker-images.yml
@@ -1,5 +1,5 @@
 variables:
-  imageNames.imageBuilderName: mcr.microsoft.com/dotnet-buildtools/image-builder:2917799
+  imageNames.imageBuilderName: mcr.microsoft.com/dotnet-buildtools/image-builder:2919324
   imageNames.imageBuilder: $(imageNames.imageBuilderName)
   imageNames.imageBuilder.withrepo: imagebuilder-withrepo:$(Build.BuildId)-$(System.JobId)
   imageNames.testRunner: mcr.microsoft.com/dotnet-buildtools/prereqs:azurelinux3.0-docker-testrunner
diff --git a/src/ImageBuilder.Tests/CopyImageServiceTests.cs b/src/ImageBuilder.Tests/CopyImageServiceTests.cs
@@ -2,11 +2,14 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 using System;
+using System.Collections.Generic;
+using System.Threading;
 using System.Threading.Tasks;
 using Azure.Core;
 using Azure.ResourceManager;
 using Azure.ResourceManager.ContainerRegistry.Models;
 using Microsoft.DotNet.ImageBuilder.Configuration;
+using Microsoft.DotNet.ImageBuilder.Oras;
 using Microsoft.DotNet.ImageBuilder.Tests.Helpers;
 using Microsoft.Extensions.Logging;
 using Moq;
@@ -29,6 +32,7 @@ public async Task ImportImageAsync_DryRun_DoesNotRequirePublishConfiguration()
         var service = new CopyImageService(
             Mock.Of<ILogger<CopyImageService>>(),
             Mock.Of<IAcrImageImporter>(),
+            Mock.Of<IOrasService>(),
             ConfigurationHelper.CreateOptionsMock(emptyConfig));
 
         await Should.NotThrowAsync(() =>
@@ -69,10 +73,15 @@ public async Task ImportImageAsync_ExternalSourceRegistry_DoesNotRequireSourceRe
         };
 
         var mockImporter = new Mock<IAcrImageImporter>();
+        var mockOras = new Mock<IOrasService>();
+        mockOras
+            .Setup(o => o.GetReferrersAsync(It.IsAny<string>(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync(Array.Empty<string>());
 
         var service = new CopyImageService(
             Mock.Of<ILogger<CopyImageService>>(),
             mockImporter.Object,
+            mockOras.Object,
             ConfigurationHelper.CreateOptionsMock(publishConfig));
 
         await service.ImportImageAsync(
@@ -92,4 +101,156 @@ await service.ImportImageAsync(
                     c.Source.RegistryAddress == "docker.io" && c.Source.ResourceId == null!)),
             Times.Once);
     }
+
+    /// <summary>
+    /// When referrers exist for the source image, ImportImageAsync should import each referrer
+    /// as an untagged artifact in addition to the main image.
+    /// </summary>
+    [Fact]
+    public async Task ImportImageAsync_CopiesReferrersAlongWithSourceImage()
+    {
+        PublishConfiguration publishConfig = CreateAcrPublishConfig("myacr.azurecr.io");
+
+        var mockImporter = new Mock<IAcrImageImporter>();
+        var mockOras = new Mock<IOrasService>();
+        mockOras
+            .Setup(o => o.GetReferrersAsync("myacr.azurecr.io/repo:tag", It.IsAny<CancellationToken>()))
+            .ReturnsAsync(["myacr.azurecr.io/repo@sha256:ref1", "myacr.azurecr.io/repo@sha256:ref2"]);
+
+        var service = new CopyImageService(
+            Mock.Of<ILogger<CopyImageService>>(),
+            mockImporter.Object,
+            mockOras.Object,
+            ConfigurationHelper.CreateOptionsMock(publishConfig));
+
+        await service.ImportImageAsync(
+            destTagNames: ["mirror/repo:tag"],
+            destAcrName: "myacr.azurecr.io",
+            srcTagName: "repo:tag",
+            srcRegistryName: "myacr.azurecr.io",
+            isDryRun: false);
+
+        // Main image import with TargetTags
+        mockImporter.Verify(
+            x => x.ImportImageAsync(
+                "myacr.azurecr.io",
+                It.IsAny<ResourceIdentifier>(),
+                It.Is<ContainerRegistryImportImageContent>(c =>
+                    c.TargetTags.Count == 1 && c.TargetTags[0] == "mirror/repo:tag")),
+            Times.Once);
+
+        // Two referrer imports with UntaggedTargetRepositories
+        mockImporter.Verify(
+            x => x.ImportImageAsync(
+                "myacr.azurecr.io",
+                It.IsAny<ResourceIdentifier>(),
+                It.Is<ContainerRegistryImportImageContent>(c =>
+                    c.UntaggedTargetRepositories.Count == 1
+                    && c.UntaggedTargetRepositories[0] == "mirror/repo"
+                    && c.Source.SourceImage == "repo@sha256:ref1")),
+            Times.Once);
+
+        mockImporter.Verify(
+            x => x.ImportImageAsync(
+                "myacr.azurecr.io",
+                It.IsAny<ResourceIdentifier>(),
+                It.Is<ContainerRegistryImportImageContent>(c =>
+                    c.UntaggedTargetRepositories.Count == 1
+                    && c.UntaggedTargetRepositories[0] == "mirror/repo"
+                    && c.Source.SourceImage == "repo@sha256:ref2")),
+            Times.Once);
+
+        // Total: 1 main + 2 referrers = 3
+        mockImporter.Verify(
+            x => x.ImportImageAsync(
+                It.IsAny<string>(),
+                It.IsAny<ResourceIdentifier>(),
+                It.IsAny<ContainerRegistryImportImageContent>()),
+            Times.Exactly(3));
+    }
+
+    /// <summary>
+    /// When no referrers exist, ImportImageAsync should import only the main image.
+    /// </summary>
+    [Fact]
+    public async Task ImportImageAsync_NoReferrers_ImportsOnlySourceImage()
+    {
+        PublishConfiguration publishConfig = CreateAcrPublishConfig("myacr.azurecr.io");
+
+        var mockImporter = new Mock<IAcrImageImporter>();
+        var mockOras = new Mock<IOrasService>();
+        mockOras
+            .Setup(o => o.GetReferrersAsync(It.IsAny<string>(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync(Array.Empty<string>());
+
+        var service = new CopyImageService(
+            Mock.Of<ILogger<CopyImageService>>(),
+            mockImporter.Object,
+            mockOras.Object,
+            ConfigurationHelper.CreateOptionsMock(publishConfig));
+
+        await service.ImportImageAsync(
+            destTagNames: ["mirror/repo:tag"],
+            destAcrName: "myacr.azurecr.io",
+            srcTagName: "repo:tag",
+            srcRegistryName: "myacr.azurecr.io",
+            isDryRun: false);
+
+        mockImporter.Verify(
+            x => x.ImportImageAsync(
+                It.IsAny<string>(),
+                It.IsAny<ResourceIdentifier>(),
+                It.IsAny<ContainerRegistryImportImageContent>()),
+            Times.Once);
+    }
+
+    /// <summary>
+    /// In dry-run mode, referrer discovery should be skipped entirely since it
+    /// requires registry connectivity.
+    /// </summary>
+    [Fact]
+    public async Task ImportImageAsync_DryRun_SkipsReferrerDiscovery()
+    {
+        var mockOras = new Mock<IOrasService>();
+
+        var service = new CopyImageService(
+            Mock.Of<ILogger<CopyImageService>>(),
+            Mock.Of<IAcrImageImporter>(),
+            mockOras.Object,
+            ConfigurationHelper.CreateOptionsMock(new PublishConfiguration()));
+
+        await service.ImportImageAsync(
+            destTagNames: ["myacr.azurecr.io/repo:tag"],
+            destAcrName: "myacr.azurecr.io",
+            srcTagName: "repo:tag",
+            srcRegistryName: "myacr.azurecr.io",
+            isDryRun: true);
+
+        mockOras.Verify(
+            o => o.GetReferrersAsync(It.IsAny<string>(), It.IsAny<CancellationToken>()),
+            Times.Never);
+    }
+
+    private static PublishConfiguration CreateAcrPublishConfig(string acrServer)
+    {
+        return new PublishConfiguration
+        {
+            RegistryAuthentication =
+            [
+                new RegistryAuthentication
+                {
+                    Server = acrServer,
+                    ResourceGroup = "my-rg",
+                    Subscription = Guid.NewGuid().ToString(),
+                    ServiceConnection = new ServiceConnection
+                    {
+                        Name = "test",
+                        Id = Guid.NewGuid().ToString(),
+                        TenantId = Guid.NewGuid().ToString(),
+                        ClientId = Guid.NewGuid().ToString()
+                    }
+                }
+            ]
+        };
+    }
 }
diff --git a/src/ImageBuilder.Tests/Oras/OrasDotNetServiceTests.cs b/src/ImageBuilder.Tests/Oras/OrasDotNetServiceTests.cs
@@ -20,6 +20,20 @@ namespace Microsoft.DotNet.ImageBuilder.Tests.Oras;
 
 public class OrasDotNetServiceTests
 {
+    [Theory]
+    [InlineData(null)]
+    [InlineData("")]
+    [InlineData("   ")]
+    public async Task GetReferrersAsync_NullOrWhitespaceReference_ThrowsArgumentException(string? reference)
+    {
+        var service = CreateService();
+
+        var exception = await Should.ThrowAsync<ArgumentException>(async () =>
+            await service.GetReferrersAsync(reference!));
+
+        exception.ShouldNotBeNull();
+    }
+
     [Fact]
     public async Task PushSignatureAsync_ReadsPayloadFile()
     {
diff --git a/src/ImageBuilder/CopyImageService.cs b/src/ImageBuilder/CopyImageService.cs
@@ -2,11 +2,13 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 // See the LICENSE file in the project root for more information.
 
+using System.Collections.Generic;
 using System.Linq;
 using System.Threading.Tasks;
 using Azure.Core;
 using Azure.ResourceManager.ContainerRegistry.Models;
 using Microsoft.DotNet.ImageBuilder.Configuration;
+using Microsoft.DotNet.ImageBuilder.Oras;
 using Microsoft.Extensions.Options;
 using Microsoft.VisualStudio.Services.Common;
 
@@ -27,15 +29,18 @@ public class CopyImageService : ICopyImageService
 {
     private readonly ILogger<CopyImageService> _logger;
     private readonly IAcrImageImporter _acrRegistryImporter;
+    private readonly IOrasService _orasService;
     private readonly PublishConfiguration _publishConfig;
 
     public CopyImageService(
         ILogger<CopyImageService> logger,
         IAcrImageImporter acrRegistryImporter,
+        IOrasService orasService,
         IOptions<PublishConfiguration> publishConfigOptions)
     {
         _logger = logger;
         _acrRegistryImporter = acrRegistryImporter;
+        _orasService = orasService;
         _publishConfig = publishConfigOptions.Value;
     }
 
@@ -92,5 +97,31 @@ public async Task ImportImageAsync(
         importImageContent.TargetTags.AddRange(destTagNames);
 
         await _acrRegistryImporter.ImportImageAsync(destAcrName, destResourceId, importImageContent);
+
+        // Discover and import all OCI referrers (signatures, SBOMs, etc.) for the source image.
+        string sourceImageReference = DockerHelper.GetImageName(srcRegistryName, srcTagName);
+        IReadOnlyList<string> referrers = await _orasService.GetReferrersAsync(sourceImageReference);
+
+        string destRepo = destTagNames.First().Split(':')[0].Split('@')[0];
+        foreach (string referrer in referrers)
+        {
+            _logger.LogInformation("Importing referrer '{Referrer}' to '{DestAcr}/{DestRepo}'", referrer, destAcrName, destRepo);
+
+            string referrerDigestReference = DockerHelper.TrimRegistry(referrer, srcRegistryName);
+            ContainerRegistryImportSource referrerImportSrc = new(referrerDigestReference)
+            {
+                ResourceId = srcResourceId,
+                RegistryAddress = srcResourceId is null ? srcRegistryName : null,
+                Credentials = sourceCredentials
+            };
+
+            ContainerRegistryImportImageContent referrerImportContent = new(referrerImportSrc)
+            {
+                Mode = ContainerRegistryImportMode.Force,
+            };
+            referrerImportContent.UntaggedTargetRepositories.Add(destRepo);
+
+            await _acrRegistryImporter.ImportImageAsync(destAcrName, destResourceId, referrerImportContent);
+        }
     }
 }
diff --git a/src/ImageBuilder/Oras/IOrasService.cs b/src/ImageBuilder/Oras/IOrasService.cs
@@ -2,6 +2,7 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 // See the LICENSE file in the project root for more information.
 
+using System.Collections.Generic;
 using System.Threading;
 using System.Threading.Tasks;
 using Microsoft.DotNet.ImageBuilder.Signing;
@@ -33,4 +34,15 @@ Task<string> PushSignatureAsync(
         Descriptor subjectDescriptor,
         PayloadSigningResult result,
         CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Returns the fully-qualified references of all OCI referrers for the given image.
+    /// </summary>
+    /// <param name="reference">Full registry reference (e.g., "registry.io/repo:tag" or "registry.io/repo@sha256:...").</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>
+    /// A list of digest-based image references (e.g., "registry.io/repo@sha256:abc...")
+    /// for every referrer associated with the image.
+    /// </returns>
+    Task<IReadOnlyList<string>> GetReferrersAsync(string reference, CancellationToken cancellationToken = default);
 }
diff --git a/src/ImageBuilder/Oras/OrasDotNetService.cs b/src/ImageBuilder/Oras/OrasDotNetService.cs
@@ -118,6 +118,33 @@ await Packer.PackManifestAsync(
         return signatureDescriptor.Digest;
     }
 
+    /// <inheritdoc/>
+    public async Task<IReadOnlyList<string>> GetReferrersAsync(string reference, CancellationToken cancellationToken = default)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(reference);
+
+        _logger.LogDebug("Fetching referrers for reference: {Reference}", reference);
+
+        long startTime = Stopwatch.GetTimestamp();
+        Repository repository = CreateRepository(reference);
+        Descriptor subjectDescriptor = await repository.ResolveAsync(reference, cancellationToken);
+
+        List<string> referrers = [];
+        Reference parsedRef = Reference.Parse(reference);
+
+        await foreach (Descriptor referrer in repository.FetchReferrersAsync(subjectDescriptor, cancellationToken))
+        {
+            string referrerReference = $"{parsedRef.Registry}/{parsedRef.Repository}@{referrer.Digest}";
+            referrers.Add(referrerReference);
+            _logger.LogDebug("Found referrer: {Referrer} (artifactType={ArtifactType})", referrerReference, referrer.ArtifactType);
+        }
+
+        TimeSpan elapsed = Stopwatch.GetElapsedTime(startTime);
+        _logger.LogDebug("Found {Count} referrer(s) for {Reference} in {Elapsed}", referrers.Count, reference, elapsed);
+
+        return referrers;
+    }
+
     /// <summary>
     /// Creates an authenticated ORAS repository client for the given reference.
     /// </summary>
