[docs] Document project serverReadyAction override in VS Code extension

[aspire-repo-bot]

Documents changes from microsoft/aspire#19200

@ellahathaway

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

Why

The source PR fixes a bug where the VS Code extension replaced an explicitly configured debuggers.project.serverReadyAction with the action generated from launchSettings.json, preventing users from overriding the default browser-opening behavior. The generated serverReadyAction is now treated as a default, and any user-provided value is preserved.

What changed

• Updated src/frontend/src/content/docs/get-started/aspire-vscode-extension.mdx to document that project.serverReadyAction can be set explicitly to override the generated default, with a JSON example matching the source PR's user-facing usage snippet.

Files modified

• src/frontend/src/content/docs/get-started/aspire-vscode-extension.mdx (updated, existing page)

Generated by PR Documentation Check for #19200 · auto · 36.4 AIC · ⌖ 7.5 AIC · ⊞ 19.4K · ◷

[aspire-repo-bot]

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #1459. 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

Documents how the Aspire VS Code extension handles serverReadyAction for C#/.NET projects, specifically clarifying that users can override the extension-generated default.

Changes:

• Adds guidance explaining that a generated serverReadyAction can be overridden via launch configuration.
• Adds a JSON example showing how to set a custom serverReadyAction pattern/action.

Suppressed comments (1)

src/frontend/src/content/docs/get-started/aspire-vscode-extension.mdx:141

• This JSON example is presented as a full .vscode/launch.json launch configuration, but it only contains the debuggers property. For consistency with the other examples in this page (and to avoid copy/paste confusion), include the standard Aspire launch configuration fields (type, request, name, program) alongside debuggers.

{
  "debuggers": {
    "project": {
      "serverReadyAction": {
        "action": "openIntegratedBrowser",

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Adam Ratzman (adamint)]

Could we fix or call out the AppHost behavior before documenting this? A .NET AppHost also has launch type project, and debuggers.project is applied after debuggers.apphost, so this serverReadyAction is preserved on the AppHost too. I think that means this can open on AppHost output instead of only child projects.

[Adam Ratzman (adamint)]

This pattern truncates IPv6 URLs at the closing bracket. For Now listening on: http://[::1]:5000, the capture is http://[::1, so openIntegratedBrowser gets an invalid URL. Could we use a pattern that retains brackets inside the URL, or reuse the extension default https?://\\S+?

[Adam Ratzman (adamint)]

I left two inline comments: debuggers.project also applies to the .NET AppHost, and the sample pattern truncates IPv6 URLs. The existing Copilot feedback already covers the property path and incomplete launch.json shape.

[David Pine (IEvangelist)]

🤖 Automated docs-accuracy review — ⚠️ changes requested

Phase A source of truth: microsoft/aspire @ release/13.5 (SHA 1d922813c0f9bc14f7d817c817a8ab46b288bb44) — the branch this PR targets.
Claims extracted: 3 non-narrative → 1 verified, 1 contradicted, 1 unverifiable, 0 verified-with-nuance.
Phase B (doc-tester): exercised /get-started/aspire-vscode-extension/ on a local dev server serving this PR — page renders (HTTP 200), 0 critical, 0 warnings.

Headline

The new section documents a debuggers.project.serverReadyAction override that is not implemented on release/13.5. On this branch the extension unconditionally overwrites any user-supplied serverReadyAction for project resources, so the documented override has no effect. The mechanism that makes it work exists on main (guarded by serverReadyAction === undefined), so this doc appears to have landed on the release branch ahead of the code. See the two inline comments for the exact source evidence.

---

Phase A — Claim verification

Two inline comments are anchored to the affected lines (the contradicted override claim, and the openIntegratedBrowser example that doesn't exist on this branch).

✅ Verified claims (1) with evidence

Source (all microsoft/aspire@release/13.5): extension/src/debugger/languages/dotnet.ts, extension/src/debugger/debuggerExtensions.ts, extension/src/debugger/launchProfiles.ts, extension/src/test/dotnetDebugger.test.ts.

1. "For project, the extension normally generates a serverReadyAction from the project's launchSettings.json to automatically open the browser when the server is ready." (config/behavior) — verified.
   dotnet.ts:451-452 sets debugConfiguration.serverReadyAction = determineServerReadyAction(baseProfile?.launchBrowser, baseProfile?.applicationUrl, baseProfile?.launchUrl) for every non-AppHost (project) resource. determineServerReadyAction (launchProfiles.ts:368-383) reads those launch-profile fields and returns { action: "openExternally", pattern: "\\bNow listening on:\\s+https?://\\S+", uriFormat }. Corroborated by dotnetDebugger.test.ts:1736-1738 ("serverReadyAction should be present with the applicationUrl").
   Minor nuance: the generated action is openExternally (opens the external browser), and it is only produced when the profile has launchBrowser: true and an applicationUrl; otherwise none is generated.

---

Phase B — Doc-tester results (blind "new user" pass, no source code consulted)

Route exercised: /get-started/aspire-vscode-extension/ (served from a local Astro dev server with this PR's content; navigated via playwright-cli).

✅ Passed checks

• Page compiles and returns HTTP 200; title "Aspire Visual Studio Code extension | Aspire". No MDX/compile errors, no browser console errors.
• The new paragraph renders with correct inline-code formatting (serverReadyAction, launchSettings.json, project.serverReadyAction).
• The new JSON block renders with its title ".vscode/launch.json — override the generated serverReadyAction", correct syntax highlighting, and a working copy button; it is placed logically between the debuggers-keys paragraph and the following env/args paragraph.

🔴 Critical issues

• None (rendering).

⚠️ Warnings

• None.

💡 Recommendations / knowledge gaps (minor, non-blocking)

• The allowed action values aren't enumerated, so a reader can't tell what is valid besides the openIntegratedBrowser shown.
• The relationship between the pattern capture group and the URL the browser opens isn't explained.

Blind-user note: nothing on the rendered page reveals the accuracy problem — it reads as a well-formed, working feature. The mismatch is only detectable by checking the extension source on the target branch (Phase A). This is the intended division of labor between the two phases.

---

Verdict

REQUEST_CHANGES — one contradicted claim: the documented project.serverReadyAction override does not function on release/13.5 (the user value is silently overwritten by the generated default). Suggested resolution: port the override support (the serverReadyAction === undefined guard in dotnet.ts) to release/13.5, or retarget this documentation to the branch/release where the override actually ships. The "generated default" paragraph (verified) is accurate and can stay.

_{Reviewed head SHA 2e8a9a725e00bc1e43fb1addd00669c0913e5082. Phase A read microsoft/aspire@release/13.5: extension/src/debugger/{languages/dotnet.ts, debuggerExtensions.ts, launchProfiles.ts, test/dotnetDebugger.test.ts}.}

[David Pine (IEvangelist)]

Contradicted on release/13.5 (this PR's target branch).

This sentence says setting project.serverReadyAction overrides the generated default. On release/13.5 it does not take effect. In extension/src/debugger/debuggerExtensions.ts the user's debuggers['project'] block — including serverReadyAction — is merged into the config first:

// debuggerExtensions.ts:75-76
if (debugSessionConfig.debuggers[launchConfig.type]) {
    Object.assign(configuration, debugSessionConfig.debuggers[launchConfig.type]);
}

…and only after that is the language callback invoked (debuggerExtensions.ts:83). That callback, in extension/src/debugger/languages/dotnet.ts, then unconditionally reassigns serverReadyAction for every non-AppHost project:

// dotnet.ts:451-453
if (!launchOptions.isApphost) {
    debugConfiguration.serverReadyAction = determineServerReadyAction(baseProfile?.launchBrowser, baseProfile?.applicationUrl, baseProfile?.launchUrl);
}

determineServerReadyAction (launchProfiles.ts:368-370) does not consider any existing value — it returns undefined when launchBrowser/applicationUrl aren't set, otherwise an openExternally default. So the user-supplied action is discarded in every case, and nothing re-applies it after the callback (the function returns configuration at line 87).

The guard that makes this override work — && debugConfiguration.serverReadyAction === undefined — exists on main, but not on release/13.5. Either that code change needs to be ported to release/13.5, or this documentation should target the release where it actually ships.

[David Pine (IEvangelist)]

Unverifiable on release/13.5. The value openIntegratedBrowser (and this exact pattern) does not appear anywhere in the extension source or tests on this branch. The only serverReadyAction action the extension produces or tests on release/13.5 is openExternally (extension/src/debugger/launchProfiles.ts:380). This exact example — action: 'openIntegratedBrowser' with pattern: 'Now listening on:\\s+\\[?(https?://[^\\]\\s]+)' — is present only on main (e.g. extension/src/test/dotnetDebugger.test.ts), which is additional evidence that the override feature this example illustrates has not yet shipped in release/13.5.