Keep launch-configuration AppHost targets out of the workspace default

[Adam Ratzman (adamint)]

Fixes #19080

Problem

A repo with several AppHosts gives each one its own VS Code launch configuration, pointing program at a different AppHost. Launching any of them rewrites aspire.config.json to name that AppHost as the workspace default. Alternating between two configurations means the file is rewritten on every launch, so it shows up as a modified file in every commit and every AppHost-agnostic command follows whichever one ran last.

Picking a target for one debug session is not a statement about what the workspace defaults to, but the CLI could not tell the two apart. Every path into UseOrFindAppHostProjectFileAsync passed createSettingsFile: true, so any resolved selection was persisted.

Approach

The extension classifies where an AppHost selection came from and forwards it to the CLI in ASPIRE_CLI_APPHOST_SELECTION_ORIGIN:

Origin	Meaning	Persists?
explicit-launch-configuration	launch.json named this AppHost	Only when there is no default yet
default-discovery	The extension resolved it	Yes
user-selection	The user picked it from a prompt	Yes

The CLI rule is establish, but never replace. An explicit launch configuration may write the default when the workspace has none, and is otherwise a no-op.

The "establish" half matters. Blanket suppression looked cleaner but regressed single-AppHost repos: checkForExistingAppHostPathInWorkspace prompts on every activation while no config exists, and previously the first F5 wrote the file and ended the prompting. I confirmed on the real binary that suppressing the write turns a self-resolving flow into a recurring prompt.

The gate lives in ProjectLocator.CreateSettingsFileAsync, the single writer of appHost.path for selection persistence. launch.json can name run, deploy, publish, or do, and all of them reach this method, so gating RunCommand alone would have left the other three rewriting the file.

Without the environment variable the behavior is unchanged.

Notable details

• launch.json never gets stamped. VS Code serializes an Initial-kind provider's provideDebugConfigurations result verbatim into a new launch.json. Stamping the origin there would bake default-discovery into a user-owned file and pin it forever, reproducing Launching aspire from different vscode launch configurations (using the extension) overrides the aspire.config.json file #19080 for extension-generated configurations. Only the Dynamic provider stamps, so the two are now registered as separate instances.
• A recorded default is read the way the CLI resolves it. The check reuses the config the upward search already loaded, so a legacy .aspire/settings.json workspace is not mistaken for having no default, and it normalizes separators so a config committed from Windows is understood on a Unix checkout.
• A recorded default survives even when its file is missing. Missing is indistinguishable from a branch switch or a sparse checkout, and treating it as "nothing to preserve" would let the next launch permanently re-point a default the user still wants. Stale entries are still healed by the other origins, the startup prompt, and aspire config set — every path that carries a deliberate choice.

Testing

• ProjectLocatorTests and RunCommandTests: 168 tests, 0 failures. New coverage for each origin, for establishing a default, for preserving one across alternating launches (a direct Launching aspire from different vscode launch configurations (using the extension) overrides the aspire.config.json file #19080 repro), for a legacy .aspire/settings.json workspace, for a Windows-authored path, and for a recorded default whose file is gone.
• Extension unit tests: 1436 passing, including 3 new tests covering the trigger-kind split.
• New E2E test asserting that switching named launch configurations leaves the workspace default alone.
• Verified against the built CLI: run and publish, with and without the variable, alternating launches, the single-AppHost establish path, and healing through user-selection.

Pre-existing issue found while testing (not fixed here)

A hand-authored appHost.path containing a NUL byte (or another Path.GetInvalidPathChars() character) crashes aspire run with An unexpected error occurred: Null character in path. This is the same class of bug as #17624. The canonical readers guard their resolution with IsValidConfiguredAppHostPath, but the upward config search in CreateSettingsFileAsync does not.

It reproduces on main with no environment variable set, and this PR adds no new unguarded resolution — git diff against the merge base shows zero added Path.GetFullPath or Path.IsPathRooted calls. Flagging it because anyone probing the new preservation logic with a hostile config will hit it, and it should not be read as a regression from this change. Tracked separately as #19137.

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

Or

• Run remotely in PowerShell:

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

[Copilot]

Pull request overview

Prevents explicit VS Code launch configurations from changing the workspace’s persisted default AppHost.

Changes:

• Adds AppHost-selection provenance across the extension-to-CLI boundary.
• Suppresses configuration persistence for explicit launch targets.
• Adds unit and extension E2E regression coverage.

Show a summary per file

File	Description
tests/Aspire.Cli.Tests/Utils/CliTestHelper.cs	Supplies CLI configuration to ProjectLocator.
tests/Aspire.Cli.Tests/Projects/ProjectLocatorTests.cs	Tests origin-based persistence behavior.
tests/Aspire.Cli.Tests/Commands/RunCommandTests.cs	Verifies commands request centralized persistence.
src/Shared/KnownConfigNames.cs	Defines the provenance environment variable.
src/Aspire.Cli/Projects/ProjectLocator.cs	Suppresses persistence for explicit launch configurations.
extension/src/utils/environment.ts	Adds the environment-variable identifier.
extension/src/types/extensionApi.ts	Adds E2E named-configuration launching.
extension/src/testing/e2eStateFileBridge.ts	Implements the new E2E control command.
extension/src/test/aspireDebugSession.test.ts	Tests provenance forwarding to the CLI.
extension/src/test/aspireDebugConfigurationProvider.test.ts	Tests provenance classification and preservation.
extension/src/test/appHostLaunchService.test.ts	Verifies user-selection classification.
extension/src/test-e2e/debugDashboard.e2e.test.ts	Covers alternating named launch configurations.
extension/src/services/AppHostLaunchService.ts	Marks UI-selected AppHosts.
extension/src/server/interactionService.ts	Classifies RPC-started debug sessions.
extension/src/debugger/AspireDebugSession.ts	Passes provenance through the CLI environment.
extension/src/debugger/AspireDebugConfigurationProvider.ts	Classifies launch targets by origin.
extension/src/debugger/AspireDebugConfigurationMetadata.ts	Defines internal provenance metadata.
extension/src/dcp/types.ts	Types the provenance field.

Review details

• Files reviewed: 18/18 changed files
• Comments generated: 1
• Review effort level: Balanced

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

extension/src/debugger/AspireDebugConfigurationProvider.ts:90

• The documented contract says any program that resolves to a directory is downgraded to default-discovery and therefore persists the selected AppHost. This condition only does that for the workspace root; AppHost subdirectories remain explicit-launch-configuration (as the new test also codifies). Please align the implementation and tests with the stated directory behavior, or update the PR description if subdirectories are intentionally session-scoped.

            if (aspireConfig[appHostSelectionOriginConfigKey] === 'explicit-launch-configuration' && this.isWorkspaceFolderRoot(program, folder)) {
                // Only a program pointing at the workspace folder root delegates the choice back to
                // normal discovery, which is what the extension's own default configuration does. A
                // configuration naming a specific AppHost file *or* subdirectory is scoped to that
                // target and must not become the workspace default.
                aspireConfig[appHostSelectionOriginConfigKey] = 'default-discovery';

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

[Copilot]

Review details

Suppressed comments (1)

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

• This summary contradicts the persistence rule below: an explicit launch target can become the workspace default when no valid default exists; it only must not replace an existing valid default. Describing it as “never” becoming the default could lead future changes to break the intentional first-launch behavior.

    /// <summary>
    /// Identifies a CLI invocation whose AppHost target came from an editor launch configuration
    /// (for example a VS Code <c>launch.json</c> entry with an explicit <c>program</c>). Such a target
    /// is owned by the individual debug session, so it must never become the workspace default.
    /// </summary>

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

[Copilot]

Review details

Suppressed comments (2)

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

• This process-scoped handoff is being read through the merged IConfiguration, but workspace/global settings are registered after environment variables (Program.cs:299-312, ConfigurationHelper.cs:73-83) and therefore take precedence. A same-named top-level setting can make an explicit launch rewrite the default, or make ordinary CLI invocations suppress persistence. Read this internal signal from the existing IEnvironment.GetEnvironmentVariable(...) abstraction instead, and remove the new IConfiguration constructor plumbing.

        var isExplicitLaunchConfiguration = string.Equals(
            configuration[KnownConfigNames.CliAppHostSelectionOrigin],
            ExplicitLaunchConfigurationSelectionOrigin,
            StringComparison.OrdinalIgnoreCase);

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

• This documentation contradicts the implemented “establish, but never replace” rule: CreateSettingsFileAsync intentionally allows this origin to become the default when none exists. Describe that exception so future callers do not incorrectly suppress all persistence.

    /// Identifies a CLI invocation whose AppHost target came from an editor launch configuration
    /// (for example a VS Code <c>launch.json</c> entry with an explicit <c>program</c>). Such a target
    /// is owned by the individual debug session, so it must never become the workspace default.
    /// </summary>

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

[Copilot]

Review details

Suppressed comments (1)

tests/Aspire.Cli.Tests/DotNet/ProcessExecutionFactoryEnvironmentTests.cs:21

• These tests mutate process-wide environment variables, but this class is not serialized with the repository's existing EnvVarMutatingTestCollection. While the overrides on lines 42–43 or 78 are active, an unrelated test can snapshot ASPIRE_CLI_APPHOST_SELECTION_ORIGIN into IConfiguration or a child process and unexpectedly suppress its config write. Put this class in the same non-parallel collection used by the other EnvVarOverride suites.

public sealed class ProcessExecutionFactoryEnvironmentTests

• Files reviewed: 25/25 changed files
• Comments generated: 1
• Review effort level: Balanced

[Copilot]

Review details

Suppressed comments (2)

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

• This summary contradicts the implemented “establish, but never replace” rule: an explicit launch target does become the workspace default when none exists. Describe that exception here so future changes do not incorrectly suppress establishment altogether.

    /// is owned by the individual debug session, so it must never become the workspace default.

tests/Aspire.Cli.Tests/DotNet/ProcessExecutionFactoryEnvironmentTests.cs:21

• This class mutates process-wide environment variables with EnvVarOverride but is not in the repository’s non-parallel environment-variable collection. xUnit can run it alongside CLI tests that build configuration from the environment, causing them to transiently observe ASPIRE_CLI_APPHOST_SELECTION_ORIGIN and suppress persistence. Join EnvVarMutatingTestCollection, as done by InstallationDiscoveryDiscoverAllTests.cs:28 and NpmRunnerTests.cs:15.

public sealed class ProcessExecutionFactoryEnvironmentTests

• Files reviewed: 25/25 changed files
• Comments generated: 1
• Review effort level: Balanced

[Copilot]

Review details

Suppressed comments (1)

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

• On case-insensitive macOS volumes, differently cased paths can identify the same config directory but produce different lock hashes here. That bypasses the cross-process serialization and allows compound launches to both establish/rewrite the same default. Canonicalize case on macOS as well; on a case-sensitive macOS volume, an occasional false collision only serializes unrelated writes and does not affect correctness.

        if (OperatingSystem.IsWindows())
        {
            normalizedRoot = normalizedRoot.ToLowerInvariant();
        }

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

[Copilot]

Review details

Suppressed comments (2)

tests/Aspire.Cli.Tests/DotNet/ProcessExecutionFactoryEnvironmentTests.cs:21

• These tests mutate process-wide environment variables via EnvVarOverride, but this class is not in the assembly's nonparallel EnvVarMutatingTestCollection. While lines 42/78 set the selection origin, any concurrently running CLI test that builds IConfiguration can observe explicit-launch-configuration and unexpectedly suppress settings writes. Add this class to the existing collection defined at InstallationDiscoveryDiscoverAllTests.cs:1037.

public sealed class ProcessExecutionFactoryEnvironmentTests

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

• This summary contradicts the implemented “establish, but never replace” rule: lines 1114-1128 intentionally allow an explicit launch target to become the default when none exists. Describe the actual constraint as not replacing an already-recorded default so future maintenance does not suppress the required establish behavior.

    /// <summary>
    /// Identifies a CLI invocation whose AppHost target came from an editor launch configuration
    /// (for example a VS Code <c>launch.json</c> entry with an explicit <c>program</c>). Such a target
    /// is owned by the individual debug session, so it must never become the workspace default.
    /// </summary>

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

[Copilot]

Review details

Suppressed comments (3)

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

• This second lookup still cannot see a sibling legacy .aspire/settings.json when aspire.config.json exists but omits appHost.path: GetConfigurationFromDirectoryAsync stops at the modern file before checking legacy, whereas the canonical AppHost reader falls back to legacy in that case. In such split-layout workspaces, an explicit launch misses the recorded default and writes its target into the modern file. Use a local AppHost-specific presence lookup that checks the modern path and then the sibling legacy path.

                ?? await configurationService.GetConfigurationFromDirectoryAsync(LegacySettingsAppHostPathKey, configRootDirectory, cancellationToken: cancellationToken);

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

• This lookup falls back to the global settings file, but global appHost.path values are explicitly ignored (Program.WarnIfGlobalSettingsContainAppHostPath, lines 199-210). A leftover global value therefore makes recordedDefault nonempty and prevents an explicit launch from establishing the missing workspace default, reintroducing the recurring-prompt behavior this PR is intended to preserve. Read only the local config target here, without the global fallback.

This issue also appears on line 1159 of the same file.

            var recordedDefault = await configurationService.GetConfigurationFromDirectoryAsync(AspireConfigAppHostPathKey, configRootDirectory, cancellationToken: cancellationToken)

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

• This documentation contradicts the implemented “establish, but never replace” policy: an explicit launch target may become the workspace default when none exists. State that it must not replace an existing default instead.

    /// is owned by the individual debug session, so it must never become the workspace default.

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

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

Review details

Suppressed comments (2)

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

• This summary contradicts the implemented “establish, but never replace” rule: lines 1136–1141 intentionally allow an explicit launch configuration to become the workspace default when none exists. Describe that exception here so future changes do not turn this into blanket suppression.

    /// is owned by the individual debug session, so it must never become the workspace default.

tests/Aspire.Cli.Tests/Projects/ProjectLocatorTests.cs:119

• This test only proves that session-scoped origins do not replace an already-recorded default; such origins do persist when no default exists, as the test at line 152 demonstrates. Rename it to reflect the narrower contract and avoid contradicting the establish-but-never-replace behavior.

    public async Task UseOrFindAppHostProjectFileDoesNotPersistSelectionFromSessionScopedOrigins(string selectionOrigin)

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

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

Review details

Suppressed comments (3)

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

• GetConfigurationFromDirectoryAsync falls back to the global settings file (ConfigurationService.cs:403-419), but global AppHost paths are explicitly ignored by the CLI (Program.cs:199-210). A user with a stale global appHost.path and no workspace default will therefore hit this branch and skip the “establish” write, leaving the workspace without a default and restoring the recurring activation prompt this PR is intended to avoid. Read only the resolved workspace target here; the legacy layout has already been migrated by ResolveWorkspaceConfigTarget.

            var recordedDefault = await configurationService.GetConfigurationFromDirectoryAsync(AspireConfigAppHostPathKey, configRootDirectory, cancellationToken: cancellationToken)
                ?? await configurationService.GetConfigurationFromDirectoryAsync(LegacySettingsAppHostPathKey, configRootDirectory, cancellationToken: cancellationToken);

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

• This documentation contradicts the implemented “establish, but never replace” rule: an explicit launch target does become the workspace default when none exists. Describe it as unable to replace an existing default so future changes do not incorrectly suppress the establish path.

    /// <summary>
    /// Identifies a CLI invocation whose AppHost target came from an editor launch configuration
    /// (for example a VS Code <c>launch.json</c> entry with an explicit <c>program</c>). Such a target
    /// is owned by the individual debug session, so it must never become the workspace default.
    /// </summary>

tests/Aspire.Cli.Tests/DotNet/ProcessExecutionFactoryEnvironmentTests.cs:21

• These tests mutate process-wide environment variables, so running them in parallel with other CLI tests can transiently mark unrelated ProjectLocator or child-process tests as explicit-launch-configuration. The repository’s existing convention is to place every EnvVarOverride test in EnvVarMutatingTestCollection, whose collection definition disables parallelization (InstallationDiscoveryDiscoverAllTests.cs:20-25,1037-1039; see NpmRunnerTests.cs:15). Add this class to that collection to prevent nondeterministic cross-test contamination.

public sealed class ProcessExecutionFactoryEnvironmentTests

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