Add debugging attach support to VS Code

[AndrewBrianHall]

VS Code should add platform level support that provides a structured way for debug adapters to implement and provide attach to process functionality that doesn't rely on updating the launch.json file every time the developer needs to attach to the process.

Key requirements are:

• Standardized entry point for all debug adapters
• Ability for user to select desired debug adapter
• Debug adapter is able to provide its concept of what the user intends to attach to (e.g. process id, url)
• Debug adapter does not need to generate an on disk .json file to achieve the attach

[weinand]

What we plan to do:

We will extend the concept of system variables with a mechanism to trigger commands.
This makes it possible to add something like ${action.PickProcess} to a launch configuration, e.g.:

       {
            "name": ".NET Core Attach",
            "type": "coreclr",
            "request": "attach",
            "processName": "${action.PickProcess}"
        }

Starting a debug session with this launch config will run the 'PickProcess' command where the user can select a process. The result is a string that becomes the value of the variable. Cancelling the command will cancel the launch of the debug session.

The implementation of the PickProcess command will live in the debugger extension and most likely is based on the QuickPick UI. But an extension is free to use whatever UI is available for an extension.

The package.json of the debugger extension will contribute a mapping between the system variable (‘PickProcess’) and the command implemented by the extension, e.g. something like:

"variables": {
    "PickProcess": "extension.pickProcess"
}

At a later point we can decide to provide a default picker action in VS Core and the debugger extensions are free to remove their implementations.

/cc @isidorn @chrisdias

[edumunoz]

Thanks Andre for the details on the proposal. I have a few questions:

I don't think this is possible, but is there a way of passing arguments to the action being launched by VSCode? Something that would be useful might be to pass the launch.json entry that is being launched.
It would be useful if we want to implement multiple configurations for attaching, e.g., remote machine and locally. If passing arguments to the action is not possible, two options are:

1. Have multiple Quick Pick dialogs every single time the action is triggered, e.g., the first level would be the type of attach (local vs remote). This seems inconvenient given that some users will always do local and some will always do remote.
2. Have multiple actions that serve as entry points for the different types of attach, and offer multiple entries in the launch.json file, each with a different action. This has the disadvantage of having multiple entry points, and depending on the attach permutations, may not scale nicely.

Do you have any other suggestions? I think option 2 is more user friendly.

Some questions about the behavior of this feature:

1. What happens if there is more than one action in the active launch.json entry? Will each action be called sequentially? In this case, it seems to me that passing the launch.json entry to each action might be useful.
2. What happens if the provided action is launched via the command palette?
3. How is the result string communicated from the debug adapter to VSCode?

[weinand]

@edumunoz here are my answers to the questions from above:

• it is possible to pass the selected launch config section to the pick action. I had planned this anyway.
• local vs. remote: why make this decision in the pick process? The launch.json could have two launch configs, one for the local and one for remote case. For this it would use a ${action.PickProcess} and a ${action.PickRemoteProcess}. Your extension would implement two pick commands for this.
• having more than one action in the active launch.json entry: yes, we will pass the launch config.
• launching the pick action via the command palette: only if we cannot make these actions invisible will the user be able to run the action, but the result will go to /dev/null anyway.
• How is the result string communicated from the debug adapter to VSCode? The string is not communicated back from the debug adapter, but from the picker command running in the extension (host). These are different processes. The string (pid etc.) becomes the command's result. Since VS Code is running the command as part of the start debug session action, the result can be assigned to the system variable and then the substitution mechanism will place it in the launch config.

[edumunoz]

Thanks for the responses @weinand.

The string is not communicated back from the debug adapter, but from the picker command running in the extension (host).

Yes, sorry for mixing both.

The string (pid etc.) becomes the command's result

I assume this can be a Promise<string> that the callback of the command would return.

[weinand]

@edumunoz, @Andrew-MSFT, @isidorn, @egamma
As an example for the process picker work I've added "Attach to Process" support to Node Debug. Please see this video.

Please note: I'm launching a simple express application from the command line without running node.js in debug mode. With the picker I select the node process by filtering on the arguments "bin/www". The variable ${action.pickProcess} in the launch config is then replaced by the process id of the node process.

[edumunoz]

@weinand very cool, thanks for showing us.

[weinand]

@edumunoz the picker code (from mock-debug) is here: https://github.com/Microsoft/vscode-mock-debug/blob/master/src/extension.ts

[edumunoz]

I integrated what I was working on with your prototype and it works great.

Let us know once the implementation makes it to master.

[isidorn]

The implementation is on master now.

[weinand]

@edumunoz since node.js supports 'Attach to Process' too, I've added the full process picker flow to node-debug. This includes:

• node-debug's 'attach' request accepts a new optional 'processId' attribute
• extension.ts implements an extension.pickNodeProcess command
• package.json makes this command available as an action variable action.PickProcess (Please note: since there is no command contribution for the extension.pickNodeProcess command, it is not available through the command palette),
• the initial node-js launch.json contains an 'Attach to Process' launch config

I've already modified the process picker in extension.ts slightly to better understand the OS X application bundle structure.
I plan to add code that filters all processes that are not node or electron (because it doesn't make sense - or it is even dangerous - to try to attach to them).

@gregg-miskelly, @roblourens, @daviwil, @rkeithhill, @felixfbecker, @rebornix, @MSLaguana, @lukehoban: this feature is useful if you want to add process, url, or port pickers to your launch configs. Here is a video.

Please be aware that this is just a first cut and things might change until the end of this sprint. But we'd appreciate any feedback.