Visual Studio Code - NEW FEATURES: 14 Extension Authoring Improvements (API Consumption, Quick Pick, Octicons, Virtual Documents, Test Suite for Debug Adapters, JSON Mode Extension, & More!)

  • Article

The Visual Studio Code 0.10.8 release features a palpable plethora of improvements, including...

Extension Authoring

API Consumption

When you write an extension for VS Code, you are developing it against a set of APIs that we define through a file called vscode.d.ts. You can see this file in our repository here. This file is picked up from our TypeScript and JavaScript language service to provide you with rich validation and IntelliSense while you develop your extension.

As we make changes to the VS Code API between versions, vscode.d.ts changes and is updated and tagged from release to release. Previously, we stored the vscode.d.ts file within the vscode npm module that all extensions automatically depend on. So to update to our latest API, you would just install a newer version of the vscode npm module in your extension by typing npm update vscode.

We found that this approach has many issues:

  • The vscode npm module needs to be updated and versioned independent from VS Code versions because it contains API unrelated code (e.g. for test running)
  • The engine field of the package.json in your extension should be the only place that drives the decision which API to develop against.

To solve these issues, we made the following changes:

  • The vscode.d.ts is no longer shipping within the vscode npm module.
  • The value of the engine field in your extension is used to determine which version of vscode.d.ts to use.
  • It is still very easy to update to a newer API via basic npm commands.

Since this is a breaking change for existing extensions, we increased the vscode npm module version to 0.11.0. We encourage all extension writers to update their devDependency to vscode in their package.json to this new version (^0.11.x) to benefit from future updates to tooling for extensions.

The process of installing a specific version of the API into your extension is still very simple:

  • Set the minimal version of VS Code that your extension requires in the engine field of the package.json. For example, when you want to upgrade to the 0.10.8 version of the VS Code API then define
  "engines": { "vscode": "^0.10.7" }
  • Make sure your devDependency for the vscode module is at least 0.11.0.
  • Add a postinstall script to your package.json like this:
 "scripts": { "postinstall": "node ./node_modules/vscode/bin/install" }
  • Type npm install from the root of your extension.
  • The vscode module will download the appropriate version of vscode.d.ts based on the version in  engines field you declared in the package.json.
  • Go back to VS Code and see how the API for the specific version you chose appears in IntelliSense and validation.

Extension API additions

We added a few new APIs to enable writing even more awesome extensions.

Quick Pick and Input

You can now validate user input, get called when an item is focused in Quick Pick, and Quick Pick now has room for additional details. Also Quick Pick now supports GitHub Octicons like the Status Bar.

Virtual Documents

We have introduced the concept of virtual documents. These are textual documents that don't have a representation on disk, but are generated at runtime. For example, HTML generated from Markdown or source code from debug symbols.

virtual document

Combine virtual documents with the new vscode.previewHtml command and you can come up with some creative experiences.

New Extension APIs

  • There is now support for glob-patterns when associating files with a language.
  • You can determine the current editor ViewColumn.
  • There is a new MarkedString to display Markdown content in various UI elements.

Debug Protocol Changes

We have changed the debug protocol in the following (backward compatible) ways:

  • Feature negotiation: the response of the InitializeRequest now returns information about the capabilities of the debug adapter. The VS Code debugger uses this information to enable or configure features which only exist for certain debug adapters.
  • New request ConfigurationDoneRequest: VS Code sends this request to indicate that the configuration (e.g. registering stored breakpoints and exception options) of the debug session has finished and that debugging is about to start. For backward compatibility, VS Code will send this request only if the debug adapter returns a value of true for the supportsConfigurationDoneRequest capability.
  • Additional attributes for Sourcetype:
    • an optional origin attribute to provide additional information about the source in the debug UI.
    • an optional adapterData attribute that the VS Code debug UI will transparently persist for breakpoints.
  • New type SourceBreakpoint: an array of SourceBreakpoint is an alternate means to specify the individual breakpoints for the SetBreakpointsRequest. The SourceBreakpoint allows for specifying column and condition information for a breakpoint (in addition to the line).

Test Suite for Debug Adapters

With the January release, we've started to simplify the process of writing automated tests for a debug adapter. The basic idea is to provide a toolkit with Promise-based building blocks for individual protocol requests (e.g. stepInRequest) and for common request sequences (e.g. hitBreakpoint). These building blocks can be easily configured for a specific adapter and combined to form complex scenarios.

Here are three example Mocha tests:

 var dc: DebugClient = ...; test('should run program to the end', () => { return Promise.all([ dc.configurationSequence(), dc.launch({ program: "main.js" }), dc.waitForEvent('terminated') ]); }); test('should stop on entry', () => { return Promise.all([ dc.configurationSequence(), dc.launch({ program: "main.js", stopOnEntry: true }), dc.assertStoppedLocation('entry', 1) ]); }); test('should set a breakpoint and stop on it', () => { return dc.hitBreakpoint({ program: "main.js" }, "test.js", 15); });

More examples can be found in these debug adapter projects on GitHub:

You can see the Promise-based API in DebugClient.ts and an initial set of tests in adapter.test.ts. We plan to make this API available as an npm module in February.

JSON mode is now an extension

From a user's perspective, nothing has really changed when editing JSON, but under the hood, the JSON language support has been refactored. JSON language support drives the smartness when editing JSON files, from validation based on schemes to code completion and formatting. JSON is now a regular extension, using the same VS Code extension APIs as everyone else. The implementation is based on the language server infrastructure, which makes it easy to run in a separate process. Read here for more on the language server.

Notable Bug Fix

  • 69: Proxy support for extension gallery

   

      

      

Check out all the new features and update to Visual Studio Code v0.10.9:

https://code.visualstudio.com/updates

 

   

Thanks for stopping. Bye!

   - Ninja Ed