Virtual Workspaces

Extension Author Guide for Supporting Virtual Workspaces

We have recently announced the Remote Repository feature that lets you browse and edit files and folders directly on GitHub.

While developing and testing the feature, we have observed that not all extensions work well with it. What's special about Remote Repositories is that they open VSCode on a folder or workspace that is located on a virtual file system. We call this a virtual workspace.

When a virtual workspace is open in a VS Code window, this is shown by a label in the remote indicator in the lower left corner, similar to remote windows. In that window, we disable all extension that signal that they don't support virtual workspaces.

We want to make sure as many extensions as possible work with virtual resources. We aim for a good user experience not just with the Remote Repository feature, but also all other features leveraging virtual resources, from connecting to ftp-servers to working with cloud resources. Features that depend on resources being available on disk should not cause error dialogs.

Is my extension affected?

When a extension has no code but is a pure theme, keybinding, snippets, grammar extension, then it can run in a virtual workspace and no adoption is necessary.

Extension with code, that means extensions that define a main entry point, require inspection and, possibly, adoption.

Run your extension against a virtual workspace

Run the Open Remote Repository... command from the Command Palette. Notice this command is currently only available in the VS Code Insiders version. The command shows a quick pick dialog and you can paste in any GitHub URL, or choose to search for a specific repository or pull request.

This opens a VSCode window for a virtual workspace where all resources are virtual.

Review that the code is ready for virtual resources

The API support for virtual file system has already been around for quite a while. You can check out the file system provider API, if you are interested. A file system provider is registered for a new URI scheme (e.g. vscode-vfs) and resources on that file system will be represented by URIs using that schema (e.g. vscode-vfs://github/microsoft/vscode)

Check how your extension deals with URIs it gets from the VSCode APIs:

• Never assume that the URI scheme is 'file'. URI.fsPath can only be used when the URI scheme is file.
• Look out for usages of the fs node module for file system operations. If possible, use the vscode.workspace.fs API, which delegates to the responsible file system provider.
• Check for third party components that depend on a fs access (e.g. a language server or a node module)
• If you run executables and tasks from commands, check whether these commands make sense in a virtual workspace window or whether they should be disabled.

Signal whether your extension can handle virtual workspaces

There's a new capabilities property in package.json, and virtualWorkspaces is used to signal whether an extension works with virtual workspace, or not.

The example below declares that an extension does not support virtual workspaces and should not be activated by VS Code in this setup.

{
  "capabilities": {
    "virtualWorkspaces": false
  }
}

When an extension works with virtual workspaces, then it should define "virtualWorkspaces": true. If it partially works, it should do the same, but it should disable the features that are not supported in a virtual workspace.

Until extensions have adopted the new capability, we came up with an internal list of extensions that we think should be disabled in virtual workspaces. The list can be found here.

Of course, extension authors are in better position to make this decision. Once a extension has adopted the capability, we will remove the extension from the list.

Disable functionality when a virtual workspace is opened

Disable command and view contributions

The availability of commands and views and many other contributions can be controlled through context keys in when clauses.

The virtualWorkspace context key is set when all workspace folders are located on virtual file systems. The example below shows the command npm.publish in the command palette only when not in a virtual workspace:

{
    "menus": {
      "commandPalette": [
        {
          "command": "npm.publish",
          "when": "!virtualWorkspace"
        }
      ]
    }
}

The resourceScheme context key is set to the URI scheme of the currently selected element in the explorer or the element open in the editor. In this example the npm.runSelectedScript command is only in the editor context menu if the underlying resource is on the local disk.

{
    "menus": {
      "editor/context": [
        {
          "command": "npm.runSelectedScript",
          "when": "resourceFilename == 'package.json' && resourceScheme == file"
        }
      ]
    }
}

Detect virtual workspaces in code

To check in code whether the current workspace consists of non-file schemes and is virtual you can use

const isVirtualWorkspace = workspace.workspaceFolders && workspace.workspaceFolders.every(f => f.uri.scheme !== 'file');

Language selectors

When registering a provider for a language feature (e.g. completions, hovers, code actions..) make sure to specify the schemes the provider supports:

return vscode.languages.registerCompletionItemProvider({ language: 'typescript', scheme: 'file' }, {
	provideCompletionItems(document, position, token) {
		// ...
	}
});

More information and feedback

Please comment in the Virtual Workspaces Tracking Issue if you have questions and suggestions.