[docs] Document proxyless endpoint port pre-allocation (Aspire 13.5)

[aspire-repo-bot]

Documents changes from microsoft/aspire#17924 by @danegsta.

Why this PR is needed

Aspire 13.5 pre-allocates public host ports for dynamic proxyless endpoints before workload resources are created. This makes endpoint properties such as EndpointProperty.Port available during resource configuration, including patterns that pass an endpoint's allocated public port into environment variables.

The existing networking-overview page documents proxyless endpoints but does not cover this pre-allocation behavior or the configurable proxyless endpoint port range.

What changed

Updated src/frontend/src/content/docs/fundamentals/networking-overview.mdx to add a new subsection “Allocate ports for dynamic proxyless endpoints” under the existing ### Proxyless endpoints section. The new subsection:

• Explains that Aspire 13.5 pre-allocates public host ports for dynamic proxyless endpoints before workload creation.
• Describes fixed port behavior versus allocation from the proxyless endpoint port range.
• Documents the default 10000-32767 range and the ASPIRE_PROXYLESS_ENDPOINT_PORT_RANGE override.
• Provides C# and TypeScript AppHost examples showing how to expose an allocated endpoint port as an environment variable.
• Notes that persistent resources reuse allocated proxyless endpoint ports from user secrets.

Files modified

• src/frontend/src/content/docs/fundamentals/networking-overview.mdx — updated (new subsection added)

> Generated by PR Documentation Check for issue #17851 · sonnet46 3.3M · ◷

[aspire-repo-bot]

Frontend HTML artifact ready

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

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

[Copilot]

Pull request overview

Adds documentation to the inner-loop networking overview describing Aspire 13.5’s on-demand resolution behavior for proxyless container endpoints when those endpoints are referenced before container creation (to avoid deadlocks/failures in certain configuration patterns).

Changes:

• Adds a new section explaining why proxyless container endpoint ports may be unavailable prior to container creation.
• Documents Aspire 13.5’s on-demand port allocation behavior for early endpoint resolution.
• Includes a C# AppHost example showing how to inject the endpoint port as an environment variable.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[IEvangelist]

Source-of-truth branch mismatch — review skipped

Cannot verify this PR against microsoft/aspire.

PR base branch (microsoft/aspire.dev)	release/13.5
Matching branch in microsoft/aspire	does not exist
Latest release branch in microsoft/aspire	release/13.4 (4f2189335)
Source PR cited in body	microsoft/aspire# — merged to main, milestone 13.5

My review protocol requires using the matching microsoft/aspire release branch as the single source of truth for claim verification. Because no release/13.5 branch exists on microsoft/aspire yet (13.5 has not been cut), I cannot verify the API/CLI/config claims in this PR against an authoritative source code snapshot for that release.

Possible resolutions:

1. Re-target this PR to release/13.4 in aspire.dev if the documented behavior is already present in 13.4.
2. Wait until release/13.5 is cut in microsoft/aspire, then re-run review against that branch.

Skipping Phase B (doc-tester) as well — running it without the Phase A claim verification would produce an incomplete review per protocol.

[danegsta]

This will soon become invalid due to microsoft/aspire#17924 which will switch 13.5 to pre-allocation of undefined proxyless ports.

[danegsta]

This will need changes after another PR merges.

[IEvangelist]

Source-of-truth branch mismatch — review feedback not applied

I checked the matching source-of-truth branch required by the docs-feedback protocol and cannot evaluate this PR yet.

PR base branch (microsoft/aspire.dev)	release/13.5
Required source branch (microsoft/aspire)	release/13.5
Result after git fetch origin --prune	origin/release/13.5 does not exist
Latest available release branch in microsoft/aspire	origin/release/13.4 (4f2189335)

Because there is no matching microsoft/aspire branch, I can't verify the review feedback or the documented behavior against an authoritative source snapshot. Per protocol, I'm leaving the PR unchanged and not resolving any threads. Once release/13.5 exists in microsoft/aspire (or the PR is retargeted to a branch that exists there), the feedback can be evaluated safely.

[IEvangelist]

Source-of-truth branch mismatch - review feedback not applied

I checked the matching source-of-truth branch required by the docs-feedback protocol and cannot evaluate this PR yet.

PR base branch (microsoft/aspire.dev)
elease/13.5
Required source branch (microsoft/aspire)
elease/13.5
Result after git fetch origin --prune	origin/release/13.5 does not exist
Latest available 13.x release branch in microsoft/aspire	origin/release/13.4 ($latest13_4)

Because there is no matching microsoft/aspire branch, I can't verify the review feedback or the documented behavior against an authoritative source snapshot. Per protocol, I'm leaving the PR unchanged and not resolving any threads. Once
elease/13.5 exists in microsoft/aspire or the PR is retargeted to a branch that exists there, the feedback can be evaluated safely.

[IEvangelist]

Source-of-truth branch mismatch - review feedback not applied

I checked the matching source-of-truth branch required by the docs-feedback protocol and cannot evaluate this PR yet.

PR base branch (microsoft/aspire.dev)	release/13.5
Required source branch (microsoft/aspire)	release/13.5
Result after git fetch origin --prune	origin/release/13.5 does not exist
Latest available release branch in microsoft/aspire	origin/release/13.4 (4f2189335)

Because there is no matching microsoft/aspire branch, I cannot verify the review feedback or the documented behavior against an authoritative source snapshot. Per protocol, I am leaving the PR unchanged and not resolving any threads. Once release/13.5 exists in microsoft/aspire (or the PR is retargeted to a branch that exists there), the feedback can be evaluated safely.

[danegsta]

@copilot we need to re-evaluate these doc changes now that microsoft/aspire#17924 is merged.

[Copilot]

@copilot we need to re-evaluate these doc changes now that microsoft/aspire#17924 is merged.

Re-evaluated after microsoft/aspire#17924 and updated the section to describe pre-allocation from the proxyless endpoint port range, fixed ports, persistent resource reuse, and added TypeScript parity. Addressed in aaab7dd.

[IEvangelist]

CI has been retriggered multiple times and is still failing on validation/build checks. This appears to be caused by the current PR changes rather than a transient workflow issue and likely needs a docs/code fix in this PR.

[IEvangelist]

This PR has had CI retriggered multiple times and is still failing on PR-specific checks. It likely needs a change in this PR to pass.

[IEvangelist]

CI has been retriggered several times and is still failing for this PR.
This appears to be related to the changes in this PR (not a transient rerun issue), so it likely needs an update in this PR to resolve.

[IEvangelist]

We've retriggered CI many times on this PR and it's still failing. At this point, the failure likely comes from changes in this PR rather than transient CI flakiness, so this probably needs a content/code fix in the PR itself.

[IEvangelist]

CI has failed repeatedly on this docs-from-code PR after multiple reruns, and the failures appear to be related to the changes in this PR. Please review and adjust the PR content so the checks can pass.

[IEvangelist]

CI has been retriggered multiple times on this PR and is still failing. The failures appear tied to the current PR changes rather than a transient runner issue, so this likely needs an update in the PR content before CI will pass.