Stop supporting vscode.startDebug command

[isidorn]

Now that we have startDebugging API we should remove the command vscode.startDebug which we used as a workaround.

https://github.com/Microsoft/vscode/blob/master/src/vs/workbench/api/node/extHostApiCommands.ts#L198

[vadimcn]

I use startSessionCommand in package.json to launch my debug adapter and add debugServer attribute into DebugConfiguration. At the end, I invoke vscode.startDebug to actually start a debug session, because I found that debug.startDebugging() just recursively invokes my startSessionCommand again. Simply returning from startSessionCommand after having modified the config doesn't seem to do anything.

How can I implement this scenario without using vscode.startDebug?

On a related note, it would be nice if startSessionCommand could obtain a session id of the debug session it initiated. I want to make sure my adapter gets terminated at the end of the session, in case it gets wedged, so I hook onDidTerminateDebugSession event. Unfortunately, I have not found a clean way to associate data (a process id in this case) with the started session.

[isidorn]

@vadimcn please checkout our new VSCode Debug API, all of this should be possible by using a DebugConfigurationProvider

As for the debugSession id you can get it from the API here

[weinand]

@vadimcn here is the new way of doing this.

Implement a DebugConfigurationProvider:

export class WhateverConfigurationProvider implements vscode.DebugConfigurationProvider {

  /**
   * returns initial debug configurations.
   */
  provideDebugConfigurations(folder: vscode.WorkspaceFolder | undefined, token?: vscode.CancellationToken): vscode.ProviderResult<vscode.DebugConfiguration[]> {

    const config = {
      type: 'whatever',
      request: 'launch',
      name: 'Launch a whatever program in debug mode...'
    };
    
    return [ config ];
  }

  /**
   * "massage" launch configuration before starting the session.
   */
  resolveDebugConfiguration(folder: vscode.WorkspaceFolder | undefined, config: vscode.DebugConfiguration, token?: vscode.CancellationToken): vscode.ProviderResult<vscode.DebugConfiguration> {
  
    config.debugServer = 12345;

    return config;
  }
}

and register it in the activate method of your extension like this:

context.subscriptions.push(vscode.debug.registerDebugConfigurationProvider('whatever', new WhateverConfigurationProvider()));

And in your package.json add a onDebug activation event:

	"activationEvents": [
		"onDebug",
		// ...
	],

BTW, both hooks are optional, so you only need to implement what you need.

[vadimcn]

@weinand: I suppose I could launch adapter process in resolveDebugConfiguration callback, assuming it only ever gets called before actually starting a debug session.

@isidorn: Still not sure how would I go about associating a pid with a debug session. By the time session id is available (I think onDidStartDebugSession is the earliest event), I will have returned from resolveDebugConfiguration, so the only option is to stash the pid in a global variable. This gets a bit complicated if we consider multi-process debug sessions. At the moment I save pids in a global map indexed by a session name, so I can re-associate them once I receive the onDidStartDebugSession event, but this still doesn't handle the case if user wants to launch the same debug config twice...

[weinand]

@vadimcn yes, launching the adapter server in resolveDebugConfiguration is a good strategy.

For the other problem associating custom data with a debug session, I'm looking into a solution. Your scenario is a great use case. Since some areas of the debug API are "proposed", we still have some flexibility to add the needed functionality.

BTW, I've just upgraded mock-debug to the new DebugConfigurationProvider.

[vadimcn]

So, what's the outcome of all this? Is DebugConfigurationProvider.resolveDebugConfiguration the official replacement for startSessionCommand?

[isidorn]

Yes.