Track Virtual Workspace Support for Extension Authors

[aeschli]

This issue tracks progress on the Virtual Workspace Support for Extension Authors and helps with the adoption.

• Read the Virtual Workspace Extension Author Guide.
• Post questions and requests is this issue.
• Subscribe this issue and check back. We post here if new information is added to the guide.

[DanTup]

I have a question about the general expectation for language support in this feature. It seems like there are two possible routes:

1. Language servers only operate on the file content they know about (eg. in the case of LSP, files that have been opened and the server notified of their contents)
2. Language servers "crawl" files as necessary (via VS Code) to analyze the whole project/workspace (or at least, the things reachable from the open file(s))

It's not very clear from the published info which of these is the goal. The first one seems like it will result in a poor experience (for example, code completion or analysis won't work for anything imported from other files that haven't been opened). The second seems like it would just be a worse version of cloning the repo locally and then opening that (because everything would be slower, and running/debugging won't work).

Knowing what the user expectations will generally be in these workspaces would definitely help understand the best direction for language support. Thanks!

[jakebailey]

This got mass posted to us, but for Pylance, we can't really make use of this because the VS Code FS abstractions are not a part of the LSP; this sort of makes this feature problematic in the same way that remote SSH filesystems and such break. Given the proliferation of LSs, I'm not sure how well things are going to work without an LSP change to add some sort of VFS API.

[lramos15]

In the hex editor when doing vscode.workspace.fs.stat(uri) on newly created files the size will always be 0. However vscode.workspace.fs.readFile(uri) will return the correct bytes. /cc @kieferrm Who was seeing an issue because of this.

[majastrz]

For Bicep, it's the same as Pylance. We rely heavily on our language server, so we would have to be disabled or run with almost no functionality outside of the TextMate grammar.

[tamuratak]

LSP and the virtual workspace are related to

• 123025

• microsoft/language-server-protocol/issues/336

[alefragnani]

I have asked this on the issue that was opened on my repo, but maybe this could be useful for other extension developers too.

I miss the information (on that Author Guide) if I also need to update the engine entry on package.json. I guess no, but if yes, to which value (1.56 or 1.57 for to be in the Insiders).

I didn't have to do anything to the extension properly activate while connected to some Virtual Workspace (while debugging) but I'm asking this because I'm worried if, for any reason, I update the extension to support Virtual Workspaces (adding that capabilities entry to package.json) but the user remains with older releases of VS Code (prior to 1.56), which does not recognizes that, and the extension does not activate for any reason.

Thank you

[aeschli]

What are the expectations for language support with virtual workspaces?

Limited functionality is fine. The language extensions that ship with VSCode (TypeScript, JSON, CSS, HTML) just look at the open text document ('single file only').

[aeschli]

@alefragnani Updating the engine is not necessary, unless you also use new VSCode API from vscode.d.ts.

[DanTup]

@aeschli

Limited functionality is fine. The language extensions that ship with VSCode (TypeScript, JSON, CSS, HTML) just look at the open text document ('single file only').

Is it likely they will remain that way or is this just an intermediate step? There's a comment at https://github.com/microsoft/vscode/issues/123025#issuecomment-836587174 suggesting LSP is getting virtual-FS support, so I'm still fairly confused which direction to take (I think the implementations of this would be quite different depending on whether it should use a full virtual filesystem versus just working on simple overlays/buffers for the existing open files so it's helpful to know how VS Code is present this to users).

I presume the single-file TS support won't have access to anything in node_modules, so most symbols will just be any and get no analysis/completion? This seems like a poor experience, but then, proxying the filesystem through the client over to GitHub also seems like it would be a poor experience.

[DavidAnson]

Similar to the LSP scenario above, what's the expectation for a linting tool in this context? The "single file only" model proposed above is convenient (and now works in a private branch for markdownlint), but that means any custom linting configuration won't be applied and the resulting warnings will be inconsistent vs. when opening the same file from the file system. For example, imagine ESLint requiring trailing semicolons or forbidding them depending on whether a file is virtual or not. The rules for loading configuration may be complex (i.e., not just a single file in the workspace root and possibly hierarchical), so scanning the virtual file system may not be practical.

What's the intended behavior? Will users be conditioned to expect that everything (language extensions, linting, etc.) is always a little wonky when using the virtual file system? Or will they consider such behavior bugs such that extensions end up disabling support because it's impractical to match non-virtual behavior?

[aeschli]

Is it likely they will remain that way or is this just an intermediate step?

We anticipate that only few language extensions will be able to work fully on a virtual file system. Most languages and language extensions use libraries and tools that do not have an abstraction of a file system and depend on synchronous file accesses. That's regardless of LSP adding the support for file systems.

We are looking into UI to signal users, that on this workspace some extensions are deactivated or work with limited functionality.

[alefragnani]

Do you have any plans to define a new virtual workspace ready keyword to be used for the Marketplace, just like you did when multi-root was released (https://github.com/microsoft/vscode/wiki/Adopting-Multi-Root-Workspace-APIs).

I would say the same idea could be expanded for the Workspace Trust feature, which is being tracked for extension authors in https://github.com/microsoft/vscode/issues/120251

Thank you

[DanTup]

@aeschli

We anticipate that only few language extensions will be able to work fully on a virtual file system. Most languages and language extensions use libraries and tools that do not have an abstraction of a file system and depend on synchronous file accesses. That's regardless of LSP adding the support for file systems.

Thanks for the clarification - although I'm still a little unsure. For some languages (for example Dart) it might be possible to run entirely from a virtual filesystem but it would involve effort (to support remote and async filesystems). Whether that's worthwhile will depend on how common this scenario is and whether users would expect it.

TypeScript is a good example that's probably fairly similar to Dart (it likely needs lots of info from node_modules to work fully). Is it likely (or is it a goal) that it would ultimately end up fully supported here, or is the intention really just to support simple languages that don't need much information from other files?

Thanks!

[DanTup]

Some additional questions:

1.

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');

Can we run this just at activation, or should we be prepared for this to change within an extension hosts lifetime?

2. Is it possible to have a mixed workspace? I assumed it was (since extensions can register their own FS providers?) but when I joined a Lifeshare session or opened a GitHub repo, I seemed unable to add additional folders (for LiveShare, there is an option, but the "Show Local" button doesn't appear for the file picker, and for GitHub repo I get an input box that says /DanTup/ and anything I type says invalid path).

3. Once a extension has adopted the capability, we will remove the extension from the list.

   Do we need to let you know to remove us from this list, or will you just honour the flag in package.json? (I presume the latter, but otherwise I plan to ship a version of Dart-Code with the flag set to true by the end of the month to allow the extension to activate and provide textmate grammar etc. - although non-local files will (gracefully) not get language support right now).

[aeschli]

@DanTup Yes, of course a local folder could be added, which could turn virtual workspace into a normal workspace. The virtualWorkspace context variable would reflect that too, as well as the label on the remote indicator. In the UI we steer users away from getting a mixed workspaces, but it's of course possible to do (by editing the workspace file, programmatically by extensions). We don't really know what the the use cases for mixed workspaces are. For now we treat these like regular workspaces I think for language extensions, I think it shouldn't matter so much whether we call the workspace virtual or not. Most functionality that a language extension provides has a resource as input (e.g. provide code lenses for a given resource), so I would just look at the scheme of that resource.

The virualWorkspace capability in the package.json wins over the default values derived from the list.

[DanTup]

I think for language extensions, I think it shouldn't matter so much whether we call the workspace virtual or not. Most functionality that a language extension provides has a resource as input

Yep, that makes sense. Here I was just wondering about handling the case where a user has an old Dart SDK (where the LSP server didn't correctly handle non-file URIs) and wanted to warn them if they had a virtual workspace (but wasn't sure if it was safe to only do at startup or it could occur later).

The virtualWorkspace capability in the package.json wins over the default values derived from the list.

Perfect, thanks!

I'm still interested to know what the plan is for TypeScript. Dart is similar in many ways and if TS decides full support is not feasible, I suspect the same would be true for Dart. If TS decides it's possible (which presumably involves sucking node_modules into the server via the client) then that suggests Dart could do similar. It's hard to justify putting too much work into trying to support a virtual filesystem in the language server without some better ideas about the intended direction/expectations of this.

[brettfo]

Are extensions always running with the file: scheme? Specifically, will ExtensionContext.globalStorageUri always be local? If not, what's the guidance for extensions that need to unzip external tools to the local disk and invoke them with child_process.spawn()?

[aeschli]

Yes, the globalStorageUri remains a file uri and you can spawn external tools. Just the workspace resources are virtual, so maybe the spawned tool might not know how to deal with a virtual resource URL.

[alefragnani]

I'm updating an extension to not support virtual workspaces, but it seems the Debug Session does not respect that capabilities flag.

I mean, I added "virtualWorkspaces": false to the capabilities property in package.json, but whenever I run a debug session and connect to some Virtual workspace, the extension remains enabled.

The only way I could test my extension was packaging and installing the .vsix.

Is debugging really not supported, or should I open an issue for you to take a look?

Thank you

[aeschli]

@alefragnani Looks like a bug, please open a separate issue.

[bmewburn]

Is there a particular URI scheme that virtual workspace folders will have?

[alefragnani]

Hi @bmewburn ,

Yep, it is defined as vscode-vfs.

Hope this helps

[aeschli]

vscode-vfs is just the one we use for RemoteHub, but others are possible too. It's everything except file and vscode-remote

[DavidAnson]

@aeschli It would be nice to have the schemes defined in the .d.ts so extensions don’t need to hardcore strings. It would also be nice to have helpers like “isVirtual” for dealing with this. Similarly, a table of behaviors would be instructive - I’m not sure my code handles -vscode-remote correctly as this is the first I’ve seen it.

[alefragnani]

@aeschli , do you have plans/scenarios for other so-called virtual workspaces that are not related to RemoteHub?

I mean, up until Virtual Workspaces came out (last release), I only had to deal with vscode-remote scheme, which is used by Docker, SSH, WSL, and more recently Codespaces. In this case, I'm only talking about the native remotes.

@DavidAnson , Totally agree. Right now I have a few mapped on my extensions for specific scenarios I had to take care, like untitled, search-editor-body, vscode-remote and vscode-vfs.

[aeschli]

vscode-remote you will only see if your extension needs to run on the UI side (extensionKind: 'ui'). By default extensions run on the machine where the workspace is and therefore see only 'file' URIs. Then there are 'untitled' URIs for new, unsaved files. And then there are file system providers that are contributed by extensions and can be many things. We call them all virtual.

[alefragnani]

Just out of curiosity, what was the main reason to create the new vscode-vfs scheme, instead of using vscode-remote with a different authority, like happened with Codespaces?

A lot of recommendations you see in the guide above also applied to remotes, and I guess (based on my extensions at least) if your extension works on remotes ( extensionKind as ui), it may work out of the box with Virtual Workspaces.

Sure, I’m probably not seeing all the complexities under the hood (in fact, I’m pretty sure 😬) , but I was wondering if it wouldn’t make extensions to support it with no changes at all.

Thank you

[aeschli]

The guide now moved to the docs: https://code.visualstudio.com/api/extension-guides/virtual-workspaces

Closing the tracking issue now. Please create an issue if you have any requests on virtual workspaces.