[docs] Document proxyless container endpoint on-demand allocation (Aspire 13.5)

[aspire-repo-bot]

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

Targeting release/13.4 — the latest release branch on microsoft/aspire.dev — because release/13.5 (from the source PR milestone 13.5) does not exist there.

Why this PR is needed

Aspire 13.5 adds on-demand port allocation for dynamic proxyless container endpoints (microsoft/aspire#17851). Before this change, referencing a proxyless container endpoint before container creation — for example, to inject the container’s own port as an environment variable — could deadlock or fail because the host port is normally assigned by DCP only after the container is created.

The existing networking-overview page documents proxyless endpoints but does not cover this new resolution behavior.

What changed

Updated src/frontend/src/content/docs/fundamentals/networking-overview.mdx to add a new subsection “Resolving proxyless container endpoints before container creation” under the existing ### Proxyless endpoints section. The new subsection:

• Explains the problem (deferred host port assignment causing deadlocks).
• Describes the on-demand allocation behavior added in Aspire 13.5.
• Provides a C# code example matching the one in the source PR.
• Notes that if the endpoint is not resolved before container creation, DCP still assigns the host port dynamically.

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.