Add OCI container annotation support

[jetersen]

Summary

• add a ContainerAnnotation MSBuild item for OCI image metadata
• write annotations to single-platform OCI manifests and top-level multi-architecture OCI indexes
• provide opt-in conventional annotations from existing container and Source Link metadata
• automatically select OCI when annotations are requested, while rejecting an explicitly selected Docker format

Motivation

OCI annotations describe the published manifest or image index itself. Registry consumers cannot reliably obtain this metadata from configuration labels, particularly for multi-platform images where the tag resolves to an image index.

Generated annotations are opt-in to preserve the existing behavior where output format follows the base image. Architecture-specific base image and .NET toolset metadata remain labels and are not copied to the top-level index.

Validation

• Microsoft.NET.Build.Containers unit tests: 288 passed, 7 existing skips
• focused manifest and image-index annotation tests pass
• integration test project compiles with target coverage for generated metadata and image-format compatibility
• git diff --check passes

Running the integration tests requires a built redist SDK; the attempted redist build was blocked by a pre-existing missing project.assets.json in the Blazor WebAssembly tool chain after the Containers projects compiled and packed.

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).
2 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).
2 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

Pull request overview

Adds first-class OCI manifest/index annotation support to the .NET SDK container publishing pipeline, enabling registry consumers to read metadata from image manifests and multi-arch indexes (not just config labels).

Changes:

• Introduces a ContainerAnnotation MSBuild item and wires it through container build/publish tasks.
• Emits annotations into single-platform OCI manifests and top-level multi-arch OCI indexes, with opt-in conventional annotations derived from existing package/source metadata.
• Enforces/auto-selects OCI output when annotations are present and rejects explicitly-selected Docker format.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
test/Microsoft.NET.Build.Containers.UnitTests/ImageIndexGeneratorTests.cs	Adds unit coverage for index-level OCI annotations and Docker manifest list behavior.
test/Microsoft.NET.Build.Containers.UnitTests/ImageBuilderTests.cs	Adds unit coverage for manifest-level OCI annotations.
test/Microsoft.NET.Build.Containers.IntegrationTests/TargetsTests.cs	Validates conventional annotation generation and the “annotations require OCI” enforcement at the MSBuild layer.
src/Containers/packaging/build/Microsoft.NET.Build.Containers.targets	Defines annotation-related properties/items, generates conventional annotations, auto-selects OCI, and errors on Docker format when annotations exist.
src/Containers/Microsoft.NET.Build.Containers/Tasks/CreateNewImage.Interface.cs	Exposes Annotations task parameter for single-image creation.
src/Containers/Microsoft.NET.Build.Containers/Tasks/CreateNewImage.cs	Plumbs MSBuild ContainerAnnotation items into ImageBuilder.
src/Containers/Microsoft.NET.Build.Containers/Tasks/CreateImageIndex.Interface.cs	Exposes Annotations task parameter for multi-arch index creation.
src/Containers/Microsoft.NET.Build.Containers/Tasks/CreateImageIndex.cs	Collects annotations and passes them into index generation.
src/Containers/Microsoft.NET.Build.Containers/PublicAPI/net11.0/PublicAPI.Unshipped.txt	Declares newly added public API surface for annotations on tasks/manifests/indexes.
src/Containers/Microsoft.NET.Build.Containers/ManifestV2.cs	Adds Annotations to OCI manifest model with null-when-empty serialization behavior.
src/Containers/Microsoft.NET.Build.Containers/ManifestListV2.cs	Adds index/list-level annotations properties to the manifest list and OCI index models.
src/Containers/Microsoft.NET.Build.Containers/ImageIndexGenerator.cs	Extends index generation APIs to accept optional annotations and serialize them into OCI indexes.
src/Containers/Microsoft.NET.Build.Containers/ImageBuilder.cs	Adds annotation capture and emission for OCI manifests.

[jetersen]

@dotnet-policy-service agree