CLI should block/warn when running against an AppHost targeting a newer Aspire version than the CLI supports
- Dominant language
- C#
- Stars
- 6.3k
- Forks
- 991
- Avg merge
- 2d 15h
- Merged PRs (30d)
- 196
Description
## Summary
Today `Aspire.Cli`'s AppHost compatibility check (`AppHostHelper.EvaluateAppHostCompatibility` in `src/Aspire.Cli/Utils/AppHostHelper.cs`) only enforces a **minimum** `Aspire.Hosting` SDK version (currently `9.2.0`). It does not check the other direction: what happens when the AppHost targets an **Aspire version newer than the installed CLI supports**.
In that scenario, an older CLI can attempt to run/build/publish an AppHost that was written for a newer Aspire release. Depending on what changed between versions, this can silently misbehave (missing backchannel capabilities, unsupported commands/resources, confusing errors deep in execution) instead of failing fast with a clear, actionable message telling the user to update their CLI.
## Proposed change
Add a compatibility check that compares the AppHost's `Aspire.Hosting` SDK version against the CLI's own version (and/or the max version it knows how to support) and blocks execution with a clear error (e.g. "Update the Aspire CLI to version X or later to run this AppHost") when the AppHost's Aspire version is newer than what the CLI supports.
Considerations:
- Where to source "the version the CLI supports" from (CLI package version vs. an explicit supported-range constant).
- Whether this should be a hard block or a warning, and whether it should be configurable/overridable (similar to `overrideMinimumSdkVersion` used for the SDK installer).
- Interaction with existing `AppHostIncompatibleException` / `RequiredCapability` backchannel-based incompatibility handling, which currently only surfaces once a specific capability is missing at call time, rather than up front.
- User experience should be consistent with the existing `ErrorStrings.AspireSDKVersionNotSupported` messaging used for the minimum-version case.
## Context
Raised from a Teams conversation about CLI/AppHost version mismatches — using an older Aspire CLI against an app that targets a newer Aspire version should fail fast with a clear message rather than behaving unpredictably.
Contributor guide
Research direction
Start in src/Aspire.Cli/Utils/AppHostHelper.cs at EvaluateAppHostCompatibility, then read AppHostIncompatibleException, RequiredCapability, and ErrorStrings.AspireSDKVersionNotSupported. Trace how the CLI version or supported range is exposed and how the minimum-version check is tested. Done means a newer AppHost Aspire.Hosting version is handled up front with consistent, actionable messaging and appropriate coverage for the chosen block or warning behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp
- Domain
- cli, developer-experience
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 54/100