Background and Motivation

Currently, .NET Aspire provides mechanisms for configuring container resources, but there is no direct API to specify container labels. Labels are widely used in containerized environments (e.g., Docker, Kubernetes) to provide metadata for images and running containers. This metadata is valuable for purposes such as:

• Operational metadata: e.g., who owns a container or when it was built.
• Integration with other systems: e.g., CI/CD pipelines, monitoring, or logging tools that rely on labels.
• Organizing and filtering resources: e.g., grouping containers by environment, service, or feature.

While .NET project containers support labels through MSBuild and container publishing settings , there is no general-purpose API to apply labels to any container resource defined in Aspire.

This proposal introduces a WithLabel (and optionally WithLabels) extension method for IResourceBuilder<T> where T : ContainerResource. This will give developers a simple, consistent way to attach labels at the Aspire container level.

Proposed API

namespace Aspire.Hosting;

public static class ContainerResourceBuilderExtensions
{
+    /// <summary>
+    /// Adds a container label to the container resource.
+    /// </summary>
+    public static IResourceBuilder<T> WithLabel<T>(
+        this IResourceBuilder<T> builder,
+        string key,
+        string value) where T : ContainerResource;
+
+    /// <summary>
+    /// Adds multiple container labels to the container resource.
+    /// </summary>
+    public static IResourceBuilder<T> WithLabels<T>(
+        this IResourceBuilder<T> builder,
+        IDictionary<string, string> labels) where T : ContainerResource;
}

Usage Examples

// Add a single label
builder.AddContainer("my-service", "nginx:latest")
       .WithLabel("com.example.service", "my-service");

// Add multiple labels
builder.AddContainer("my-service", "nginx:latest")
       .WithLabels(new Dictionary<string, string>
       {
           ["com.example.service"] = "my-service",
           ["com.example.environment"] = "staging",
           ["com.example.owner"] = "team-xyz"
       });

This approach ensures that all containers, regardless of whether they originate from .NET projects or external images, can be tagged with custom labels.

Alternative Designs

• Single method with params overload: Instead of having WithLabel and WithLabels, a single method could accept params (string key, string value)[]. However, this is less clear and requires allocation of tuples.

• Builder-style API: Another option would be an object for building metadata (e.g., .ConfigureLabels(l => l.Add(...))). While more flexible for future extensions, it is overkill for the common simple key-value label pattern.

• MSBuild-only approach: Labels could be configured for project-based containers via MSBuild, but this excludes non-.NET container resources, making the solution incomplete.

• Comparison to Docker Compose: Docker Compose supports labels through a straightforward labels key:

  services:
    web:
      image: nginx
      labels:
        com.example.service: "my-service"
        com.example.environment: "staging"

  The proposed WithLabel(s) API mirrors this pattern, making it intuitive for developers already familiar with Compose or Dockerfile labels.

Risks

• Consistency with other metadata APIs: We need to ensure that the label API is aligned with existing Aspire configuration patterns for environment variables, ports, etc.
• Potential for conflicts: If a label is set via both MSBuild and Aspire APIs, behavior must be clearly documented (e.g., Aspire overrides MSBuild or vice versa).
• Breaking changes: None expected since this is additive.