microsoft / microsoft/aspire

[14.0] Redesign PublishAsDockerFile argument handling

Open
#19,922 0 comments 0 reactions 0 assignees View on GitHub
area-app-model breaking-change
Dominant language
C#
Stars
6.3k
Forks
991
Avg merge
2d 15h
Merged PRs (30d)
196

Description

### Is there an existing issue for this?

- [x] I have searched the existing issues

### Is your feature request related to a problem? Please describe the problem.

`PublishAsDockerFile` currently clears ordinary `WithArgs` callbacks to prevent host-launch arguments from leaking into a generated container's runtime arguments. This is a broad, positional operation: it cannot distinguish a local tool invocation (`go run`, `python -m`, package-manager scripts, host paths) from genuine application arguments that should be passed to the published image.

The repeated-call behavior is also inconsistent:

- For an `ExecutableResource`, every `PublishAsDockerFile` call appends another clear. Arguments configured before the first call, by its callback, or between calls are removed by a later call; only arguments configured by or after the final call survive.
- For a `ProjectResource`, only the first call clears. Arguments configured by its first callback or between calls survive subsequent calls.

This behavior is established and must remain compatible through Aspire 13.x, but it is difficult to explain and easy for integrations to depend on accidentally.

Related issues:

- #18904 tracks the broader need to distinguish tool arguments from application arguments.
- #16873 and #16874 report published container arguments disappearing around `PublishAsDockerFile`.
- #19070 covers generated versus user-authored Dockerfile entrypoints for Go and Python.

### Describe the solution you'd like

For Aspire 14.0, define one explicit argument model for resources that can run through a local launch tool and publish as a container:

1. `WithArgs` should have a consistent meaning, preferably application/runtime arguments that survive publishing.
2. Local tool-invocation arguments should be modeled separately and automatically excluded when a container image entrypoint replaces the local launcher.
3. `PublishAsDockerFile` should not rely on appending `Args.Clear()` callbacks whose effects depend on registration order.
4. Repeated `PublishAsDockerFile` calls should have the same replacement/accumulation semantics for project and executable resources.
5. Generated and user-authored Dockerfiles should have an explicit contract for who owns `ENTRYPOINT`/`CMD` and how application arguments are composed with it.

This may require a breaking behavioral change, so it should target 14.0 rather than changing the 13.6 compatibility behavior.

### Additional context

The 13.6 resource-projection work preserves the existing evaluated argument behavior with focused tests. The redesign should add cross-publisher coverage for manifest, Azure Container Apps, Kubernetes, and Docker Compose output so `WithArgs` does not vary accidentally by deployment target.

Contributor guide

Open the contributing guide

Research direction

Start by reading the 13.6 resource-projection work and its focused tests, then trace how argument evaluation reaches manifest, Azure Container Apps, Kubernetes, and Docker Compose output. Compare ExecutableResource and ProjectResource behavior across repeated PublishAsDockerFile calls. Done means the 14.0 contract is explicit and cross-publisher coverage verifies consistent application and local-tool arguments.

Written by the indexing model from the issue text.

Assessment

Tech stack
azure, csharp, docker, docker-compose, go, kubernetes, python
Domain
devops, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.