示例-调试适配器

虽然VS Code实现了一个原生的调试界面，但是它不能直接和调试器通信，而是依赖于调试插件实现调试和运行时的功能特性。

这些调试插件各不相同，主要是因为他们的实现并不运行在扩展主机中，而是作为一个分离的独立程序。我们称这些调试插件为适配器是因为他们能“适配”API、具体的调试器，或者由VS Code定义的调试适配器协议(DAP)。

适配器运行框架

将调试适配器作为单独的运行程序有两方面的原因：第一，对于适合的调试器或者运行时，有其对应的语言来实现；第二，一个独立的程序能运行于底层调试器或者运行时上，也更轻松地运行在特权模式中。

为了避免本地防火墙的问题，VS Code依靠stdin/stdou和适配器通信，而不是sockets等的通信流行机制。

每个调试器插件定义了一种调试类型，而且会被VS Code的启动配置使用。当调试器session结束，调试器也会关闭。

示例-调试适配器 - 图2

VS Code自带Node.js的调试插件。你也可以在插件市场找到更多调试插件，本篇教程接下来会告诉你怎么开发一个调试器插件。

插件Mock Debug

从零开始做一个调试适配器对本篇教程来说实在太重了。因此我们会从一个简单的教学适配器开始，这个模拟的调试插件支持步进，继续，断点，异常捕捉和变量审查，但它并不会真的连接到调试器上。

不过在深入开发模拟调试器之前，我们先安装一个插件市场上的预编译版本来玩玩：

  • 切换到插件侧边栏，输入“mock”然后找到Mock Debug插件。
  • 安装然后重启VS Code

试试Mock Debug吧：

  • 创建一个空文件夹mock test，然后用VS Code打开
  • 新建readme.md，然后输入几行文字
  • 切换到调试侧边栏，然后按齿轮⚙按钮
  • VS Code会让你选择“environment”，然后创建一个默认的启动配置文件。选择“Mock Debug”。
  • 按下绿色的开始按钮，然后进入我们的readme.md文件

调试会话（debug session）就开始了，你可以按“步进（step）”，设置断点，捕捉异常（如果文本中出现exception字样）

示例-调试适配器 - 图3

那么现在我们要正式学习Mock Debug示例了，我们建议你先删除这个插件。

Mock Debug开发设置

接下来让我们获取源码，在VS Code中开始开发吧：

  1. git clone https://github.com/Microsoft/vscode-mock-debug.git
  2. cd vscode-mock-debug
  3. npm install

打开项目文件夹vscode-mock-debug，看看里面有什么：

  • package.json mock-debug插件的配置清单
    • 列出了插件的发布内容配置点
    • complie脚本用于编译Typescript到out文件夹中，watch则是侦听后续的源码变动
    • vscode-debugprotocol、vscode-debugadapter 、vscode-debugadapter-testsupport是NPM模块，简化了基于node的调试适配器开发工作
  • src/mockRuntime.ts 提供了简单API的虚拟运行时
  • src/mockDebug.ts适配代码运行时到调试适配器协议中，你能在这个文件中找到各种各样的调试适配器协议和请求。
  • 因为调试插件的实现就在调试适配器中，所以我们就完全没有编写平常要求的插件代码的必要了（如：运行在扩展主机环境的代码），不过Mock Debug有一个小的src/extension.ts文件，这个文件描述了一个调试插件都能做些什么。

现在构建然后加载Mock Debug插件，选择插件加载配置，然后按下F5，一开始，全部的Typescript编译会进入编译，然后输出到out文件夹中。全部构建完成后，会启动一个watch task用于监听你所作的任何改动。

之后会弹出一个新的VS Code窗口“[扩展开发主机]”，Mock Debug插件就运行在调试模式中。在这个窗口中打开mock test，再打开readme.md文件，F5启动调试会话。

示例-调试适配器 - 图4

现在插件已经启动在调试模式中了，你可以在src/extension.ts打断点，但是就如我之前所说，这个文件没有什么有意思的代码，真正重要的部分都在调试适配器中。

想要调试调试适配器本身，我们必须首先运行在调试模式中。运行调试适配器服务，然后配置VS Code连接上就好了。选中调试面板，从下拉面板中加载Server配置文件，然后按下绿色的开始按钮。

因为我们已经激活了一个插件的调试会话，VS Code调试器界面现在进入了一个多会话模式，我们也能从调试窗口中看到Extention和Server的调用栈视图：

示例-调试适配器 - 图5

现在我们可以调试2个插件了，同时模拟调试适配器。使用Extension + Server的启动配置文件可以更快到达这一步。我们在下面提供了一个更为简单的调试插件和调试适配器的方案。

那么回到正题，我们现在给src/mockDebug.ts的launchRequest(...)方法开头添加一个断点，最后在启动配置中添加debugServer和4711端口将mock debugger连接到调试适配服务器。

  1. {
  2.     "version": "0.2.0",
  3.     "configurations": [
  4.         {
  5.             "type": "mock",
  6.             "request": "launch",
  7.             "name": "mock test",
  8.             "program": "${workspaceFolder}/readme.md",
  9.             "stopOnEntry": true,
  10.             "debugServer": 4711
  11.         }
  12.     ]
  13. }

如果你现在加载了这份调试配置，VS Code就不会将mock debug适配器作为分离进程启动，而是直接连接到已启动的服务器端口4711上，然后你就可以在launchRequest上打断点了。

在这个步骤之后，你就可以轻松地编辑，编译和调试Mock Debug项目了。

但是真正的工作现在才开始：你需要把src/mockDebug.ts和src/mockRuntime.ts中的关于”mock”的实现替换成真正和调试器或者运行时通信的代码，你首先可能需要理解调试适配器协议。

剖析调试插件的package.json

package.json文件除了提供调试器所需的调试适配器和调试插件的实现细节之外，这个文件还包括了各式各样和调试相关的内容配置点。

我们现在就来仔细看看Mock Debug的package.json

就像每个VS Code插件一样，package.json声明了基本的插件属性如name，publisher，version。而categories帮助我们能更快地在插件市场找到它。

  1. {
  2.     "name": "mock-debug",
  3.     "displayName": "Mock Debug",
  4.     "version": "0.24.0",
  5.     "publisher": "...",
  6.     "description": "Starter extension for developing debug adapters for VS Code.",
  7.     "author": {
  8.         "name": "...",
  9.         "email": "..."
  10.     },
  11.     "engines": {
  12.         "vscode": "^1.17.0",
  13.         "node": "^7.9.0"
  14.     },
  15.     "icon": "images/mock-debug-icon.png",
  16.     "categories": [ "Debuggers" ],
  18.     "contributes": {
  19.         "breakpoints": [
  20.             { "language": "markdown" }
  21.         ],
  22.         "debuggers": [{
  23.             "type": "mock",
  24.             "label": "Mock Debug",
  26.             "program": "./out/mockDebug.js",
  27.             "runtime": "node",
  29.             "configurationAttributes": {
  30.                 "launch": {
  31.                     "required": ["program"],
  32.                     "properties": {
  33.                         "program": {
  34.                             "type": "string",
  35.                             "description": "Absolute path to a text file.",
  36.                             "default": "${workspaceFolder}/${command:AskForProgramName}"
  37.                         },
  38.                         "stopOnEntry": {
  39.                             "type": "boolean",
  40.                             "description": "Automatically stop after launch.",
  41.                             "default": true
  42.                         }
  43.                     }
  44.                 }
  45.             },
  47.             "initialConfigurations": [
  48.                 {
  49.                     "type": "mock",
  50.                     "request": "launch",
  51.                     "name": "Ask for file name",
  52.                     "program": "${workspaceFolder}/${command:AskForProgramName}",
  53.                     "stopOnEntry": true
  54.                 }
  55.             ],
  57.             "configurationSnippets": [
  58.                 {
  59.                     "label": "Mock Debug: Launch",
  60.                     "description": "A new configuration for launching a mock debug program",
  61.                     "body": {
  62.                         "type": "mock",
  63.                         "request": "launch",
  64.                         "name": "${2:Launch Program}",
  65.                         "program": "^\"\\${workspaceFolder}/${1:Program}\""
  66.                     }
  67.                 }
  68.             ],
  70.             "variables": {
  71.                 "AskForProgramName": "extension.mock-debug.getProgramName"
  72.             }
  73.         }]
  74.     },
  76.     "activationEvents": [
  77.         "onDebug",
  78.         "onCommand:extension.mock-debug.getProgramName"
  79.     ]
  80. }

现在我们看看调试插件所需的发布内容配置（contributes）部分。

第一个是breakpoints内容配置点，它列出了支持设置断点的语言，没有这个配置点的话，我们就不能在Markdown文件里设置断点了。

第二个是debuggers部分，这里给出了一个调试器，也就是type描述的”mock”。用户可以在选择加载调试配置文件的时候看到这个type。可选的label属性作为type的别称最后会显示在界面上。

既然调试插件用了调试适配器，所以它的相对路径可以在program中定义。为了使插件自包含，应用必须在插件文件夹内。为了方便起见，我们把这个应用所在的文件夹命名为out和bin，不过你想用别的名字也随便。

因为让VS Code运行在不同的平台上，所以我们的调试适配程序也必须支持不同的平台，所以我们有了下列选项：

  1. 如果程序是平台无关的，如：程序需要一个统一的运行时支持，那么你可以通过runtime指定，本项目就是采用了这个方法。到目前为止，VS Code支持node和mono运行时。

  2. 如果实现你的调试适配器需要执行在不同平台，那么program配置可以像下面这样指定：

    1. "debuggers": [{
    2.  "type": "gdb",
    3.  "windows": {
    4.      "program": "./bin/gdbDebug.exe",
    5.  },
    6.  "osx": {
    7.      "program": "./bin/gdbDebug.sh",
    8.  },
    9.  "linux": {
    10.      "program": "./bin/gdbDebug.sh",
    11.  }
    12. }]

  3. 组合上面的两种方式也是可行的。下面是一个Mono Debug适配器，只需要macOs和Linux，而不需要Windows支持。

    1. "debuggers": [{
    2.  "type": "mono",
    3.  "program": "./bin/monoDebug.exe",
    4.  "osx": {
    5.      "runtime": "mono"
    6.  },
    7.  "linux": {
    8.      "runtime": "mono"
    9.  }
    10. }]

configurationAttributes表示这个调试器是支持launch.json配置，开启之后它会校验launch.json。另外这个属性还会启用：编辑启动配置文件时的智能提示和悬浮帮助文本。

initialConfigurations定义了launch.json的初始默认内容。以便于项目不包含launch.json文件时，用户打开调试或者按下调试侧边栏的齿轮按钮后仍能启动调试会话，VS Code会让用户选择一个调试环境，然后生成对应的launch.json：

示例-调试适配器 - 图6

configurationSnippets定义了编辑launch.json启动配置文件的配置补全。方便起见，给调试环境名称加上label前缀以便于补全下拉框出现时能快速地找到我们的目标。

variables字段将”variables”绑定到了”commands”，用${command:Xxxx}语法在启动配置中使用这些变量，调试会话启动后这些值会被替换掉。

命令是在插件中实现的，它可既可以提供简单的无界面实现，也可以通过插件API提供界面中的复杂功能点。Mock Debug将AskForProgramName变量绑定到extension.mock-debug.getProgramName命令上。这个命令的实现在src/extension.ts中，让用户用showInputBox输入程序的名称。

  1. vscode.commands.registerCommand('extension.mock-debug.getProgramName', config => {
  2.     return vscode.window.showInputBox({
  3.         placeHolder: "Please enter the name of a markdown file in the workspace folder",
  4.         value: "readme.md"
  5.     });
  6. });

这个变量可以用${command:AskForProgramName}形式注入到任何加载配置允许字符串类型的地方。

使用DebugConfigurationProvider

如果package.json中的静态调试发布配置内容不够，那DebugConfigurationProvider就派上用场了，它能动态控制调试插件的下列内容：

  • 动态生成launch.json中的debug配置，例如：基于一些工作区可用的上下文信息。
  • 启动新的调试会话前“解析”加载配置，比如根据工作区的一些信息填充默认值。
  • 动态计算调试适配器的可执行路径或者其他命令行参数。

src/extension.ts中的MockConfigurationProvider实现了resolveDebugConfiguration，如果Markdown文件打开而启动调试会话后检测是否有launch.json文件存在。这是一个非常典型的用户场景，用户在编辑器内打开了文件，想要调试的时候却发现没有launch.json文件。

vscode.debug.registerDebugConfigurationProvider是一个调试供应器（debug configuration provider）注册的特殊调试类型，一般出现在activate函数中。为了确保DebugConfigurationProvider尽早注册，插件必须在调试功能启动之前就激活，我们可以在package.json的onDebug事件中配置插件激活事件：

  1. "activationEvents": [
  2.     "onDebug",
  3.     // ...
  4. ],

这个总的onDebug事件在调试功能一启动就会被调用。如果插件的启动开销不大（如：启动时不要花太多时间）那就会运行正常。如果调试插件的启动开销很大（如：启动一个语言服务器），那么onDebug激活事件就会对其他调试插件产生负面影响了，因为它只想尽早启动，而不会把其他类型的调试器考虑在内。

对于高开销调试插件的更好办法是用粒度更细的激活事件：

  • onDebugInitialConfigurations：在DebugConfigurationProvider的provideDebugConfigurations调用前触发。
  • onDebugResolve:type：在DebugConfigurationProvider的resolveDebugConfiguration调用前触发。

!> 首要准则：如果插件的开销不大，就用onDebug。如果插件的开销比较高，根据DebugConfigurationProvider是否调用provideDebugConfigurations或resolveDebugConfiguration，在对应的onDebugInitialConfigurations或者onDebugResolve中处理。

发布你的调试适配器

通过下面的步骤将你的调试适配器发布到市场上：

  • 更新package.json中的发布配置内容表明你调试适配器的功能和目标
  • 根据分享插件部分把你的插件上传到市场上

可选方案：开发一个调试插件

开发调试插件一般既包含插件，也包含调试器和调试适配器这两个平行session。就如上面解释的，VS Code对一点支持非常友好，不过如果想要开发得更容易的话，还是把插件和调试适配器放在一个程序里，用一个会话启动更方便些。

当你在使用Typescript/Javascript实现调试适配器的时候会更容易。

基本的思路是在DebugConfigurationProvider的resolveDebugConfiguration方法中拦截调试会话的加载，然后对连接请求就行侦听，对每一个请求创建新的调试适配器会话。为了确保VS Code使用连接请求（而不是总是加载新的调试适配器），可以修改加载配置，加上debugServer。

这是几行Mock Debug项目实现的这个方法的代码

通过将编译时间标识EMBED_DEBUG_ADAPTER设置为true启用这个特性。现在如果你用F5启动调试，你不仅仅可以插件中打断点了，调试器适配器里也同样可以。