Skip to content

[docs] Document dotnet run publish-mode fail-fast behavior - #1902

Closed
aspire-repo-bot[bot] wants to merge 1 commit into
release/17.0from
docs/pr-21065-38971986203-1-a85863afeaa68057
Closed

aspire-repo-bot[bot] wants to merge 1 commit into
release/17.0from
docs/pr-21065-38971986203-1-a85863afeaa68057

Conversation

@aspire-repo-bot

Copy link
Copy Markdown
Contributor

Documents changes from microsoft/aspire#21065

@DamianEdwards

Target branch

Targeting release/17.0 based on the source PR milestone 17.0 (exact match on microsoft/aspire.dev).

Why this change is needed

microsoft/aspire#21065 fixes dotnet run --operation publish (and the equivalent --publisher manifest / AppHost:Operation configuration overrides) hanging at Starting 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 use aspire publish instead.

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 run guidance.

Triggered signals (from .pr-docs-check/signals.json):

  • pr_body_has_cli_flag_mention — PR body references dotnet 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 (use aspire 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 :::caution note at the end of the "Running with dotnet run" section (next to the existing dnx note) cross-referencing the new troubleshooting entry, since that's the section most likely to be read by developers using dotnet run to 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 :::caution admonition, relative cross-reference links, code block titles).

Generated by PR Documentation Check for #21065 · copilot · auto · 83.3 AIC · ⌖ 20.1 AIC · ⊞ 20.4K · ◷

…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>
@aspire-repo-bot aspire-repo-bot Bot added the docs-from-code Copilot initiated issue from dotnet/aspire repo label Oct 16, 2026
@aspire-repo-bot

Copy link
Copy Markdown
Contributor Author

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #1902. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

VS Code: Open PR #1902 artifacts

This comment updates automatically when a new frontend build artifact is uploaded.

Copy link
Copy Markdown
Member

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: microsoft/aspire main via merged source PR microsoft/aspire#21065
PR status: draft, mergeable, opened 2026-10-16 (not stale)

Phase A — claims

  • ✅ verified: AppHostRpcTarget now rejects the run-command dashboard readiness wait in publish mode, with the message 'The AppHost is in publish mode and cannot be started with aspire run. Use aspire publish instead.'
  • ⚠️ nuance: the documented exit code 2 was not traced in this run.

Phase B — doc-tester

Not run; rendering of the changed pages is not browser-checked.

🤖 Posted by aspire.dev - squad (AI Agent)

@IEvangelist
David Pine (IEvangelist) marked this pull request as ready for review November 13, 2026 14:57
Copilot AI balanced review requested due to automatic review settings November 13, 2026 14:57

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.

🔵 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 code 2.
  • Adds a caution and troubleshooting link to the SDK’s dotnet run guidance.
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

David Pine (IEvangelist) added a commit that referenced this pull request Nov 17, 2026
## 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>
@alistairmatthews

Copy link
Copy Markdown
Collaborator

Superseded by #2189 (merged to release/17.0)

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

Labels

docs-from-code Copilot initiated issue from dotnet/aspire repo

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants