[Breaking change]: AddDockerfile/WithDockerfile default container image name and tag changed in Aspire 9.1

[DamianEdwards]

Description

In Aspire 9.1, the default container image name and tag assigned to the container resource when using AddDockerfile or WithDockerfile are changing.

Version

Other (please put exact version in description textbox)

Previous behavior

In Aspire 9.0:

• the default container image name used was based on this format: {ResourceName}-image-{HashOfAppHostDirectory}
• the default container tag used was simply latest

New behavior

In Aspire 9.1:

• the default container image name used is now simply the resource name lowercased
• the default container tag used is now a hash that's derived from the app host directory combined with a timestamp of when the method was called.

Type of breaking change

• Binary incompatible: Existing binaries might encounter a breaking change in behavior, such as failure to load or execute, and if so, require recompilation.
• Source incompatible: When recompiled using the new SDK or component or to target the new runtime, existing source code might require source changes to compile successfully.
• Behavioral change: Existing binaries might behave differently at run time.

Reason for change

The previous behavior caused the bug dotnet/aspire#7462 as the resource name wasn't properly sanitized to be a safe container image name, didn't result in very friendly container names when using Dockerfiles, and resulted in images simply tagged as "latest" on every build/publish, potentially making it difficult to roll-back deployments.

Recommended action

Users should be aware that the generated image names and tags are now different to what they'd previously been and update any dependent deployment tools, scripts, and processes accordingly.

Note that the default image name and tag can be overridden by calling WithImage and WithImageTag on the IResourceBuilder<ContainerResource> respectively

Affected APIs

• Aspire.Hosting.ContainerResourceBuilderExtensions
  • AddDockerfile(this IDistributedApplicationBuilder builder, [ResourceName] string name, string contextPath, string? dockerfilePath = null, string? stage = null)
  • WithDockerfile<T>(this IResourceBuilder<T> builder, string contextPath, string? dockerfilePath = null, string? stage = null) where T : ContainerResource

---

Associated WorkItem - 373402