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)

Erich Gamma 2021-05-06 09:01:52 +02:00
parent 44ebdcdc1c
commit 7e2d9d7b95
1 changed files with 16 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
Virtual-Workspaces.md

@ -2,12 +2,12 @@
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. 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__.
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__.
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.
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.
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 is for extension authors and documents how an extension can fully support a virtual workspace or, if it can't, how it can signal that it should be disabled when a virtual workspace is opened.
## Is my extension affected?
@ -17,26 +17,26 @@ Extension with code, that means extensions that define a 'main' entry point, req
## 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.
Run the **Open Remote Repository...** command from the Command Palette. **Notice** this command is currently only available in the [VS Code Insiders](https://code.visualstudio.com/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 where all resources are all based on virtual resources.
This opens a VSCode window for a virtual workspace where all resources are virtual.
## Verify that the code is ready for virtual resources
The API support for virtual file system has been around for quite a while already. 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 is registered a new URI scheme and URIs with that scheme can then be used to represent resources.
The API support for virtual file system has been around for quite a while already. 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 registered a new URI scheme and URIs with that scheme can then be used to represent resources.
Resource URIs are used all over the place in the VS Code API
Resource URIs are used all over in the VS Code API
- An extension should never assume that the URI scheme is 'file'. `URI.fsPath` must only be used when the URI scheme is file.
- Look out 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.
- An extension must never assume that the URI scheme is 'file'. `URI.fsPath` must 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 delegate to 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)
- If you run executable and tasks, check whether they make sense to have these in a virtual workspace window or should rather be disabled.
- If you run executables and tasks from commands, check whether these commands make sense in a virtual workspace window or whether they should better be disabled.
## Adopt your extension for virtualWorkspaces
To know which extensions have already be tested and adopted, we have introduced a new property to `package.json`:
We have introduced a new property for `package.json` to declare whether an extension supports virtualWorkspaces:
The `virtualWorkspaces` capability property in `package.json` signals whether the extension works with virtual workspace, or not
The `virtualWorkspaces` capability property in `package.json` signals whether the extension works with virtual workspace, or not. The example below declares that an extension does not support virtualWorkspaces and should not be activated by VS Code in this setup.
```json
{
"capabilities": {
@ -44,9 +44,8 @@ The `virtualWorkspaces` capability property in `package.json` signals whether th
}
}
```
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 partially work with virtual workspaces, the it should define `"virtualWorkspaces": true` but disable some functionality when a virtual workspace is opened.
When an extension can partially work with virtual workspaces, then it should define `"virtualWorkspaces": true` but it should disable the features that are not supported in a virtual workspace.
## Disable functionality when a virtual workspace is opened
@ -54,7 +53,7 @@ When an extension can partially work with virtual workspaces, the it should defi
One way to disable functionality when a virtual workspace is opened is to use the `virtualWorkspace` context key in `when` clauses of contributions for menus and views.
The `virtualWorkspace` context key is set when all workspace folders are located on virtual file systems.
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": {
@ -67,7 +66,7 @@ The `virtualWorkspace` context key is set when all workspace folders are located
}
```
The 'resourceScheme` context keys matches the URI scheme of the currently selected entry in the explorer or open editor.
Another way is to use the 'resourceScheme` context keys. They match the URI scheme of the currently selected element in the explorer or the element open in the editor.
```
{
"menus": {
@ -83,7 +82,7 @@ The 'resourceScheme` context keys matches the URI scheme of the currently select
### Detect virtual workspaces in code
To check in code whether the current workspace consists of non-`file` schemes use
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');
@ -91,7 +90,7 @@ const isVirtualWorkspace = workspace.workspaceFolders && workspace.workspaceFold
### Language selectors
When registering a provider for a language feature (e.g. completions, hovers, code actions..) specify the scheme(s) you support:
When registering a provider for a language feature (e.g. completions, hovers, code actions..) make sure to specify the scheme(s) you actually support:
```
return vscode.languages.registerCompletionItemProvider({ language: 'typescript', scheme: 'file' }, {