You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Persist stable AppHost ports and add worktree isolation - #21013
Generated public ports are currently stable only in a few special cases, which means endpoint addresses can change across AppHost restarts and linked Git worktrees require explicit isolation. This change introduces a consistent persistent port model for both C# and polyglot AppHosts.
Generated public ports are stored in an AppHost-local key/value state file under .aspire/state. The state store uses cross-process locking, atomic replacement, per-value schema versioning, and a product-owned .gitignore. Port allocation continues to treat executable target ports as transient, while preserving generated public ports that form the user-observable endpoint identity.
The implementation also:
migrates existing Resources:<resource>:<endpoint>:port user-secret values when first encountered, without writing new allocations back to user secrets
adds features.gitWorktreeIsolationEnabled to automatically use isolated mode for AppHosts in linked Git worktrees, while preserving explicit --isolated true|false precedence
adds portAllocation.persistInIsolatedMode so isolated runs can opt into stable persisted ports
projects the AppHost-relative port policy consistently into managed C# and polyglot AppHosts
By default, isolated mode continues to skip persisted allocations. Setting persistInIsolatedMode to true gives each AppHost/worktree identity stable generated ports across restarts.
Persist generated public ports in AppHost-local state and add feature-controlled worktree isolation for C# and polyglot AppHosts.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
The same C# AppHost uses different state files depending on its launcher. The CLI sets DCP_WORKLOAD_ID to apphost-<path hash> (DotNetAppHostProject.cs:1588), while a direct launch without that variable falls back to AppHost:FilePath or AppHost:Path. Hashing these different strings selects separate stores, so switching launchers loses the saved public ports. Use a canonical AppHost identity shared by both launch paths, and test that both configurations reuse the same allocations.
Preserve valid legacy ports outside the allocation range
TryGetPortIndex rejects legacy ports outside the configured allocation range, even though the previous migration path accepted any valid port. For example, a saved port of 8080 is discarded with the default 10000–32767 range. Upgrading therefore changes the endpoint address and can recreate a persistent workload despite there being no conflict. Preserve valid legacy ports outside the scan range, tracking their reservations separately so duplicates and fixed-port conflicts are still rejected; keep new allocations within the configured range. Add an out-of-range migration regression test.
The same C# AppHost selects different state files depending on how it is launched. The CLI supplies DCP_WORKLOAD_ID=apphost-<path hash> (DotNetAppHostProject.cs:1588), while execution without that CLI environment falls back to AppHost:FilePath or AppHost:Path. Hashing these different identities prevents reuse of the other launcher's saved ports and can recreate persistent proxyless workloads. Use a consistent normalized AppHost-path identity across launchers, and add a regression that verifies reuse with and without the CLI-provided workload ID.
Rejects valid legacy ports outside the current allocation range
This rejects valid legacy ports outside the current generation range, even when allowInUse is true. For example, a saved port of 55000 was previously reusable because the old path checked only PortRange.IsValidPort, but it cannot migrate with the default 10000–32767 range. The endpoint address changes and a persistent workload may be recreated despite no conflict. Reserve valid legacy ports independently of the range for new allocations, while preserving availability checks, fixed-port exclusions, and duplicate detection. Add an out-of-range migration regression test.
David Negstad (danegsta)
changed the title
Persist stable AppHost port allocations
Persist stable AppHost ports and add worktree isolation
Oct 15, 2026
If .aspire/state and its .gitignore already exist but the lock file cannot be opened for writing, FileLock.Acquire retries for five seconds. A continuously held lock has the same effect. The initial read times out, but the store remains available, so every generated endpoint's SetPort waits again under the allocator lock. With 20 endpoints, this can add roughly 105 seconds to startup. Bound persistence retries across the launch, rather than per endpoint, or stop disk access after a failure. Preserve in-memory port reservations when disabling disk persistence.
The reason will be displayed to describe this comment to others. Learn more.
🔵 Needs a closer look
The new C# and TypeScript linked-worktree restart E2E scenarios were not run locally, leaving persisted-port reuse and worktree isolation across restarts unverified against the real CLI/server/DCP stack.
If there are concerns about merging this late in the 17.0 cycle, we could consider holding it for 17.1. The automatic worktree isolation is opt-in, but persistent generated public ports change the default behavior for normal AppHost runs, so holding would give us more time to exercise restart scenarios.
If there are concerns about merging this late in the 17.0 cycle, we could consider holding it for 17.1. The automatic worktree isolation is opt-in, but persistent generated public ports change the default behavior for normal AppHost runs, so holding would give us more time to exercise restart scenarios.
I don't think this is urgent for 17.0. I'm comfortable holding off merge until main becomes 17.1.
The reason will be displayed to describe this comment to others. Learn more.
🔵 Needs a closer look
Cross-process persistence and C#/TypeScript linked-worktree restart behavior still need runtime validation because the new worktree E2E cases remain unrun and cannot be executed in this environment.
The reason will be displayed to describe this comment to others. Learn more.
🔵 Needs a closer look
Human assessment is needed because the saved-port probe may treat TCP TIME_WAIT as a conflict, unexpectedly changing public URLs after restart without a competing listener.
## Description
Generated public ports are currently stable only in a few special cases,
which means endpoint addresses can change across AppHost restarts and
linked Git worktrees require explicit isolation. This change introduces
a consistent persistent port model for both C# and polyglot AppHosts.
Generated public ports are stored in an AppHost-local key/value state
file under `.aspire/state`. The state store uses cross-process locking,
atomic replacement, per-value schema versioning, and a product-owned
`.gitignore`. Port allocation continues to treat executable target ports
as transient, while preserving generated public ports that form the
user-observable endpoint identity.
The implementation also:
- migrates existing `Resources:<resource>:<endpoint>:port` user-secret
values when first encountered, without writing new allocations back to
user secrets
- adds `features.gitWorktreeIsolationEnabled` to automatically use
isolated mode for AppHosts in linked Git worktrees, while preserving
explicit `--isolated true|false` precedence
- adds `portAllocation.persistInIsolatedMode` so isolated runs can opt
into stable persisted ports
- projects the AppHost-relative port policy consistently into managed C#
and polyglot AppHosts
### User-facing usage
```json
{
"features": {
"gitWorktreeIsolationEnabled": true
},
"portAllocation": {
"persistInIsolatedMode": true
}
}
```
By default, isolated mode continues to skip persisted allocations.
Setting `persistInIsolatedMode` to `true` gives each AppHost/worktree
identity stable generated ports across restarts.
No additional dependencies are required.
### Validation
- `dotnet test --project
tests/Aspire.Hosting.Tests/Aspire.Hosting.Tests.csproj --no-build
--no-launch-profile -- --filter-class "*.DcpExecutorTests"
--filter-not-trait "quarantined=true" --filter-not-trait
"outerloop=true"` - passed (314 succeeded, 1 platform-specific skip)
- `dotnet test --project tests/Aspire.Cli.Tests/Aspire.Cli.Tests.csproj
--no-build --no-launch-profile -- --filter-class
"*.AspireConfigFileTests" --filter-not-trait "quarantined=true"
--filter-not-trait "outerloop=true"` - passed (41 succeeded, 1
platform-specific skip)
- `./build.sh --build /p:SkipNativeBuild=true` - passed
- CLI end-to-end coverage was added for C# and TypeScript
linked-worktree restart stability; it was not run locally
Fixes#20653
## Checklist
- Is this feature complete?
- [x] Yes. Ready to ship.
- [ ] 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 App <223556219+Copilot@users.noreply.github.com>
(cherry picked from commit 168a8b4)
## Description
Generated public ports are currently stable only in a few special cases,
which means endpoint addresses can change across AppHost restarts and
linked Git worktrees require explicit isolation. This change introduces
a consistent persistent port model for both C# and polyglot AppHosts.
Generated public ports are stored in an AppHost-local key/value state
file under `.aspire/state`. The state store uses cross-process locking,
atomic replacement, per-value schema versioning, and a product-owned
`.gitignore`. Port allocation continues to treat executable target ports
as transient, while preserving generated public ports that form the
user-observable endpoint identity.
The implementation also:
- migrates existing `Resources:<resource>:<endpoint>:port` user-secret
values when first encountered, without writing new allocations back to
user secrets
- adds `features.gitWorktreeIsolationEnabled` to automatically use
isolated mode for AppHosts in linked Git worktrees, while preserving
explicit `--isolated true|false` precedence
- adds `portAllocation.persistInIsolatedMode` so isolated runs can opt
into stable persisted ports
- projects the AppHost-relative port policy consistently into managed C#
and polyglot AppHosts
### User-facing usage
```json
{
"features": {
"gitWorktreeIsolationEnabled": true
},
"portAllocation": {
"persistInIsolatedMode": true
}
}
```
By default, isolated mode continues to skip persisted allocations.
Setting `persistInIsolatedMode` to `true` gives each AppHost/worktree
identity stable generated ports across restarts.
No additional dependencies are required.
### Validation
- `dotnet test --project
tests/Aspire.Hosting.Tests/Aspire.Hosting.Tests.csproj --no-build
--no-launch-profile -- --filter-class "*.DcpExecutorTests"
--filter-not-trait "quarantined=true" --filter-not-trait
"outerloop=true"` - passed (314 succeeded, 1 platform-specific skip)
- `dotnet test --project tests/Aspire.Cli.Tests/Aspire.Cli.Tests.csproj
--no-build --no-launch-profile -- --filter-class
"*.AspireConfigFileTests" --filter-not-trait "quarantined=true"
--filter-not-trait "outerloop=true"` - passed (41 succeeded, 1
platform-specific skip)
- `./build.sh --build /p:SkipNativeBuild=true` - passed
- CLI end-to-end coverage was added for C# and TypeScript
linked-worktree restart stability; it was not run locally
Fixes#20653
## Checklist
- Is this feature complete?
- [x] Yes. Ready to ship.
- [ ] 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 App <223556219+Copilot@users.noreply.github.com>
(cherry picked from commit 168a8b4)
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
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.
Description
Generated public ports are currently stable only in a few special cases, which means endpoint addresses can change across AppHost restarts and linked Git worktrees require explicit isolation. This change introduces a consistent persistent port model for both C# and polyglot AppHosts.
Generated public ports are stored in an AppHost-local key/value state file under
.aspire/state. The state store uses cross-process locking, atomic replacement, per-value schema versioning, and a product-owned.gitignore. Port allocation continues to treat executable target ports as transient, while preserving generated public ports that form the user-observable endpoint identity.The implementation also:
Resources:<resource>:<endpoint>:portuser-secret values when first encountered, without writing new allocations back to user secretsfeatures.gitWorktreeIsolationEnabledto automatically use isolated mode for AppHosts in linked Git worktrees, while preserving explicit--isolated true|falseprecedenceportAllocation.persistInIsolatedModeso isolated runs can opt into stable persisted portsUser-facing usage
{ "features": { "gitWorktreeIsolationEnabled": true }, "portAllocation": { "persistInIsolatedMode": true } }By default, isolated mode continues to skip persisted allocations. Setting
persistInIsolatedModetotruegives each AppHost/worktree identity stable generated ports across restarts.No additional dependencies are required.
Validation
dotnet test --project tests/Aspire.Hosting.Tests/Aspire.Hosting.Tests.csproj --no-build --no-launch-profile -- --filter-class "*.DcpExecutorTests" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true"- passed (314 succeeded, 1 platform-specific skip)dotnet test --project tests/Aspire.Cli.Tests/Aspire.Cli.Tests.csproj --no-build --no-launch-profile -- --filter-class "*.AspireConfigFileTests" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true"- passed (41 succeeded, 1 platform-specific skip)./build.sh --build /p:SkipNativeBuild=true- passedFixes #20653
Checklist
<remarks />and<code />elements on your triple slash comments?