Adjust required CLI behavior for C# AppHosts

[Damian Edwards (DamianEdwards)]

Description

Launching a C# AppHost with dotnet run or an IDE should continue to work without requiring the Aspire CLI, while users who opt into CLI delegation should be able to use either an installed aspire command or DNX.

This change:

• Restores AspireUseCliBundle to false by default and emits ASPIRE010 with migration guidance.
• Preserves direct AppHost launch when CLI delegation is not enabled.
• Resolves an opted-in CLI invocation in this order: an explicit AspireCliPath, forced DNX mode, aspire on PATH, then dnx on PATH.
• Adds AspireCliInvocationMode=Dnx to force DNX and reports ASPIRE011 when DNX is unavailable.
• Allows DNX delegation when build-time DCP and dashboard bundle metadata is unavailable, while preserving AppHost identity metadata.
• Invokes DNX as dnx --yes aspire.cli@$(AspireHostingSDKVersion) so noninteractive launches restore and execute the exact CLI version paired with the AppHost SDK rather than an unpinned package.
• Fails explicitly when DNX cannot restore or probe that package instead of falling back to an incomplete direct launch.
• Preserves the exact executable selected from PATH through launch and rejects non-executable PATH candidates on Unix.
• Preserves ASPIRE009 for invalid explicitly configured CLI or bundle paths.

The DNX invocation and explicit-path behavior reuse the relevant implementation from #18331.

User-facing usage

To enable CLI delegation and automatically prefer aspire before falling back to DNX:

<PropertyGroup>
  <AspireUseCliBundle>true</AspireUseCliBundle>
</PropertyGroup>

This opt-in permits DNX to restore and execute the exact Aspire.Cli version paired with the AppHost SDK from the user's configured NuGet sources when aspire is not available on PATH. --yes is required because dotnet run is noninteractive.

To force DNX:

<PropertyGroup>
  <AspireUseCliBundle>true</AspireUseCliBundle>
  <AspireCliInvocationMode>Dnx</AspireCliInvocationMode>
</PropertyGroup>

Validation included:

• 35 AppHostSdkTargetsTests on Linux; 34 passed and the Unix-only test was skipped on Windows.
• 23 MSBuildTests.
• A restore-inclusive repository build and package creation.
• A portable local hive containing 103 unique Aspire packages.
• Seven Aspire apps created outside the repository and run with .NET SDK 10.0.302.
• Actual direct, PATH aspire, automatic DNX, forced DNX, and explicit-path launches through healthy dashboard startup.
• A real Docker E2E test that creates an external starter app without a tool manifest, hides aspire, restores the pinned local Aspire.Cli package through SDK DNX, reaches healthy AppHost startup, and verifies forwarded arguments.
• Expected ASPIRE009, ASPIRE010, and ASPIRE011 failure and warning scenarios.

Fixes #18447

Checklist

• Is this feature complete?
  • Yes. Ready to ship.
  • No. Follow-up changes expected.
• Are you including unit tests for the changes and scenario tests if relevant?
  • Yes
  • No
• Did you add public API?
  • Yes
    • If yes, did you have an API Review for it?
      • Yes
      • No
    • Did you add <remarks /> and <code /> elements on your triple slash comments?
      • Yes
      • No
  • No
• Does the change make any security assumptions or guarantees?
  • Yes
    • Bundle opt-in allows DNX to restore and execute the exact CLI version paired with the AppHost SDK from user-configured NuGet sources. The package is pinned, PATH executables are resolved before launch, and the behavior is documented above and in docs/list-of-diagnostics.md.
    • If yes, have you done a threat model and had a security review?
      • Yes
      • No
  • No

[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/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 18850

Or

• Run remotely in PowerShell:

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

[Copilot]

Pull request overview

Restores direct C# AppHost launching by default while adding opt-in Aspire CLI and DNX delegation.

Changes:

• Defaults AspireUseCliBundle to false and adds ASPIRE010 guidance.
• Adds Aspire/DNX resolution, validation, and run-hook behavior.
• Expands MSBuild and SDK target coverage.

Reviewed changes

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

Show a summary per file

File	Description
tests/Directory.Build.props	Suppresses ASPIRE010 in tests.
tests/Aspire.Hosting.Tests/MSBuildTests.cs	Tests defaults, diagnostics, and metadata.
tests/Aspire.Hosting.Sdk.Tests/Aspire.Hosting.Sdk.Tests.csproj	Makes hosting tasks available to tests.
tests/Aspire.Hosting.Sdk.Tests/AppHostSdkTargetsTests.cs	Tests Aspire and DNX delegation.
src/Aspire.Hosting.Tasks/ResolveAspireCliInvocation.cs	Selects the CLI invocation mode.
src/Aspire.Hosting.Tasks/ResolveAspireCliBundle.cs	Reuses shared PATH resolution.
src/Aspire.Hosting.Tasks/CommandPathResolver.cs	Implements command discovery.
src/Aspire.Hosting.AppHost/build/Aspire.Hosting.AppHost.props	Restores the disabled-by-default setting.
src/Aspire.Hosting.AppHost/build/Aspire.Hosting.AppHost.in.targets	Implements delegation and diagnostics.
src/Aspire.AppHost.Sdk/SDK/Sdk.in.targets	Aligns SDK defaults.
playground/Directory.Build.props	Suppresses ASPIRE010 in playground builds.
docs/list-of-diagnostics.md	Documents ASPIRE010 and ASPIRE011.

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

src/Aspire.Hosting.AppHost/build/Aspire.Hosting.AppHost.in.targets:275

• A failed DNX version probe silently disables delegation because _AspireCliVersionSupportsRunHook remains false, so a missing or unrestored aspire.cli local tool causes the AppHost to launch directly. That contradicts the DNX contract documented below: the actual dnx invocation never runs, so users never receive the local-tool restore error. For DNX selection, either fail this preflight with the DNX error or preserve delegation on probe failure so dnx can report the actionable restore failure.

      <_AspireCliVersionCommand Condition="'$(AspireCliPath)' == '' and '$(_AspireResolvedCliInvocationMode)' == 'Dnx'">dnx $(_AspireCliDnxPackageId) -- --version</_AspireCliVersionCommand>

src/Aspire.Hosting.Tasks/CommandPathResolver.cs:39

• On Unix, File.Exists also accepts files without any execute bit. Such a file named aspire earlier on PATH is selected as the CLI, its version probe fails with permission denied, and a valid later aspire or dnx candidate is never considered. Match executable lookup semantics by rejecting non-executable Unix candidates (the repository's PathLookupHelper.FileExistsAndIsExecutable demonstrates the required check).

                if (seenPaths.Add(candidate) && File.Exists(candidate))
                {
                    yield return candidate;

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (2)

src/Aspire.Hosting.AppHost/build/Aspire.Hosting.AppHost.in.targets:217

• Making bundle resolution optional as soon as a dnx executable is found leaves an invalid fallback path. If restoring/probing aspire.cli fails or reports a version below 13.5, _AspireCliVersionSupportsRunHook remains false and dotnet run launches the AppHost directly. Because CLI opt-in also skipped the DCP/Dashboard package references and this condition suppressed ASPIRE009, that AppHost has neither build-time discovery metadata nor runtime paths injected by the CLI. Only permit missing bundle metadata after a usable DNX invocation is confirmed, or fail the DNX probe instead of falling back to direct launch.

      <_AspireCliBundleResolutionOptional Condition="'$(_AspireResolvedCliInvocationMode)' == 'Dnx' and '$(AspireCliPath)' == '' and '$(AspireCliBundlePath)' == ''">true</_AspireCliBundleResolutionOptional>

src/Aspire.Hosting.Tasks/CommandPathResolver.cs:37

• On Unix, existence does not mean the candidate is an executable command. A non-executable file named aspire earlier on PATH is selected here, its version probe fails, and the resolver never tries a later executable or DNX, so CLI delegation unexpectedly falls back to direct launch. Filter Unix candidates by executable permissions (with appropriate handling for the task assembly's target frameworks) before returning them.

                if (seenPaths.Add(candidate) && File.Exists(candidate))

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

src/Aspire.Hosting.AppHost/build/Aspire.Hosting.AppHost.in.targets:291

• The preceding comment is now inaccurate: DNX probe failures do fail the target via the new <Error> elements, and DNX uses a 120-second timeout rather than 5 seconds. Please describe both the ordinary Aspire fallback and the DNX failure behavior so future changes do not rely on the old contract.

          Timeout="$(_AspireCliVersionTimeout)"

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[Damian Edwards (DamianEdwards)]

PR Testing Report

PR Information

• PR: Adjust required CLI behavior for C# AppHosts #18850
• Head commit: cabe057e7c9518320f3b7421aa6ecce2aa98598a

Artifact Version Verification

Installed PR #18850 from CI run 30965936001 into the fresh workspace. The installed Windows CLI reported:

13.5.0-pr.18850.gcabe057e

The fresh PR hive contains the matching Aspire.Cli, Aspire.Cli.win-x64, and Aspire.Cli.linux-x64 packages. The version check was completed before any scenario ran; no stale 6aaddbd installation or report was reused.

Scenarios

1. Default direct AppHost launch

Passed. A fresh aspire-empty AppHost reached dashboard startup with the default bundle behavior and emitted the expected direct-launch warning. Forwarded arguments were preserved exactly:

FORWARDED_ARGS:[https://host/?a=1&b=2]|[%ASPIRE_TEST_LITERAL%]

Evidence: scenarios\DirectDefault\forwarded-direct-shell.log.

2. PATH native Aspire delegation and argv preservation

Passed. With AspireUseCliBundle=true and the fresh gcabe057e CLI first on PATH, the AppHost reached healthy dashboard startup. The AppHost recorded the exact URL and literal environment-token-shaped argument without expansion:

FORWARDED_ARGS:[https://host/?a=1&b=2]|[%ASPIRE_TEST_LITERAL%]

Evidence: scenarios\PathAspire\forwarded-path-shell.log.

3. Automatic real DNX fallback

Passed. With the PATH Aspire executable hidden and no tool manifest, the exact paired aspire.cli@13.5.0-pr.18850.gcabe057e package was prewarmed through SDK DNX using the fresh project's NuGet configuration and PR hive, then the AppHost reached dashboard startup through automatic DNX fallback.

Evidence: scenarios\AutoDnx\dnx-prewarm.log and scenarios\AutoDnx\run.log.

4. Forced DNX

Passed. With AspireCliInvocationMode=Dnx, the fresh AppHost launched through DNX and reached the dashboard.

Evidence: scenarios\ForcedDnx\forced-shell.log.

5. Invalid explicit CLI path (ASPIRE009)

Passed. A nonexistent AspireCliPath failed non-zero with actionable ASPIRE009 diagnostics.

Evidence: scenarios\ExplicitInvalid\run.log.

6. Missing forced DNX (ASPIRE011)

Passed. Forced DNX with no dnx command on PATH failed non-zero with actionable ASPIRE011 diagnostics.

Evidence: scenarios\MissingForcedDnx\run.log.

7. Fresh artifact/package consistency

Passed. The fresh installation, SDK AppHost package, CLI package, and RID-specific CLI packages all carried the 13.5.0-pr.18850.gcabe057e suffix; AppHost logs reported the same version.

Summary

Scenario	Result
Exact gcabe057e artifact verification	Passed
Default direct launch	Passed
Direct forwarded arguments	Passed
PATH native Aspire delegation	Passed
PATH argv preservation	Passed
Automatic real DNX fallback	Passed
Forced DNX	Passed
ASPIRE009 invalid path	Passed
ASPIRE011 missing DNX	Passed

Overall Result

PR #18850 verified against cabe057e7c9518320f3b7421aa6ecce2aa98598a.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 1 comment.

[github-actions]

Tests selector (audit mode)

The full test matrix and all jobs still run in audit mode. The tests and jobs below are what selective CI would run under enforcement.

Runs the full test matrix + all jobs (ALL) — a rule matching 'Aspire.slnx' selects ALL

---

Selection computed for commit 0a5dc56.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated no new comments.

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[github-actions]

⚠️ CI Failure Analysis: Possible Flaky Test(s)

The CI build failed due to test failure(s) that appear unrelated to the PR changes. These may be flaky tests.

Suspected flaky test(s):

• Aspire.Hosting.Maui.Tests.MauiBuildQueueTests.ReleaseSemaphoreAfterLaunchAsync_SkipsReplayStateAndReleasesOnStableState in job Tests / Hosting.Maui / Hosting.Maui (windows-latest)
  • Error: System.TimeoutException : The operation has timed out.
  • Stack Trace (first frames):

    at Aspire.Hosting.Maui.Tests.MauiBuildQueueTests.ReleaseSemaphoreAfterLaunchAsync_SkipsReplayStateAndReleasesOnStableState() in D:\a\aspire\aspire\tests\Aspire.Hosting.Maui.Tests\MauiBuildQueueTests.cs:line 663
       at Aspire.Hosting.Maui.Tests.MauiBuildQueueTests.ReleaseSemaphoreAfterLaunchAsync_SkipsReplayStateAndReleasesOnStableState() in D:\a\aspire\aspire\tests\Aspire.Hosting.Maui.Tests\MauiBuildQueueTests.cs:line 664
    

  • Why likely flaky: Timing-based test that intermittently times out; not in PR-changed files; matches known prior cause 'mauibuildqueue-releasesemaphoreafterlaunchasync' with 2 previous occurrences.
• Aspire.Hosting.Azure.Tests.AzureSqlPrincipalReconciliationTests.ReconciliationCreatesThePrincipalWithTheIdentityObjectIdAsItsSid in job Tests / Hosting.Azure / Hosting.Azure (ubuntu-latest)
  • Error: Class fixture type 'Aspire.Hosting.Azure.Tests.SqlServerContainerFixture' threw in InitializeAsync
    ---- Docker.DotNet.DockerApiException : Docker API responded with status code=InternalServerError, response={"message":"failed to set up container networking: driver failed programming external connectivity on endpoint peaceful_lewin (...): failed to bind host port for 0.0.0.0::172.17.0.3:1433/tcp: address already in use"}
  • Stack Trace (first frames):

    at Docker.DotNet.DockerClient.HandleIfErrorResponseAsync(...)
       at Docker.DotNet.DockerClient.MakeRequestAsync[T](...)
       at Docker.DotNet.ContainerOperations.StartContainerAsync(...)
       at DotNet.Testcontainers.Clients.TestcontainersClient.StartAsync(...)
       at Aspire.Hosting.Azure.Tests.SqlServerContainerFixture.InitializeAsync() in .../SqlServerContainerFixture.cs:line 28
    

  • Why likely flaky: Port 1433 already in use on the runner — environmental port conflict, not caused by PR changes. All 6 AzureSqlPrincipalReconciliationTests share this fixture and fail for the same reason. Matches prior cause 'sqlserver-container-fixture-port-in-use'.
• Aspire.Hosting.Azure.Tests.AzureSqlPrincipalReconciliationTests.ReconciliationHandlesPrincipalNamesRequiringEscaping in job Tests / Hosting.Azure / Hosting.Azure (ubuntu-latest)
  • Error: Class fixture type 'Aspire.Hosting.Azure.Tests.SqlServerContainerFixture' threw in InitializeAsync
    ---- Docker.DotNet.DockerApiException : Docker API responded with status code=InternalServerError, response={"message":"failed to bind host port for 0.0.0.0::172.17.0.3:1433/tcp: address already in use"}
  • Stack Trace (first frames):

    at Aspire.Hosting.Azure.Tests.SqlServerContainerFixture.InitializeAsync() in .../SqlServerContainerFixture.cs:line 28
    

  • Why likely flaky: Same Docker port conflict as ReconciliationCreatesThePrincipalWithTheIdentityObjectIdAsItsSid — shared fixture failure.
• Aspire.Hosting.Azure.Tests.AzureSqlPrincipalReconciliationTests.ReconciliationIsANoOpWhenTheScriptRunsAgain in job Tests / Hosting.Azure / Hosting.Azure (ubuntu-latest)
  • Error: Class fixture type 'Aspire.Hosting.Azure.Tests.SqlServerContainerFixture' threw in InitializeAsync
    ---- Docker.DotNet.DockerApiException : Docker API responded with status code=InternalServerError, response={"message":"failed to bind host port for 0.0.0.0::172.17.0.3:1433/tcp: address already in use"}
  • Stack Trace (first frames):

    at Aspire.Hosting.Azure.Tests.SqlServerContainerFixture.InitializeAsync() in .../SqlServerContainerFixture.cs:line 28
    

  • Why likely flaky: Same Docker port conflict — shared fixture failure.
• Aspire.Hosting.Azure.Tests.AzureSqlPrincipalReconciliationTests.ReconciliationReplacesThePrincipalWhenTheIdentityObjectIdChanges in job Tests / Hosting.Azure / Hosting.Azure (ubuntu-latest)
  • Error: Class fixture type 'Aspire.Hosting.Azure.Tests.SqlServerContainerFixture' threw in InitializeAsync
    ---- Docker.DotNet.DockerApiException : Docker API responded with status code=InternalServerError, response={"message":"failed to bind host port for 0.0.0.0::172.17.0.3:1433/tcp: address already in use"}
  • Stack Trace (first frames):

    at Aspire.Hosting.Azure.Tests.SqlServerContainerFixture.InitializeAsync() in .../SqlServerContainerFixture.cs:line 28
    

  • Why likely flaky: Same Docker port conflict — shared fixture failure.
• Aspire.Hosting.Azure.Tests.AzureSqlPrincipalReconciliationTests.ReconciliationLeavesPrincipalsItDidNotCreateIntact in job Tests / Hosting.Azure / Hosting.Azure (ubuntu-latest)
  • Error: Class fixture type 'Aspire.Hosting.Azure.Tests.SqlServerContainerFixture' threw in InitializeAsync
    ---- Docker.DotNet.DockerApiException : Docker API responded with status code=InternalServerError, response={"message":"failed to bind host port for 0.0.0.0::172.17.0.3:1433/tcp: address already in use"}
  • Stack Trace (first frames):

    at Aspire.Hosting.Azure.Tests.SqlServerContainerFixture.InitializeAsync() in .../SqlServerContainerFixture.cs:line 28
    

  • Why likely flaky: Same Docker port conflict — shared fixture failure.
• Aspire.Hosting.Azure.Tests.AzureSqlPrincipalReconciliationTests.ReconciliationRollsBackWhenTheUserCannotBeRecreated in job Tests / Hosting.Azure / Hosting.Azure (ubuntu-latest)
  • Error: Class fixture type 'Aspire.Hosting.Azure.Tests.SqlServerContainerFixture' threw in InitializeAsync
    ---- Docker.DotNet.DockerApiException : Docker API responded with status code=InternalServerError, response={"message":"failed to bind host port for 0.0.0.0::172.17.0.3:1433/tcp: address already in use"}
  • Stack Trace (first frames):

    at Aspire.Hosting.Azure.Tests.SqlServerContainerFixture.InitializeAsync() in .../SqlServerContainerFixture.cs:line 28
    

  • Why likely flaky: Same Docker port conflict — shared fixture failure.
• Aspire.Hosting.Azure.Tests.AzureSqlPrincipalReconciliationTests.ReconciliationFailsWithoutDamageWhenThePrincipalOwnsASchema in job Tests / Hosting.Azure / Hosting.Azure (ubuntu-latest)
  • Error: Class fixture type 'Aspire.Hosting.Azure.Tests.SqlServerContainerFixture' threw in InitializeAsync
    ---- Docker.DotNet.DockerApiException : Docker API responded with status code=InternalServerError, response={"message":"failed to bind host port for 0.0.0.0::172.17.0.3:1433/tcp: address already in use"}
  • Stack Trace (first frames):

    at Aspire.Hosting.Azure.Tests.SqlServerContainerFixture.InitializeAsync() in .../SqlServerContainerFixture.cs:line 28
    

  • Why likely flaky: Same Docker port conflict — shared fixture failure.

Suggested actions:

• Re-run the failed CI jobs to confirm if the failure is intermittent
• If the test continues to fail, consider quarantining it using /quarantine-test <test name> <issue URL>
• Search existing issues to see if this test is already known to be flaky

You can re-run the failed jobs from the workflow run page.

[aspire-repo-bot]

📝 Documentation has been drafted in microsoft/aspire.dev#1512 targeting release/13.5.

Added new diagnostic pages for ASPIRE009, ASPIRE010, and ASPIRE011 (each with the message, an example, and fix/suppress guidance), and updated get-started/aspire-sdk.mdx to reflect the restored AspireUseCliBundle=false default, the new invocation resolution order (explicit path → forced DNX → aspire on PATH → dnx on PATH), and the pinned dnx --yes aspire.cli@$(AspireHostingSDKVersion) delegation behavior.

• src/frontend/src/content/docs/diagnostics/aspire009.mdx (new)
• src/frontend/src/content/docs/diagnostics/aspire010.mdx (new)
• src/frontend/src/content/docs/diagnostics/aspire011.mdx (new)
• src/frontend/src/content/docs/get-started/aspire-sdk.mdx (updated)

Note

This draft PR needs human review before merging.