Pull request overview

Updates Aspire 13.4 documentation to reflect the corrected default endpoint proxy behavior for persistent containers (proxied by default) vs persistent executables/projects (proxyless by default), and documents immediate host port allocation for proxyless container endpoints when only targetPort is provided.

Changes:

• Clarifies proxyless-by-default behavior applies to persistent executables/projects, not containers.
• Adds explanation that persistent containers remain proxied by default to preserve pre-start endpoint allocation behavior.
• Documents immediate host port resolution for proxyless container endpoints when only targetPort is specified.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

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

Documentation review (Phase A claim verification + Phase B doc-tester)

Source of truth (Phase A): microsoft/aspire branch release/13.4 @ commit 4f218933552e18ff2874d1b6d5dc3fe671e3b6d9 (Fix persistent container endpoint allocation (#17960)).

Phase A claim summary: 14 claims extracted · 13 verified · 1 verified-with-nuance · 0 unverifiable · 0 contradicted.

Phase B doc-tester summary: 3 affected pages exercised (/app-host/resource-lifetimes/, /fundamentals/networking-overview/, /whats-new/aspire-13-4/) via Playwright against the frontend-dist artifact built for this PR head SHA (2f9c41bb). 0 critical issues · 0 warnings worth blocking on · 1 minor enhancement note.

Verdict: ✅ APPROVE — all non-narrative claims verified against source, doc-tester found no critical issues or warnings, and the single nuance (an existing behavior statement) is consistent with the source code.

Phase A — Claim verification

All non-narrative claims in the diff map cleanly to release/13.4 source.

Key checks against microsoft/aspire@4f218933:

• DcpExecutor.cs:700 — GetEffectiveIsProxied returns !resource.HasPersistentLifetime() || resource.IsContainer();. This means:
  • Session container: !false || true = true (proxied) ✅
  • Persistent container: !true || true = true (proxied) ✅ — matches the PR's new claim
  • Persistent executable / project: !true || false = false (proxyless) ✅ — matches the PR's narrowed claim
• ResourceBuilderExtensions.cs:1693 — WithEndpointProxySupport(bool proxyEnabled) exists; it sets ProxySupportAnnotation, which DcpExecutor.SupportsProxy() consults to force all endpoints on the resource to proxyless when disabled. ✅ matches the PR's WithEndpointProxySupport(false) reference.
• EndpointAnnotation.cs:204 — Port getter: _port ?? (IsProxied || _portSetToNull ? null : _targetPort);. For a proxyless endpoint declared with only targetPort and no explicit port, this evaluates to _targetPort immediately. ✅ matches .WithEndpoint(targetPort: 6379, isProxied: false) allocating host port 6379 right away.
• PR #17960 deletes OnDemandEndpointAllocationAnnotation.cs and removes the on-demand fallback path in DcpModelUtilities.cs and EndpointReference.cs, replacing it with direct AllAllocatedEndpoints.GetAllocatedEndpointAsync(...) lookups. ✅ confirms "no deferred allocation" claim.
• DcpNameGenerator.cs:79-83 — ThrowIfPersistentExecutableHasReplicas throws InvalidOperationException when a persistent resource has multiple replicas. ✅ matches "don't support replicas" claim.
• Dcp/Model/Executable.cs:64,84,90 — [JsonPropertyName("persistent")], [JsonPropertyName("start")], [JsonPropertyName("stop")] properties exist. ✅ matches "new persistent, start, and stop fields" claim.
• ContainerResourceBuilderExtensions.cs:587 — WithLifetime<T>(this IResourceBuilder<T> builder, ContainerLifetime lifetime) where T : ContainerResource is unchanged. ✅ matches "the existing container-specific WithLifetime(ContainerLifetime.Persistent) API is unchanged" claim.

Phase B — doc-tester results

Setup: Downloaded the frontend-dist artifact from CI run 27042834350 (PR head 2f9c41bb), served it locally with python -m http.server, and navigated via playwright-cli.

Pages exercised (scoped to this PR's diff):

1. /app-host/resource-lifetimes/ — #persistent-lifetime section
2. /fundamentals/networking-overview/ — #proxyless-endpoints section and EndpointAnnotation reference paragraph
3. /whats-new/aspire-13-4/ — feature-spotlight Caution Aside and Persistent executable and project lifetimes breaking-changes entry

Critical issues

None.

Warnings

None.

Passed checks

Recommendation (low-priority, not blocking)

The example sentence in fundamentals/networking-overview.mdx (.WithEndpoint(targetPort: 6379, isProxied: false)) is embedded in a prose paragraph rather than a code fence. A reader new to Aspire might benefit from a short fenced code block showing the builder.AddContainer("cache", "redis").WithEndpoint(targetPort: 6379, isProxied: false); form (which the source PR description already uses). This is purely an enhancement — the inline form is technically accurate and the surrounding paragraph is clear enough.

Knowledge-gap notes

None unique to this PR. The "ports your service is reachable on stay stable" wording in the Proxyless endpoints section is mildly awkward, but it is pre-existing copy that this PR does not modify, so it is out of scope.

Final verdict: ✅ APPROVE

This PR accurately rescopes the proxyless-by-default claim away from "all persistent resources" (which is now incorrect for containers after aspire#17960) to "persistent executables and projects only", correctly documents the new "persistent containers use proxied endpoints by default" behavior, and accurately documents the restored immediate-target-port allocation for proxyless container endpoints with only targetPort. All claims verified against release/13.4@4f218933. The rendered pages look clean and convey the corrected behavior unambiguously to a reader.

Hourly docs-from-code review — PR #1219 (revision 472f1ef)

Source-of-truth: microsoft/aspire@release/13.4 at SHA 4f218933552e18ff2874d1b6d5dc3fe671e3b6d9 (the merge commit for PR #17960 — exactly the upstream change this PR documents).

This revision adds a single clarification on line 41 of resource-lifetimes.mdx ("The proxy runs only while the AppHost is running, so the proxy address isn't reachable after the AppHost stops.") to the previously approved revision 2f9c41b. That new sentence is consistent with how DCP-managed proxies behave: the proxy is part of the AppHost-managed orchestration plane, so it stops when the AppHost stops, even though the persistent container itself keeps running.

Phase A — Claim verification

No contradicted or unverifiable claims, so no inline blocking comments are warranted.

Phase B — doc-tester results

Pages exercised: app-host/resource-lifetimes/, fundamentals/networking-overview/, whats-new/aspire-13-4/.

Constraint note: The locally running Astro dev server (localhost:4321) was on a stale main commit (May 2026) where two of the three affected pages return 404. Testing therefore used the live aspire.dev site, which currently still serves the pre-fix release/13.4 content — a useful "before" view that confirms the PR is correcting genuinely-incorrect statements (production currently reads, e.g., "Persistent resources default to proxyless endpoints…", with no carve-out for containers).

Critical issues: none.

Warnings (low severity, all non-blocking; none introduced by this PR):

• W1 — carryover wording, resource-lifetimes.mdx: "automatically persisted random executable ports aren't supported." compresses two ideas (random port auto-assignment + cross-run persistence) into a phrase a new reader may not unpack. Not changed by this PR.
• W2 — internal-implementation phrasing, networking-overview.mdx: "there is no deferred allocation" is concept-internal jargon. The example immediately afterward (WithEndpoint(targetPort: 6379, isProxied: false) → 6379) carries the meaning, so it's fine, but something like "Aspire doesn't wait until the container starts to assign the host port" would be more user-facing.
• W3 — assumes Aspire eventing model, networking-overview.mdx: "so integrations that depend on endpoint allocation before startup continue to work." Fine context for a release-notes audience; in the fundamentals page a brand-new reader has no prior model of "endpoint allocation before startup."

Passed checks:

• All three affected pages render cleanly on the live site; sidebar/TOC structure intact.
• The PR introduces no new internal links — link validation trivially passes.
• The new C# example uses valid named parameters matching the existing WithEndpoint overload.
• No new components (<Tabs>, <Aside>, <LinkCard>, etc.) — no risk of mismatched imports or missing pivot keys.
• Existing in-page anchor #container-lifetime-vs-data-durability and its danger Aside link still resolve.

Recommendation: Merge as-is. Treat W1–W3 as optional, separately-tracked editorial follow-ups.

Verdict

APPROVE — Phase A: every non-narrative claim verified. Phase B: no critical issues. The three Phase B warnings are pre-existing carryover/jargon that this PR did not introduce and that don't materially affect the corrections this PR delivers. This revision (472f1ef) is a strict clarity improvement over the previously-approved 2f9c41b.