Skip to content

Report configuration source availability in aspire doctor - #22197

Draft
James Newton-King (JamesNK) wants to merge 3 commits into
mainfrom
jamesnk/doctor-config-sources-rebased
Draft

James Newton-King (JamesNK) wants to merge 3 commits into
mainfrom
jamesnk/doctor-config-sources-rebased

Conversation

@JamesNK

Copy link
Copy Markdown
Member

Description

Existing AppHosts do not indicate when a machine configuration source is available but has not been adopted. aspire doctor now reports the available machine source and the detected AppHost's saved binding, explicit opt-out, or missing selection. An unconfigured AppHost gets a non-blocking warning suggesting aspire update.

The check uses doctor's existing shallow AppHost discovery and reports failed or timed-out source detection without treating it as a confirmed absence. It does not prompt, acquire configuration from Git, or write settings. JSON output includes the diagnostic states and metadata.

This reapplies #21677, which was merged into its feature branch after #21678 had already landed on main.

User-facing usage

aspire doctor
aspire doctor --format json

With a synthetic machine source and an AppHost that has no saved choice, the table output includes:

AppHost
  🚨 A configuration source is available, but this AppHost has not selected a configuration source.
       Run 'aspire update' to choose whether this AppHost should use the available configuration source.

Environment
  ✅ A configuration source is available on this machine.

Screenshots / Recordings

This PR includes UI changes. Please add screenshots or screen recordings so reviewers can evaluate the visual changes without running locally.

  • For before/after comparisons, place them side-by-side or label them clearly.
  • For interactive changes (animations, transitions, new flows), prefer a short screen recording (GIF or video).
  • If you cannot capture visuals now, note what scenario to test and mark this section as TODO.

TODO: Capture the available-source warning and the saved-binding and opt-out states. Terminal capture could not start in this environment.

Validation

  • Passed: 373 tests covering doctor, source discovery, and source-selection regressions:

    $env:MSBUILDTERMINALLOGGER = 'false'
    dotnet test --project tests\Aspire.Cli.Tests\Aspire.Cli.Tests.csproj --no-restore --no-launch-profile -- --filter-class '*.ConfigSourceCheckTests' --filter-class '*.DoctorCommandTests' --filter-class '*.EnvironmentCheckerTests' --filter-class '*.ConfigSourceServiceTests' --filter-class '*.ConfigSourceCommandTests' --filter-not-trait 'quarantined=true' --filter-not-trait 'outerloop=true'
  • Passed: dotnet build src\Aspire.Cli\Aspire.Cli.csproj --no-restore /t:UpdateXlf regenerated localization files without warnings or errors.

  • Passed: source-built aspire.exe doctor --format json --non-interactive with a synthetic source and an unconfigured AppHost reported both the machine candidate and the AppHost warning.

  • Passed: source-built aspire.exe doctor --non-interactive --nologo with the same scenario produced the table output shown above.

  • Passed: git diff --check origin/main...HEAD.

Fixes # (issue)

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

Existing AppHosts do not currently tell users when an organization
configuration source is available but has not been adopted. `aspire
doctor` now reports machine source availability and the current
AppHost's saved configuration-source choice, with a non-blocking
suggestion to run `aspire update` when no choice has been recorded.

**PR stack:** `main` -> #21678 (brownfield adoption) -> this doctor PR.

**Stacked PR:** depends on #21678 and targets
[`jamesnk/config-source-brownfield`](https://github.com/microsoft/aspire/tree/jamesnk/config-source-brownfield),
which contains brownfield adoption and persisted `configSource.optOut`
support. This PR adds only the doctor diagnostics and their supporting
discovery extraction, tests, localization, and documentation.

- Report environment-variable and Microsoft-employee source candidates,
including their discovery origin.
- Report an AppHost's saved binding or explicit opt-out without
suggesting adoption.
- Include stable diagnostic names and metadata in JSON output.
- Reuse doctor's shallow AppHost discovery and extract candidate
resolution without consent prompts, Git acquisition, remote-version
checks, or configuration writes.

Project diagnostics currently inspect the nearest local configuration.
Reporting and accounting for saved global source bindings remains
follow-up work; a project using global defaults can still receive the
local-adoption warning.

```shell
aspire doctor
aspire doctor --format json
```

Relevant existing command help, also exercised by the doctor tests:

```text
Usage:
  aspire doctor [options]

Options:
  --format <Json|Table>  Output format (Table or Json)
```

When a candidate is available and the AppHost has no recorded choice,
doctor reports a warning with:

```text
Run 'aspire update' to choose whether this AppHost should use the available configuration source.
```

JSON output includes the `config-source` environment check and, when
applicable, the `apphost-config-source` check with a `bound`,
`optedOut`, or `unconfigured` state. An explicit opt-out is reported as
an intentional choice, not something to fix.

> **This PR includes UI changes.** Please add screenshots or screen
recordings so reviewers can evaluate the visual changes without running
locally.
>
> - For before/after comparisons, place them side-by-side or label them
clearly.
> - For interactive changes (animations, transitions, new flows), prefer
a short screen recording (GIF or video).
> - If you cannot capture visuals now, note what scenario to test and
mark this section as TODO.

TODO: Capture `aspire doctor` with `ASPIRE_INIT_SOURCE_URL` set in an
AppHost with no saved source choice, showing availability, the adoption
warning, and its suggested fix. Also capture saved-binding and
explicit-opt-out states. No visual capture was made during this change.

<!-- Add screenshots/recordings here -->

Focused validation rerun after splitting the branches: **passed, 52
succeeded, 0 failed, 0 skipped**.

```powershell
$env:MSBUILDTERMINALLOGGER='false'
dotnet test --project tests\Aspire.Cli.Tests\Aspire.Cli.Tests.csproj --no-launch-profile -- --filter-class "*.ConfigSourceCheckTests" --filter-class "*.DoctorCommandTests" --filter-class "*.EnvironmentCheckerTests" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true"
```

Broader doctor, creation, and config-source regression coverage, run
before splitting the same implementation into commits: **passed, 784
succeeded, 0 failed, 2 skipped**.

```powershell
$env:MSBUILDTERMINALLOGGER='false'
dotnet test --project tests\Aspire.Cli.Tests\Aspire.Cli.Tests.csproj --no-launch-profile -- --filter-class "*.ConfigSourceCheckTests" --filter-class "*.DoctorCommandTests" --filter-class "*.EnvironmentCheckerTests" --filter-class "*.ConfigSourceServiceTests" --filter-class "*.ConfigSourceCommandTests" --filter-class "*.NewCommandLocalTemplateTests" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true"
```

Localization regeneration: **passed, 0 warnings and 0 errors**.

```powershell
dotnet build src\Aspire.Cli\Aspire.Cli.csproj /t:UpdateXlf
```

Doctor-only diff whitespace validation: **passed**.

```powershell
git diff --check jamesnk/config-source-brownfield...jamesnk/doctor-config-sources
```

The full repository suite and manual visual verification were not run.

Fixes # (issue)

- Is this feature complete?
  - [ ] Yes. Ready to ship.
  - [x] No. Follow-up changes expected.
- Are you including unit tests for the changes and scenario tests if
relevant?
  - [x] 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
  - [x] 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
  - [x] No

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@github-actions

Copy link
Copy Markdown
Contributor

🚀 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 -- 22197

Or

  • Run remotely in PowerShell:
iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 22197"

@github-actions

This comment has been minimized.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Doctor startup can rewrite existing flat-key settings despite the documented no-write guarantee, and packaged-CLI E2E coverage does not verify the new diagnostics.

2 open issues
1 file not reviewed
  • src/Aspire.Cli/Resources/ConfigSourceStrings.Designer.cs: Generated file
What changed in this PR

This PR reapplies the doctor diagnostics from #21677 on top of the configuration-source adoption support in #21678. It reports machine source availability and the detected AppHost’s saved choice, with a non-blocking adoption suggestion when appropriate.

Changes:

  • Add configuration-source diagnostics and structured JSON metadata, distinguishing detection failures from confirmed absence.
  • Share shallow AppHost discovery and separate candidate resolution from source acquisition.
  • Add unit tests, JSON snapshots, localized resources, and documentation.
File Description
tests/​Aspire.Cli.Tests/​Utils/​ConfigSourceCheckTests.cs Tests discovery, saved choices, failures, cancellation, and side effects.
tests/​Aspire.Cli.Tests/​Utils/​CliTestHelper.cs Registers the new check in test services.
tests/​Aspire.Cli.Tests/​Snapshots/​DoctorCommandTests.DoctorCommand_Json_ReportsConfigSourcesWithoutAcquisitionOrConfigurationWrites_state=unconfigured.verified.json Captures the adoption warning.
tests/​Aspire.Cli.Tests/​Snapshots/​DoctorCommandTests.DoctorCommand_Json_ReportsConfigSourcesWithoutAcquisitionOrConfigurationWrites_state=optedOut.verified.json Captures explicit opt-out output.
tests/​Aspire.Cli.Tests/​Snapshots/​DoctorCommandTests.DoctorCommand_Json_ReportsConfigSourcesWithoutAcquisitionOrConfigurationWrites_state=noAppHost.verified.json Captures machine-only diagnostics.
tests/​Aspire.Cli.Tests/​Snapshots/​DoctorCommandTests.DoctorCommand_Json_ReportsConfigSourcesWithoutAcquisitionOrConfigurationWrites_state=bound.verified.json Captures saved-binding metadata.
tests/​Aspire.Cli.Tests/​Snapshots/​DoctorCommandTests.DoctorCommand_Json_DistinguishesInconclusiveConfigSourceDetection_outcome=timed_out.verified.json Captures detection timeout output.
tests/​Aspire.Cli.Tests/​Snapshots/​DoctorCommandTests.DoctorCommand_Json_DistinguishesInconclusiveConfigSourceDetection_outcome=not_detected.verified.json Captures confirmed source absence.
tests/​Aspire.Cli.Tests/​Snapshots/​DoctorCommandTests.DoctorCommand_Json_DistinguishesInconclusiveConfigSourceDetection_outcome=failed.verified.json Captures detection failure output.
tests/​Aspire.Cli.Tests/​Commands/​DoctorCommandTests.cs Adds command-level JSON and side-effect assertions.
src/​Aspire.Cli/​Utils/​EnvironmentChecker/​EnvironmentChecker.cs Extracts shared shallow AppHost discovery.
src/​Aspire.Cli/​Utils/​EnvironmentChecker/​ConfigSourceCheck.cs Implements machine and AppHost source diagnostics.
src/​Aspire.Cli/​Utils/​EnvironmentChecker/​AspireVersionCheck.cs Uses the shared discovery helper.
src/​Aspire.Cli/​Resources/​xlf/​ConfigSourceStrings.zh-Hant.xlf Adds Traditional Chinese localization entries.
src/​Aspire.Cli/​Resources/​xlf/​ConfigSourceStrings.zh-Hans.xlf Adds Simplified Chinese localization entries.
src/​Aspire.Cli/​Resources/​xlf/​ConfigSourceStrings.tr.xlf Adds Turkish localization entries.
src/​Aspire.Cli/​Resources/​xlf/​ConfigSourceStrings.ru.xlf Adds Russian localization entries.
src/​Aspire.Cli/​Resources/​xlf/​ConfigSourceStrings.pt-BR.xlf Adds Brazilian Portuguese localization entries.
src/​Aspire.Cli/​Resources/​xlf/​ConfigSourceStrings.pl.xlf Adds Polish localization entries.
src/​Aspire.Cli/​Resources/​xlf/​ConfigSourceStrings.ko.xlf Adds Korean localization entries.
src/​Aspire.Cli/​Resources/​xlf/​ConfigSourceStrings.ja.xlf Adds Japanese localization entries.
src/​Aspire.Cli/​Resources/​xlf/​ConfigSourceStrings.it.xlf Adds Italian localization entries.
src/​Aspire.Cli/​Resources/​xlf/​ConfigSourceStrings.fr.xlf Adds French localization entries.
src/​Aspire.Cli/​Resources/​xlf/​ConfigSourceStrings.es.xlf Adds Spanish localization entries.
src/​Aspire.Cli/​Resources/​xlf/​ConfigSourceStrings.de.xlf Adds German localization entries.
src/​Aspire.Cli/​Resources/​xlf/​ConfigSourceStrings.cs.xlf Adds Czech localization entries.
src/​Aspire.Cli/​Resources/​ConfigSourceStrings.resx Defines diagnostic messages and source details.
src/​Aspire.Cli/​Resources/​ConfigSourceStrings.Designer.cs Exposes the new resource strings.
src/​Aspire.Cli/​Program.cs Registers the configuration-source check.
src/​Aspire.Cli/​Configuration/​ConfigSourceService.cs Separates candidate discovery from acquisition.
docs/​specs/​cli-output-formats.md Documents diagnostic names and JSON metadata.
docs/​specs/​cli-config-sources.md Documents availability checks and saved-choice reporting.

Review effort: Balanced

Comment thread docs/specs/cli-config-sources.md Resolved
Comment thread src/Aspire.Cli/Program.cs

// Environment checking services.
builder.Services.AddSingleton<IEnvironmentCheck, AspireVersionCheck>();
builder.Services.AddSingleton<IEnvironmentCheck, ConfigSourceCheck>();
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Cover an AppHost bound to the machine configuration source and an AppHost where a source is available but unused, asserting table and JSON output and unchanged project settings.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues require changes to the configuration-source diagnostics.

1 open issue
1 resolved since last review
1 file not reviewed
  • src/Aspire.Cli/Resources/ConfigSourceStrings.Designer.cs: Generated file

Review effort: Balanced

@github-actions

Copy link
Copy Markdown
Contributor

Tests selector

3 / 101 PR test projects · 4 PR jobs, from 33 changed files.

Selected PR test projects (3 / 101)

Aspire.Cli.EndToEnd.Tests, Aspire.Cli.Tests, Infrastructure.Tests

Selected PR jobs (4)

cli-starter-validation, extension-e2e, polyglot, typescript-api-compat


How these were chosen — grouped by what changed

📦 affected project Aspire.Cli
→ 1 test: Aspire.Cli.EndToEnd.Tests

🔧 src/Aspire.Cli/Resources/ConfigSourceStrings.Designer.cs (changed source)
→ 1 via the project graph: Aspire.Cli.EndToEnd.Tests

🔧 src/Aspire.Cli/Resources/ConfigSourceStrings.resx (changed source)
→ 1 directly: Infrastructure.Tests

🧪 tests/Aspire.Cli.EndToEnd.Tests/Aspire.Cli.EndToEnd.Tests.csproj (changed test)
→ 1 directly: Aspire.Cli.EndToEnd.Tests

🧪 tests/Aspire.Cli.EndToEnd.Tests/ConfigSourceTests.cs (changed test)
→ 1 directly: Aspire.Cli.EndToEnd.Tests

🧪 tests/Aspire.Cli.EndToEnd.Tests/Helpers/ConfigSourceTestContext.cs (changed test)
→ 1 directly: Aspire.Cli.EndToEnd.Tests

🧪 tests/Aspire.Cli.Tests/Commands/DoctorCommandTests.cs (changed test)
→ 1 directly: Aspire.Cli.Tests

🧪 tests/Aspire.Cli.Tests/Snapshots/DoctorCommandTests.DoctorCommand_Json_DistinguishesInconclusiveConfigSourceDetection_outcome=failed.verified.json (changed test)
→ 1 directly: Aspire.Cli.Tests

🧪 tests/Aspire.Cli.Tests/Snapshots/DoctorCommandTests.DoctorCommand_Json_DistinguishesInconclusiveConfigSourceDetection_outcome=not_detected.verified.json (changed test)
→ 1 directly: Aspire.Cli.Tests

🧪 tests/Aspire.Cli.Tests/Snapshots/DoctorCommandTests.DoctorCommand_Json_DistinguishesInconclusiveConfigSourceDetection_outcome=timed_out.verified.json (changed test)
→ 1 directly: Aspire.Cli.Tests

🧪 tests/Aspire.Cli.Tests/Snapshots/DoctorCommandTests.DoctorCommand_Json_ReportsConfigSourcesWithoutAcquisitionOrConfigurationWrites_state=bound.verified.json (changed test)
→ 1 directly: Aspire.Cli.Tests

🧪 tests/Aspire.Cli.Tests/Snapshots/DoctorCommandTests.DoctorCommand_Json_ReportsConfigSourcesWithoutAcquisitionOrConfigurationWrites_state=noAppHost.verified.json (changed test)
→ 1 directly: Aspire.Cli.Tests

🧪 tests/Aspire.Cli.Tests/Snapshots/DoctorCommandTests.DoctorCommand_Json_ReportsConfigSourcesWithoutAcquisitionOrConfigurationWrites_state=optedOut.verified.json (changed test)
→ 1 directly: Aspire.Cli.Tests

🧪 tests/Aspire.Cli.Tests/Snapshots/DoctorCommandTests.DoctorCommand_Json_ReportsConfigSourcesWithoutAcquisitionOrConfigurationWrites_state=unconfigured.verified.json (changed test)
→ 1 directly: Aspire.Cli.Tests

🧪 tests/Aspire.Cli.Tests/Utils/CliTestHelper.cs (changed test)
→ 1 directly: Aspire.Cli.Tests

🧪 tests/Aspire.Cli.Tests/Utils/ConfigSourceCheckTests.cs (changed test)
→ 1 directly: Aspire.Cli.Tests

Job reasons

Job Triggered by
cli-starter-validation affected project Aspire.Cli
extension-e2e • src/Aspire.Cli/Configuration/ConfigSourceService.cs, src/Aspire.Cli/Program.cs, src/Aspire.Cli/Resources/ConfigSourceStrings.Designer.cs, src/Aspire.Cli/Resources/ConfigSourceStrings.resx, src/Aspire.Cli/Resources/xlf/ConfigSourceStrings.cs.xlf, src/Aspire.Cli/Resources/xlf/ConfigSourceStrings.de.xlf, src/Aspire.Cli/Resources/xlf/ConfigSourceStrings.es.xlf, src/Aspire.Cli/Resources/xlf/ConfigSourceStrings.fr.xlf, src/Aspire.Cli/Resources/xlf/ConfigSourceStrings.it.xlf, src/Aspire.Cli/Resources/xlf/ConfigSourceStrings.ja.xlf, src/Aspire.Cli/Resources/xlf/ConfigSourceStrings.ko.xlf, src/Aspire.Cli/Resources/xlf/ConfigSourceStrings.pl.xlf, src/Aspire.Cli/Resources/xlf/ConfigSourceStrings.pt-BR.xlf, src/Aspire.Cli/Resources/xlf/ConfigSourceStrings.ru.xlf, src/Aspire.Cli/Resources/xlf/ConfigSourceStrings.tr.xlf, src/Aspire.Cli/Resources/xlf/ConfigSourceStrings.zh-Hans.xlf, src/Aspire.Cli/Resources/xlf/ConfigSourceStrings.zh-Hant.xlf, src/Aspire.Cli/Utils/EnvironmentChecker/AspireVersionCheck.cs, src/Aspire.Cli/Utils/EnvironmentChecker/ConfigSourceCheck.cs, src/Aspire.Cli/Utils/EnvironmentChecker/EnvironmentChecker.cs
• affected project Aspire.Cli
polyglot affected project Aspire.Cli
typescript-api-compat affected project Aspire.Cli

Selection computed for commit ef1064c.

@github-actions

Copy link
Copy Markdown
Contributor

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

Copy link
Copy Markdown
Contributor

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

Copy link
Copy Markdown
Contributor

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

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants