Debug protocol: Support browser launching

[gregg-miskelly]

Currently the debug protocol has no way for a debug adapter to request that the IDE open up a web browser. Some debug adapters, such as the C# debug adapter, can start a web browser as part of launching a web server project. The debug adapter needs some control to be able to signal when the web server is ready.

This could either be designed as an event (ex: WebServerReady) or as a callback request like starting processes in the terminal.

Dependent issue: dotnet/vscode-csharp#2657
Related issue: microsoft/vscode-debugadapter-node#153

[weinand]

Proposal:

If a client (frontend) supports the 'openExternal' request, it must announce this by setting the supportsOpenExternalRequest in the 'initialize' request to true:

/** Arguments for 'initialize' request. */
export interface InitializeRequestArguments {

	// ...
	
	/** Client supports the openExternal request. */
	supportsOpenExternalRequest?: boolean;
}

And a debug adapter can then use the 'openExternal' request by passing the uri as the only (mandatory) argument:

/** OpenExternal request; value of command field is 'openExternal'.
	This request is sent from the debug adapter to the client to open a url in an external program, e.g. a http(s) or mailto-link, using the default application.
*/
export interface OpenExternalRequest extends Request {
	// command: 'openExternal';
	arguments: OpenExternalArguments;
}

/** Arguments for 'openExternal' request. */
export interface OpenExternalArguments {
	/** The uri that should be opened. */
	url: string;
}

/** Response to 'openExternal' request. This is just an acknowledgement, so no body field is required. */
export interface OpenExternalResponse extends Response {
}

[weinand]

Gregg Miskelly (@gregg-miskelly) Andrew Crawley (@andrewcrawley) Chuck Ries (@chuckries) Don Jayamanne (@DonJayamanne) Pierson Lee (@pieandcakes)
You can find my proposal for a openExternal request in the branch;

For your convenience I've added the corresponding TypeScript definitions above.

I'd appreciate any feedback.

[DonJayamanne]

Sounds, good, however wouldn't a custom request also solve this.
Send a custom request from debug adapter, and handle that from the extension to launch the browser?
Just trying to understand use causes for custom requests.

[weinand]

Yes, a custom request picked up in the corresponding extension could do the same. However, including this new request in the DAP simplifies the case where debug adapters are hosted by a different client than VS Code.

[auchenberg]

One aspect we should think about here, is how this potentially could play together with other debug adaptors in VS Code?

A typical scenario for ASP.Net developers is
0) Press F5 / Launch

1. Launch asp.net server-side
2. Launch Chrome in debug mode
3. Attach VS code to .net
4. Attach VS Code to Chrome
   = debug both stacks at the same time.

Ideas: In the .net DA, for the OpenExternalRequest handler instead of having it's own browser logic, maybe it could try to start a browser debugging session for Chrome/Edge/Firefox?

If no debugging is wished, fallback to new vscode.openExternal api?

[weinand]

Kenneth Auchenberg (@auchenberg) multi-debugger cases like your scenario are best handled in an extension since a debug adapter has no access to VS Code's extension API (and cannot assume that it runs in VS Code at all).

The openExternal request is for the scenario from Gregg Miskelly (@gregg-miskelly)'s initial comment or maybe for "The debugger for Chrome".

roblourens and Gregg Miskelly (@gregg-miskelly) please chime in for additional thoughts...

[gregg-miskelly]

I didn't see any changes in your branch, but the type script definitions above look good to me.

[weinand]

Gregg Miskelly (@gregg-miskelly) sorry, I forgot to push. The commit is ac0289e

[gregg-miskelly]

LGTM