Repository navigation
[docs] Document worktree isolation and persistent port settings - #2094
Draft
aspire-repo-bot[bot] wants to merge 1 commit into
Draft
aspire-repo-bot[bot] wants to merge 1 commit into
aspire-repo-bot[bot] wants to merge 1 commit into
Conversation
4 of 14 tasks
Contributor
Author
Frontend HTML artifact readyThe latest frontend build uploaded the This comment updates automatically when a new frontend build artifact is uploaded. |
David Pine (IEvangelist)
requested review from
David Negstad (danegsta)
and removed request for
Mitch Denny (mitchdenny)
November 12, 2026 23:54
David Pine (IEvangelist)
marked this pull request as ready for review
November 13, 2026 14:54
David Pine (IEvangelist)
requested review from
David Pine (IEvangelist) and
Mitch Denny (mitchdenny)
as code owners
November 13, 2026 14:54
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The new settings and related --isolated descriptions lack minimum-version qualifications, even though the linked implementation targets 17.1 and the settings are unavailable in 17.0.
1 open issue
What changed in this PR
This PR updates Aspire’s CLI reference to document worktree isolation and generated-port persistence from microsoft/aspire#21013.
Changes:
- Adds settings for automatic worktree isolation and persisted ports in isolated mode.
- Expands the
aspire runandaspire startreferences with persistence behavior and explicit isolation overrides.
| File | Description |
|---|---|
src/frontend/src/content/docs/reference/cli/includes/config-settings-table.md |
Documents both settings, defaults, and persisted-state location. |
src/frontend/src/content/docs/reference/cli/commands/aspire-start.mdx |
Clarifies port persistence and --isolated false behavior. |
src/frontend/src/content/docs/reference/cli/commands/aspire-run.mdx |
Adds matching isolation and persistence guidance. |
Review effort: Balanced
| | `features.experimentalPolyglot:java` | `false` | Enable or disable experimental Java AppHost support. | | ||
| | `features.experimentalPolyglot:python` | `false` | Enable or disable experimental Python AppHost support. | | ||
| | `features.experimentalPolyglot:rust` | `false` | Enable or disable experimental Rust AppHost support. | | ||
| | `features.gitWorktreeIsolationEnabled` | `false` | Enable or disable automatic isolated mode for AppHosts in linked Git worktrees. An explicit `--isolated true` or `--isolated false` always takes precedence. | |
David Negstad (danegsta)
marked this pull request as draft
November 16, 2026 21:16
Member
|
This particular change isn't shipping in 17.0. |
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>
Maddy Montaquila (maddymontaquila)
changed the base branch from
release/17.0
to
main
November 17, 2026 19:15
Maddy Montaquila (maddymontaquila)
force-pushed
the
docs/pr-21013-42717977901-1-61b4adada2db2189
branch
from
November 17, 2026 19:28
b70dfed to
01a5f2d
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

Documents changes from microsoft/aspire#21013
Author:
@danegstaTargeting
release/17.0— the latest release branch onmicrosoft/aspire.dev— becauserelease/17.1(from the source PR milestone17.1) does not exist there.Why
The source PR adds persisted generated AppHost ports,
features.gitWorktreeIsolationEnabled, andportAllocation.persistInIsolatedMode. Triggered signals:cli_command_file_changed(RunCommand.cs),pr_body_has_cli_flag_mention(--isolated true|false),pr_body_has_user_facing_section(JSON config example).Changes (existing pages updated)
reference/cli/includes/config-settings-table.md: added the two new settings.reference/cli/commands/aspire-run.mdx:--isolatednow explains persisted-port and worktree behavior.reference/cli/commands/aspire-start.mdx: same.