Debug API

[isidorn]

We are looking into adding debug API to our vscode.d.ts. In order to design this as best as possible let's first look at the use cases and the current use of commands.

Use Cases

• Debug session end event Introduce a debugSessionEnds event  #28234
• Node internal modules navigator

Commands

Extension --> VS Code

• vscode.startDebug - extension can start a debug session by calling this command
• customDebugRequest - extension can send any DAP request to the currently active debug adapter
• debug.logToDebugConsole - extension can log a string to the debug console

VS Code --> Extension

• startSessionCommand - if contributed vscode calls this command instead of starting a debug session on its own
• initialConfigurations - if contributed vscode calls this command to get the initial content of the launch.json

Proposal

Minimal API proposal by @weinand and me. If name and type should be a part of DebugSession is very coraleted to the question @weinand raises below.

export namespace debug {
  export const onDidEndDebugSession: Event<DebugSession>;
}

export interface DebugSession {
   readonly name: string;
   readonly type: string;
   customRequest(requestName: string, args: any): Thenable<DebugRequestResult>;
}

[weinand]

One interesting question is: can a debugger extension only see the debug sessions that have the type introduced by the debugger extension or can it see all debug sessions of all types?

[DanTup]

I'd like to be able to report status messages from the debug adapter back to the extension so that I can show text in the status bar. There are some things that would be really spammy to log to the debug output window (for example, I think in full-VS it shows in the status bar every DLL symbols are being loaded for during debugging?).

If status messages is a common requirement, maybe something like an additional channel for OutputEvent (eg. status) would work, though being able to send complete custom messages (similar to customDebugRequest but in the opposite direction) would be ideal, since an extension/debugger than have complete two-way communication (something some debug adapters have apparently implemented themselves by hosting endpoints and connecting back).

[isidorn]

@DanTup thanks for the suggestion however we are taking this one step at a time, currently we are looking into what is the minimal set of APIs to make this good.
We will probably be focusing more on feature requests from next milestone onward

[DanTup]

@isidorn No worries; I figured it was worth you having the info even if you don't do anything with it for now (never hurts to have an idea of what people might want). My request is pretty minor tbh, the debugger just provides this info so I thought I'd look whether I could surface it anywhere.

[isidorn]

We have introduced an initial API, more details #28234 (comment)
@weinand should we close this issue, or leave it open as an umbrella item for future discussion regarding the debug API?

[weinand]

We leave this open as the umbrella item for future discussions.

[vadimcn]

I just want to highlight this comment here.

Say, my extension wants to send a custom command in response to a UI action. How does it know which debug session to send it to?
Should I still use workbench.customDebugRequest command in this scenario? But what if the active debug session was contributed by another extension?

[weinand]

In the July release there will be API to track the active debug session and to find out the type of the debug session. This makes it possible to send custom command only to those sessions, that are "owned" by your extension.

[hediet]

Is it possible somehow for an extension to ask the debug adapter to evaluate a given expression? It would be great if such an API method was available.

[weinand]

@hediet currently we do not have official API for this but you can use this workaround:

You can pass in evaluate to DebugSession.customRequest https://github.com/Microsoft/vscode/blob/8ace097b59ea3180ff47353782ca7a9214b37530/src/vs/vscode.d.ts#L6049
Pass the expression in this form https://github.com/Microsoft/vscode/blob/8ace097b59ea3180ff47353782ca7a9214b37530/src/vs/workbench/parts/debug/common/debugProtocol.d.ts#L882

The result has this format: https://github.com/Microsoft/vscode/blob/8ace097b59ea3180ff47353782ca7a9214b37530/src/vs/workbench/parts/debug/common/debugProtocol.d.ts#L900

[hediet]

@weinand thanks for your quick reply. However, running this code:

const result = await vscode.debug.activeDebugSession.customRequest(
      "evaluate", { expression: "myexpression" });

throws an exception with the message "not available" (I get the German error message "Nicht verfügbar").
I set enableProposedApi to true in package.json and made sure that there is an active debug session.

Is there an event that fires when the debugger switches between running and pause mode?
I want to code an extension that can visualize expressions while debugging - if you want, a more graphical watch window.

[weinand]

Yes, some debuggers can only "evaluate" if they are stopped.

Currently there is no API to track the debug status. Here is the corresponding feature request: #30810

BTW, It is no longer necessary to set "enableProposedApi" to true, since the API already lives in "vscode.d.ts" (and not vscode.proposed.d.ts").

[hediet]

I always get this error (even if the debugger is stopped). In order to access the debug namespace, I had to copy the content from vscode.d.ts of the github repository into the vscode.d.ts file of the most recent (1.1.7) vscode package. I am using the most recent version of vs code (1.18.1). Maybe a bug?

[weinand]

Please update your vscode dependency in your package.json, e.g.:

	"engines": {
		"vscode": "^1.18.0",
		"node": "^7.4.0"
	},

and then delete node_modules folder and run npm install again.

Or just run the postinstallscript:

	"scripts": {
		"postinstall": "node ./node_modules/vscode/bin/install",
                /// ....
	},

What debugger extension are you using?

[hediet]

I am using this launch.json:

{
	"version": "0.2.0",
	"configurations": [	
		{
			"type": "node",
			"request": "launch",
			"name": "Launch Program",
			"program": "${workspaceFolder}/index.js"
		}
	]
}

(the default nodejs debugger)
After deleting the node_modules folder and reinstalling all packages, it found the debug namespace - just changing the version in package.json and running npm install didn't do it. However, the error is still being thrown.

[hediet]

Are there any updates? I never managed to get it working (i.e. asking the debugging adapter to evaluate expressions). I am waiting for this feature for an awesome extension I want to prototype.

[isidorn]

@hediet we now support many new things in the debug api. You can find it here
@weinand I see no use of keeping this issue open, thus closing it.

[hediet]

@isidorn I still don't see how to ask the debugger to evaluate a given expression. Did I miss something in the documentation?

[isidorn]

@hediet appologies, I misunderstood what you are exactly meaning to do. The evaluate request is still not a part of the API. For that one please create a brand new feature request so we have this on our radar. Thank you.

[weinand]

The "Evaluate Debug API" discussion continues here: #42989