Repository navigation
[docs] Document dotnet run publish-mode fail-fast behavior - #1902
aspire-repo-bot[bot] wants to merge 1 commit into
Conversation
…ublish Documents microsoft/aspire#21065: dotnet run --operation publish now fails fast with a clear error instead of hanging at dashboard startup when the CLI run hook is enabled. Adds a troubleshooting entry and a cross-reference note in the Aspire SDK docs. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Frontend HTML artifact readyThe latest frontend build uploaded the This comment updates automatically when a new frontend build artifact is uploaded. |
docs-pr-reviewer report — [partial — phase A: key claims evaluated; phase B: not run (docs site was not served in this automated run)]Recommendation: approve Source used: Phase A — claims
Phase B — doc-testerNot run; rendering of the changed pages is not browser-checked. 🤖 Posted by aspire.dev - squad (AI Agent) |
There was a problem hiding this comment.
🔵 Needs a closer look
Required new-user browser/CLI validation could not run in the dependency-free review environment, leaving the rendered cross-reference and replacement publish command unconfirmed.
No open issues 🎉
What changed in this PR
Documents the publish-mode fail-fast behavior introduced by microsoft/aspire#21065 and directs developers using the CLI run hook to aspire publish.
Changes:
- Adds troubleshooting guidance for the
Starting dashboard...hang, including the newer error message and exit code2. - Adds a caution and troubleshooting link to the SDK’s
dotnet runguidance.
| File | Description |
|---|---|
src/frontend/src/content/docs/get-started/troubleshooting.mdx |
Explains the hang, replacement command, and fail-fast behavior. |
src/frontend/src/content/docs/get-started/aspire-sdk.mdx |
Adds a publish-mode caution and links to troubleshooting. |
Review effort: Balanced
## Summary Consolidates the open `docs-from-code` PRs that cover features from @IEvangelist's product work or that request their review, all targeting `release/17.0`, into this single PR. Each PR was checked against its merged microsoft/aspire source PR and against product `release/17.0`, to confirm the change shipped in 17.0 and is user-facing rather than an implementation detail. Accepted text was corrected where the bot's wording was inaccurate. | PR(s) | Verdict | Notes | | --- | --- | --- | | #2103, #2098, #1967, #2073, #2070 | Accepted with fixes | Go AppHost conventions, `aspire init`, and VS Code extension. Unrelated e2e test edits from #2073 were dropped. | | #1972 | Partially accepted | Only the verified behavior was kept. | | #2069, #2064, #1829 | Accepted with fixes | Dashboard explore page and `aspire describe --format Mermaid` | | #2044 | Partially accepted | The Cards/Home/Graph layout selector text is outdated, so it was dropped. | | #1959, #1904, #1835, #1801 | Accepted with fixes | `WithTerminal` options, the dashboard terminal UX, and TypeScript `configure` | | #1902 | Accepted with fixes | `dotnet run --operation publish` guidance | | #2081 | Accepted with fixes | WSLc limited publish support. The minimum version is corrected to 3.0.4.0. | | #2014, #1862, #1809, #1936, #2140, #1997, #2051, #2068, #2022, #1963 | Accepted with fixes | DCP timeouts, the container tunnel base image, browser origins, the PVC `WithConfiguration` API, the interaction service caution, secrets, `aspire update`, and agent init telemetry | | #2092 | Rejected | Documents implementation details. | | #2078 | Rejected | Already documented correctly; the proposed text was wrong. | | #2110, #2104, #2085, #2094 | Rejected | The product change isn't in `release/17.0`; it's 17.1-only. Redo these against the next release branch. | | #2133 | Rejected for now | Its backport, microsoft/aspire#22219, is still open, so redo this once it merges. | Additional consistency fixes: - **WSLc:** the minimum version is now 3.0.4.0, the source's `MinimumWslcVersion`, across prerequisites, `aspire doctor`, configuration, and what's new. The pages now describe limited publish support and state that Docker Compose isn't supported. - **`WithTerminal`:** `WithTerminal` and `TerminalOptions` are no longer `[Experimental]` in 17.0. I removed the stale `ASPIRETERMINAL001` pragmas and cautions and rewrote the diagnostic page to cover the terminal APIs that are still experimental. Closes #2140 Closes #2133 Closes #2110 Closes #2104 Closes #2103 Closes #2098 Closes #2094 Closes #2092 Closes #2085 Closes #2081 Closes #2078 Closes #2073 Closes #2070 Closes #2069 Closes #2068 Closes #2064 Closes #2051 Closes #2044 Closes #2022 Closes #2014 Closes #1997 Closes #1972 Closes #1967 Closes #1963 Closes #1959 Closes #1936 Closes #1904 Closes #1902 Closes #1862 Closes #1835 Closes #1829 Closes #1809 Closes #1801 ## Third-party links and affiliations None. The only added external link is to mermaid.js.org, which the page already links elsewhere. ## Validation - I compared each claim with the merged microsoft/aspire source and checked that it's included in product `release/17.0`, using `gh api compare` and searches for backport PRs. - I checked the TypeScript sample against the generated `aspire.d.ts`. `EndpointReferenceExpression` is an `IValueProvider`. - I reviewed the full diff by hand for MDX and table formatting, imports, and anchors. The new `seoTitle` is 58 characters. - I didn't run any local unit, e2e, or build commands because frontend dependencies aren't installed locally. CI covers the build, unit, and e2e checks, including the updated `custom-components.spec.ts` assertion. --------- Co-authored-by: David Pine <7679720+IEvangelist@users.noreply.github.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
|
Superseded by #2189 (merged to release/17.0) |
Documents changes from microsoft/aspire#21065
@DamianEdwardsTarget branch
Targeting
release/17.0based on the source PR milestone17.0(exact match onmicrosoft/aspire.dev).Why this change is needed
microsoft/aspire#21065 fixes
dotnet run --operation publish(and the equivalent--publisher manifest/AppHost:Operationconfiguration overrides) hanging atStarting dashboard...when the Aspire CLI run hook is enabled. The AppHost now detects it's running in publish mode before waiting on dashboard readiness, and fails immediately (exit code 2) with guidance to useaspire publishinstead.This is a user-facing behavior change: a scenario that previously hung indefinitely now fails fast with explanatory text, so it needs a documented troubleshooting entry and a pointer from the existing
dotnet runguidance.Triggered signals (from
.pr-docs-check/signals.json):pr_body_has_cli_flag_mention— PR body referencesdotnet run --operation publish/--operation publish.pr_body_has_user_facing_section— PR body includes a "User-facing usage" section showing the exact new error output and exit code.What was documented
src/frontend/src/content/docs/get-started/troubleshooting.mdx: Added a new section,`dotnet run --operation publish` hangs at "Starting dashboard...", describing the symptom, root cause, and the fix (useaspire publish), including the exact new error message and exit code from the source PR.src/frontend/src/content/docs/get-started/aspire-sdk.mdx: Added a:::cautionnote at the end of the "Running with dotnet run" section (next to the existingdnxnote) cross-referencing the new troubleshooting entry, since that's the section most likely to be read by developers usingdotnet runto launch an AppHost via the CLI run hook.Both pages were updated in place; no new pages were created.
Validation
Documentation-only change (no code, tests, or build affected). Content follows the doc-writer skill conventions (Starlight
:::cautionadmonition, relative cross-reference links, code block titles).