microsoft/vscode
1
0
Fork 0
mirror of https://github.com/microsoft/vscode.git synced 2025-12-10 14:16:15 -06:00
Code Issues Packages Projects Releases 177 Wiki Activity

Updated Virtual Workspaces (markdown)

Martin Aeschlimann 2021-05-05 06:47:25 -07:00
parent c60f64cf07
commit 4bc5584268
1 changed files with 30 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
Virtual-Workspaces.md

@ -1,20 +1,43 @@
# [WIP] Extension Author Guide for Supporting Virtual Workspaces
The VS Code extension API allows extension to define a virtual file system by providing a [file system provider](https://github.com/microsoft/vscode/blob/dc8bd9cd7e5231745549ac6218266c63271f48cd/src/vs/vscode.d.ts#L7038) for a URI scheme. By opening VSCode a such a folder, users can work with the virtual resource the same way as with local files and folder.
We have recently released 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.
An example for this is the built-in __Remote Repository__ extension that lets you browse and edit files and folders directly on GitHub.
What's special about the new feature is that it opens VSCode on a folder or workspace that is located on a virtual file system. We call this a __virtual workspace__.
We indicate that VSCode is opened on a virtual workspace by showing a label in the remote indicator in the lower left corner, similar to remote windows.
When VSCode is opened on a virtual folder, or multiple virtual folders, we call this a __virtual workspace__.
We want to make sure as many extensions as possible work with virtual res, providing a great user experience not just with the the __Remote Repository__ feature, but also all other similar features, from connecting to ftp-servers to working with cloud resources.
The virtual file system feature has existed since a while. However, we have observed that not all extensions can work with resources that are not file based.
This guide is for extension authors and documents how an extension can support a virtual workspace or, if it can't, how it can signal that it should be disabled when a virtual workspace is opened.
This guide documents how an extension can support a virtual workspace or, if it can't, how it can signal that it should be deactivated when a virtual workspace is opened.
## 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.
As a result, the extension should set the new `virtualWorkspaces` capability property in `package.json` to signal whether it works with virtual workspace, or not
## Run your extension against a virtual workspace
Run the **Open Remote Repository...** command from the Command Palette. From there, you can paste in any GitHub URL, or choose to search for a specific repository or pull request.
Resources shown in the explorer and editors opened are now all based on virtual resources.
## Verify that the code is ready for virtual resources
The API support for virtual file system is nothing new and has been around for quite a while. You can check out the (file system provider API)[https://github.com/microsoft/vscode/blob/dc8bd9cd7e5231745549ac6218266c63271f48cd/src/vs/vscode.d.ts#L7038] if you are interested. A file system provider can be registered for a custom URI scheme.
The VS Code API represents resources such as files, folders with resource URIs which now can also be of this new scheme.
- An extension should never assume that the URI scheme is 'file'. `URI.fsPath` should only be used when the URI scheme is file.
- Look our for usages of the `fs` node module for file system operation. If possible, use the `vscode.workspace.fs` API, which will make use of the custom file system provider.
- Check for third party components that depend on a fs access (e.g. a language server or a node module).
## Adopt your extension is ready for virtualWorkspaces
To know which extensions have already be tested and adopted, we have added a new property to `package.json`.
The `virtualWorkspaces` capability property in `package.json` signals whether the extension works with virtual workspace, or not
```json
{
"capabilities": {
@ -24,11 +47,7 @@ As a result, the extension should set the new `virtualWorkspaces` capability pro
```
When an extension can not work with virtual workspaces, it will be disabled by VS Code when a virtual workspace is opened.
When an extension can only partially work with virtual workspaces, the it should define `"virtualWorkspaces": true` but disable some functionality when a virtual workspace is opened.
## Test your extension against a virtual workspace
run the **Open Remote Repository...** command from the Command Palette. From there, you can paste in any GitHub URL, or choose to search for a specific repository or pull request.
When an extension can partially work with virtual workspaces, the it should define `"virtualWorkspaces": true` but disable some functionality when a virtual workspace is opened.
## Disable functionality when a virtual workspace is opened
@ -52,11 +71,3 @@ A second way is to check in code whether the current workspace consists of non-`
```
const isVirtualWorkspace = workspace.workspaceFolders && workspace.workspaceFolders.every(f => f.uri.scheme !== 'file');
```
## Verify that the code is ready for virtual resources
The VS Code API represents resources such as files, folders with resource URIs.
- An extension should never assume that the URI scheme is 'file'. `URI.fsPath` should only be used when the URI scheme is file.
- Instead of using the `fs` node module, use the `vscode.workspace.fs` API in VS Code
- Check for third party components that depend on a fs access (e.g. a language server or a node module)