Repository navigation
Report configuration source availability in aspire doctor - #22197
James Newton-King (JamesNK) wants to merge 3 commits into
Conversation
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>
|
🚀 Dogfood this PR with:
curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 22197Or
iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 22197" |
This comment has been minimized.
This comment has been minimized.
There was a problem hiding this comment.
🟡 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
|
|
||
| // 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>
There was a problem hiding this comment.
🟢 Approval recommended
No active review issues require changes to the configuration-source diagnostics.
1 resolved since last review
1 file not reviewed
src/Aspire.Cli/Resources/ConfigSourceStrings.Designer.cs: Generated file
Review effort: Balanced
Tests selector3 / 101 PR test projects · 4 PR jobs, from 33 changed files. Selected PR test projects (3 / 101)
Selected PR jobs (4)
How these were chosen — grouped by what changed📦 affected project 🔧 🔧 🧪 🧪 🧪 🧪 🧪 🧪 🧪 🧪 🧪 🧪 🧪 🧪 🧪 Job reasons
Selection computed for commit |
|
Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt. |
|
Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt. |
|
Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt. |


Description
Existing AppHosts do not indicate when a machine configuration source is available but has not been adopted.
aspire doctornow 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 suggestingaspire 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
With a synthetic machine source and an AppHost that has no saved choice, the table output includes:
Screenshots / Recordings
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:
Passed:
dotnet build src\Aspire.Cli\Aspire.Cli.csproj --no-restore /t:UpdateXlfregenerated localization files without warnings or errors.Passed: source-built
aspire.exe doctor --format json --non-interactivewith a synthetic source and an unconfigured AppHost reported both the machine candidate and the AppHost warning.Passed: source-built
aspire.exe doctor --non-interactive --nologowith the same scenario produced the table output shown above.Passed:
git diff --check origin/main...HEAD.Fixes # (issue)
Checklist
<remarks />and<code />elements on your triple slash comments?