Fix misleading AppHost build failure diagnostics

[Ella Hathaway (ellahathaway)]

Description

An AppHost can exist and still fail MSBuild evaluation — most commonly when Aspire.AppHost.Sdk cannot be resolved. ProjectLocator treated that signal (IsPossiblyUnbuildable) as "no such project", so the user was told the file did not exist, or that no AppHosts were found, and never saw the MSB4236 that explained the real problem.

This keeps the selection instead. An explicitly named file, an explicitly named directory holding a single candidate, and a configured aspire.config.json path are all deliberate user choices, so they are honored and the command's existing build path prints the diagnostics it already collects. That path needed no changes — it already stashes build output, reports FailedToBuildArtifacts, and displays the collected lines. The entire fix is contained in ProjectLocator.cs.

User-facing behavior

Before, for an AppHost whose SDK cannot be resolved:

--apphost ./MissingSdkAppHost/MissingSdkAppHost.csproj
  ❌ The --apphost option specified a project that does not exist.        (exit 7)

aspire.config.json -> ./MissingSdkAppHost/MissingSdkAppHost.csproj
  ❌ No AppHosts were found (there may be AppHost project files with
     syntax errors/invalid SDK versions).                                 (exit 7)

After, both paths reach the build and report what is actually wrong:

MissingSdkAppHost.csproj : error : Could not resolve SDK "Missing.AppHost.Sdk". Exactly one of the
probing messages below indicates why we could not resolve the SDK. Investigate and resolve that
message to correctly specify the SDK.
MissingSdkAppHost.csproj : error :   SDK resolver "Microsoft.DotNet.MSBuildWorkloadSdkResolver" returned null.
MissingSdkAppHost.csproj : error :   The NuGetSdkResolver did not resolve this SDK because there was
no version specified in the project or global.json.
MissingSdkAppHost.csproj : error MSB4236: The SDK 'Missing.AppHost.Sdk' specified could not be found.

Build FAILED.

❌ The project could not be built.                                        (exit 6)

What deliberately did not change

Ambient discovery. Finding only unbuildable candidates while scanning the working directory is still AppHostsMayNotBeBuildable mapped to FailedToFindProject. AppHostConnectionResolver.IsProjectResolutionError keys off that exit code to tell "AppHost not running" apart from "no project resolved"; remapping it makes stop/logs/describe/ps emit success-shaped output. AppHostConnectionResolverTests guards this.

Unsupported projects. IsUnsupported (for example a guest language unavailable in the current environment) still falls back to discovery. Only IsPossiblyUnbuildable is reinterpreted — the two were previously conflated in one theory, which is now split into two focused tests.

Ambiguous directories. An explicit directory containing more than one unbuildable candidate is a genuine ambiguity rather than a selection, so it still fails resolution. Candidates injected into the walk from a parent directory's config are excluded from that count, so --apphost ./some-dir never auto-selects a project that is not under ./some-dir.

Settings are never written from an unverified selection. A candidate kept only because MSBuild failed was never confirmed to be an AppHost; persisting it would let later ambient invocations silently reuse the guess.

Validation

• ProjectLocatorTests — 98 tests (97 passed, 1 Windows-only skip), including 8 new regression tests covering the explicit-file, explicit-directory, configured, out-of-directory, and multiple-healthy-candidate paths.
• RunCommandTests, UpdateCommandTests, AppHostConnectionResolverTests, AddCommandTests — 227/227.
• End-to-end (RunReportsMissingSdkAsBuildFailureForDotNetAppHost) run in Docker against a locally built CLI. The asciinema recording confirms MSB4236 reaches the terminal, the shell reports exit code 6, and neither of the two misleading messages appears.

Fixes #19035

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
    • If yes, have you done a threat model and had a security review?
      • Yes
      • No
  • No

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Note

This error may be related to your runner configuration. You can now configure runners for Copilot code review separately from Copilot cloud agent by creating a copilot-code-review.yml file with your setup steps. Read the docs for details.

[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 -- 19082

Or

• Run remotely in PowerShell:

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

[Copilot]

Pull request overview

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

Suppressed comments (1)

src/Aspire.Cli/Commands/RunCommand.cs:589

• The new build_failed telemetry classification is not covered by the added tests: the locator tests stop at the exception/exit-code mapping, and the E2E test only checks terminal output. Since RunCommandTests already verifies ErrorType tags, add a case whose locator throws AppHostsMayNotBeBuildable and assert that the run activity records build_failed; otherwise this advertised telemetry behavior can regress without any test failing.

            runActivity?.SetTag(
                TelemetryConstants.Tags.ErrorType,
                ex.FailureReason is ProjectLocatorFailureReason.AppHostsMayNotBeBuildable ? "build_failed" : "project_not_found");

[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]

Review details

Suppressed comments (1)

src/Aspire.Cli/Projects/ProjectLocator.cs:604

• On case-sensitive macOS volumes, OrdinalIgnoreCase treats sibling directories such as Services and services as the same subtree. Because discovery injects candidates from parent configuration, --apphost ./Services can therefore auto-select an unverified configured project under ./services, defeating the containment check this helper was added to enforce. Please determine case sensitivity for the actual volume (or compare filesystem identity) rather than assuming all macOS paths are case-insensitive.

        var pathComparison = environment.IsWindows() || environment.IsMacOS()
            ? StringComparison.OrdinalIgnoreCase
            : StringComparison.Ordinal;

• Files reviewed: 7/7 changed files
• Comments generated: 0 new
• Review effort level: Balanced