Skip to content

[docs] Document IInteractionService unavailability during before-start - #2022

Closed
aspire-repo-bot[bot] wants to merge 1 commit into
release/17.0from
docs/pr-21553-41333939061-1-4beb729532f0e890
Closed

aspire-repo-bot[bot] wants to merge 1 commit into
release/17.0from
docs/pr-21553-41333939061-1-4beb729532f0e890

Conversation

@aspire-repo-bot

Copy link
Copy Markdown
Contributor

Documents changes from microsoft/aspire#21553

Author: @davidfowl (source PR author per workflow actor; see source PR)

Target branch: Targeting release/17.0 based on the source PR milestone 17.0 (pr_milestone, exact_match).

Why: The source PR makes IInteractionService.IsAvailable return false during before-start (BeforeStartEvent subscribers, lifecycle hook BeforeStartAsync, before-start pipeline step, and between Build() and Run()); unguarded prompts now throw InvalidOperationException instead of deadlocking. No automated signals fired, but this is a user-visible behavior change to a documented feature.

Changes (updated page):

  • src/frontend/src/content/docs/extensibility/interaction-service.mdx: added a caution Aside explaining the restriction and the alternative.

Generated by PR Documentation Check for #21553 · copilot · auto · 25.9 AIC · ⌖ 1.13 AIC · ⊞ 7.1K · ◷

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

@aspire-repo-bot aspire-repo-bot Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Automated wording suggestions from the forbidden-words check. Apply the suggestions to resolve them.

</Aside>

<Aside type="caution">
The interaction service isn't available while the app host runs before-start logic: `BeforeStartEvent` subscribers, `IDistributedApplicationLifecycleHook.BeforeStartAsync` implementations, and the `before-start` pipeline step. Nothing can respond to a prompt at that point because the dashboard and CLI backchannel start later. `IInteractionService.IsAvailable` returns `false` during this phase (including between `Build()` and `Run()`), and it returns `true` again once before-start completes. Calling a prompt method without checking `IsAvailable` throws an `InvalidOperationException` instead of hanging app host startup. To prompt the user, move the logic to a later event, such as a resource event or a resource command.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Use "AppHost" instead of "app host".

Suggested change
The interaction service isn't available while the app host runs before-start logic: `BeforeStartEvent` subscribers, `IDistributedApplicationLifecycleHook.BeforeStartAsync` implementations, and the `before-start` pipeline step. Nothing can respond to a prompt at that point because the dashboard and CLI backchannel start later. `IInteractionService.IsAvailable` returns `false` during this phase (including between `Build()` and `Run()`), and it returns `true` again once before-start completes. Calling a prompt method without checking `IsAvailable` throws an `InvalidOperationException` instead of hanging app host startup. To prompt the user, move the logic to a later event, such as a resource event or a resource command.
The interaction service isn't available while the AppHost runs before-start logic: `BeforeStartEvent` subscribers, `IDistributedApplicationLifecycleHook.BeforeStartAsync` implementations, and the `before-start` pipeline step. Nothing can respond to a prompt at that point because the dashboard and CLI backchannel start later. `IInteractionService.IsAvailable` returns `false` during this phase (including between `Build()` and `Run()`), and it returns `true` again once before-start completes. Calling a prompt method without checking `IsAvailable` throws an `InvalidOperationException` instead of hanging AppHost startup. To prompt the user, move the logic to a later event, such as a resource event or a resource command.

@aspire-repo-bot

Copy link
Copy Markdown
Contributor Author

Frontend HTML artifact ready

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

VS Code: Open PR #2022 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#21553 (merged 2026-11-01)
PR status: draft, mergeable, bot-authored, opened 2026-11-01 — not stale.

Phase A — claims

  • ✅ source PR merged ('Make IInteractionService unavailable during BeforeStart to prevent deadlock'); the caution lists BeforeStartEvent, BeforeStartAsync hooks and the before-start step.
  • ⚠️ nuance: confirm the exact failure behavior (exception vs IsAvailable=false) stated in the doc.

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:55
Copilot AI balanced review requested due to automatic review settings November 13, 2026 14:55

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

The documentation incorrectly implies that completing before-start guarantees interaction availability, rather than clarifying that callers must still check IsAvailable, particularly for CLI-triggered resource commands.

1 open issue
What changed in this PR

This documentation-only PR updates the interaction service guide for the before-start behavior change in Aspire 17.0.

Changes:

  • Adds a caution identifying startup phases where IInteractionService is unavailable.
  • Explains that prompts during before-start throw rather than hang startup, and recommends moving prompts to later events or resource commands.
File Description
src/​frontend/​src/​content/​docs/​extensibility/​interaction-service.mdx Documents before-start interaction restrictions and alternatives.

Review effort: Balanced

</Aside>

<Aside type="caution">
The interaction service isn't available while the app host runs before-start logic: `BeforeStartEvent` subscribers, `IDistributedApplicationLifecycleHook.BeforeStartAsync` implementations, and the `before-start` pipeline step. Nothing can respond to a prompt at that point because the dashboard and CLI backchannel start later. `IInteractionService.IsAvailable` returns `false` during this phase (including between `Build()` and `Run()`), and it returns `true` again once before-start completes. Calling a prompt method without checking `IsAvailable` throws an `InvalidOperationException` instead of hanging app host startup. To prompt the user, move the logic to a later event, such as a resource event or a resource command.
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