Skip to content

[docs] Document project serverReadyAction override in VS Code extension #1459

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
aspire-repo-bot wants to merge 1 commit into
base: release/13.5
Choose a base branch
from
+15 −0
Open

[docs] Document project serverReadyAction override in VS Code extension #1459

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions src/frontend/src/content/docs/get-started/aspire-vscode-extension.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -131,6 +131,21 @@ All of these commands are debuggable; you can step into custom publishers and de

The `debuggers` property forwards configuration to specific debuggers. Recognized keys are: `apphost`, `project` (C#/.NET), `node`, `python`, `browser`, and `azure-functions`.

For `project`, the extension normally generates a `serverReadyAction` from the project's `launchSettings.json` to automatically open the browser when the server is ready. Set `project.serverReadyAction` explicitly to override this generated default with your own action and pattern:

@IEvangelist David Pine (IEvangelist) Aug 11, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

```json title=".vscode/launch.json — override the generated serverReadyAction"
{
"debuggers": {
"project": {
"serverReadyAction": {

@adamint Adam Ratzman (adamint) Aug 11, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

"action": "openIntegratedBrowser",
"pattern": "Now listening on:\\s+\\[?(https?://[^\\]\\s]+)"

@IEvangelist David Pine (IEvangelist) Aug 11, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

}

@adamint Adam Ratzman (adamint) Aug 11, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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+?

}
}
}
```

Finally, you can specify `env` and `args` to set environment variables and command-line arguments for the AppHost process.

```json title=".vscode/launch.json — deploy with debugger settings, env, and args"
Expand Down
Loading