Walkthrough: Quickly Testing a Debug Adapter in Visual Studio

This walkthrough demonstrates how a debug adapter can quickly be loaded into Visual Studio for testing purposes, without setting up a proper installable VSIX package. This allows for fast verification of basic scenarios with a new debug adapter.

Prerequisites

• Visual Studio 2017 15.6 Preview 2 or later
• Git (https://git-scm.com/download/win)

Set up the "Debug Adapter Host" repo

For this walkthrough, we'll be using the "SampleDebugAdapter" available in the "VSDebugAdapterHost" repository.

Clone the repo and build the SampleDebugAdapter

git clone https://github.com/Microsoft/VSDebugAdapterHost.git

Open the solution "VSDebugAdapterHost\src\VSDebugAdapterHostSamples.sln" in Visual Studio.

Build the solution by clicking Build -> Build Solution.

Open the file "src\sample\SampleDebugAdapter\SampleScripts\TestScript.txt" in Visual Studio, and set a breakpoint somewhere in it.

Create a launch configuration file

Debug adapters in Visual Studio use the same "launch.json" configuration that you may already be familiar with from VS Code. By adding a few special properties that have special meaning to the Debug Adapter Host, we can test a debug adapter without any packaging or installation required.

Create a file called "launch.json" somewhere easily accessible, and add the following content:

{
    "$adapter": "C:\\Users\\andrewcr\\source\\repos\\VSDebugAdapterHost\\bin\\Debug\\SampleDebugAdapter.exe",

    "type": "sample",
    "request": "launch",
    "program": "C:\\Users\\andrewcr\\source\\repos\\VSDebugAdapterHost\\src\\sample\\SampleDebugAdapter\\SampleScripts\\TestScript.txt"
}

NOTE: You'll need to update the paths to reflect the location of the repository on your system.

This works if your adapter is an executable, as is the case with the SampleDebugAdapter. If your adapter is Node-based, you have two options:

Option 1: Use the globally installed version of Node.js

Specify the path to "node.exe" as the adapter, and the path to the debug adapter as an argument, e.g.:

{
    "$adapter": "c:\\Program Files\\nodejs\\node.exe",
    "$adapterArgs": "c:\\path\\to\\debugAdapter.js",

    "type": "your-adapter-id",
    "request: "launch",
    // Other-adapter specific properties here
}

Option 2: Use the Debug Adapter Host's "runtime" support

Launch the Visual Studio Installer and ensure that the "Runtime for components based on Node.js v7.4.0 (x86)" component is installed:

Update your "launch.json" as follows:

{
    "$adapter": "c:\\path\\to\\debugAdapter.js",
    "$adapterRuntime": "node-x86-7.4.0",

    "type": "your-adapter-id",
    "request: "launch",
    // Other-adapter specific properties here
}

Enable adapter logging

The Debug Adapter Host can provide a great deal of debugging information through its logging mechanism, which can make debugging integration issues with debug adapters much simpler. In addition to a trace of all the CDP messages sent to or from the adapter, the log includes any warnings or errors generated by the Debug Adapter Host.

Open the Command Window by clicking View -> Other Windows -> Command Window.

In the command window, type:

DebugAdapterHost.Logging /On /OutputWindow

This will enable logging, and direct the log output to the Output window. If the Output window isn’t visible, you can open it by clicking View -> Output. The log output will appear in a separate Debug Adapter Host Log pane that you can view by selecting it in the Show output from dropdown. The pane won’t appear in the list unless there is log output to show.

Launch the adapter

Open the Command Window by clicking View -> Other Windows -> Command Window.

In the command window, type:

DebugAdapterHost.Launch /LaunchJson:"c:\path\to\launch.json"

The debug adapter should begin running and stop at the breakpoint we set earlier.

Note that the log may contain warnings due to configuration items we didn't provide in our launch.json. This is generally OK, as the point of this method is simply to quickly test the basic adapter functionality and look for any major issues that would need to be fixed before packaging it.