microsoft / microsoft/aspire

CLI should block/warn when running against an AppHost targeting a newer Aspire version than the CLI supports

Open
#19,626 0 comments 0 reactions 0 assignees View on GitHub
area-cli
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.