Fix Docker image tag parsing error when environment names contain uppercase or special characters

[Copilot]

Problem

Docker image push operations occasionally fail with parsing errors when deployment tags contain uppercase letters or special characters:

Pushing api to octopetsacrl5romtyajh3t2: Failed to push api: Input 
string was not in a correct format. Failure to parse near offset 35. Expected an ASCII 
digit. (33.6s)

This occurs because Docker image tags have strict format requirements:

• Must contain only lowercase/uppercase ASCII letters, digits, underscores, periods, and hyphens
• Cannot start with a period or hyphen
• Maximum 128 characters

When environment names or registry names (like Azure Container Registry names) contain uppercase letters or special characters, the resulting deployment tags violate these constraints, causing push operations to fail.

Solution

This PR introduces a new utility class DockerImageTagHelpers that sanitizes strings to ensure Docker tag compliance. The sanitization process:

1. Converts all characters to lowercase
2. Replaces invalid characters (anything other than a-z, 0-9, _, ., -) with hyphens
3. Removes leading periods and hyphens
4. Truncates to 128 characters if necessary
5. Returns a safe default ("aspire-deploy") if the result is empty after sanitization

Example Usage

// Environment name with uppercase letters
var tag1 = DockerImageTagHelpers.SanitizeTag("MyEnvironment-20231215120000");
// Returns: "myenvironment-20231215120000"

// ACR name with mixed case
var tag2 = DockerImageTagHelpers.SanitizeTag("octoPetsACRL5romtyajh3t2-20231215120000");
// Returns: "octopetsacrl5romtyajh3t2-20231215120000"

// Name with special characters
var tag3 = DockerImageTagHelpers.SanitizeTag("My@Env#2024");
// Returns: "my-env-2024"

Changes

• src/Aspire.Hosting/Utils/DockerImageTagHelpers.cs (new): Public utility class with SanitizeTag() method, fully documented with XML comments and examples
• src/Aspire.Hosting.Azure/AzureEnvironmentResource.cs: Updated BuildContainerImagesAsync() to sanitize deployment tags before use
• tests/Aspire.Hosting.Azure.Tests/DockerImageTagHelpersTests.cs (new): 33 comprehensive unit tests covering edge cases

Testing

All tests pass, including:

• ✅ 33 new tests for tag sanitization (valid inputs, uppercase, special chars, truncation, etc.)
• ✅ Existing Azure environment resource tests
• ✅ Existing Docker publishing tests

Impact

This fix prevents deployment failures when:

• Environment names contain uppercase letters
• Azure Container Registry names contain mixed case
• Any part of the deployment tag contains special characters

The utility is placed in Aspire.Hosting.Utils for reusability across both Azure and Docker Compose deployment scenarios.

Fixes #[issue-number]

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• aka.ms
  • Triggering command: /usr/local/bin/bicep build /tmp/aspireReMTZI/env.module.bicep --stdout (dns block)
  • Triggering command: /usr/local/bin/bicep build /tmp/aspireJSVUCz/env.module.bicep --stdout (dns block)
  • Triggering command: /usr/local/bin/bicep build /tmp/aspireq9SUJm/worker.module.bicep --stdout (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Image push fails with parsing error when environment name contains uppercase letters or special characters</issue_title>
<issue_description>## Description

The image push occasionally fails with the following error:

Pushing api to octopetsacrl5romtyajh3t2: Failed to push api: Input 
string was not in a correct format. Failure to parse near offset 35. Expected an ASCII 
digit. (33.6s)

Root Cause

In the compose-deployment-tag branch, the deployment tag generation was changed from:

var deploymentTag = $"aspire-deploy-{DateTime.UtcNow:yyyyMMddHHmmss}";

to:

var deploymentTag = $"{environmentName}-{DateTime.UtcNow:yyyyMMddHHmmss}";

The problem is that environmentName can contain characters that are invalid for Docker image tags. Docker image tags have strict format requirements and must match the pattern [a-zA-Z0-9_.-]+ with additional constraints:

• Can contain lowercase and uppercase ASCII letters, digits, underscores, periods, and hyphens
• Cannot start with a period or hyphen
• Maximum 128 characters
• Some registries may have additional restrictions (e.g., Azure Container Registry names often contain mixed case)

When the environment name contains uppercase letters or special characters, the resulting tag can be malformed, causing parsing errors during the push operation.

Affected Code

• src/Aspire.Hosting.Azure/AzureDeployingContext.cs (line 178)
• src/Aspire.Hosting.Docker/DockerComposeInfrastructure.cs (line 61)

Proposed Fix

Sanitize the environment name before using it in the tag by converting to lowercase and replacing invalid characters:

private static string SanitizeDockerTag(string input)
{
    if (string.IsNullOrEmpty(input))
    {
        return "aspire-deploy";
    }

    // Convert to lowercase and replace invalid characters with hyphens
    var sanitized = new StringBuilder();
    foreach (var c in input.ToLowerInvariant())
    {
        if (char.IsAsciiLetterOrDigit(c) || c == '-' || c == '_' || c == '.')
        {
            sanitized.Append(c);
        }
        else
        {
            sanitized.Append('-');
        }
    }

    // Ensure it doesn't start with a period or hyphen
    var result = sanitized.ToString().TrimStart('.', '-');
    
    // Ensure it's not empty after sanitization
    return string.IsNullOrEmpty(result) ? "aspire-deploy" : result;
}

Then use it:

var sanitizedEnvironmentName = SanitizeDockerTag(environmentName);
var deploymentTag = $"{sanitizedEnvironmentName}-{DateTime.UtcNow:yyyyMMddHHmmss}";

Impact

This affects both:

• Azure deployments (AzureDeployingContext)
• Docker Compose deployments (DockerComposeInfrastructure)

/cc @github-copilot</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #12157

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 12158

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 12158"

[davidfowl]

?

[captainsafia]

I'm trying something new where I iterate on the issue spec via the Copilot CLI before I send it to the agent. I tried it for this PR on a branch outsie main and I think that tripped it up.