Vscode: Help extensions adopt `asWebviewUri`

[mjbvz]

Background

Back when webviews first shipped with VS Code, we used vscode-resource: uris to load local resources. For example:

<img src="vscode-resource:/Users/matb/path/to/cats.gif">

The vscode-resource format however has a few important issues:

• It does not specify the scheme used to load the resources.

  This prevents vscode-resrouce from being used to read resources from custom VS Code file systems.

• vscode-resource: does not work on web.

  VS Code has to rewrite vscode-resource uris. This rewriting is not complete.

• vscode-resource will also not work with new builds of VS Code that that replace vscode-resource with a new protocol: #97777

  We again have to rewrite uris.

To fix these issues, a while back we introduced the Webview.asWebviewUri helper function. This function takes a local uri and returns a uri that can be used inside a webview to load that resource.

However a number of extensions are still using hardcoded vscode-resoruce: uris. We have already added a warning if you use vscode-resource:: https://github.com/microsoft/vscode/issues/81685

Fix

If your extension is using vscode-resource: to load resources—scripts, css, images, ...—switch to instead use the Webview.asWebviewUri function.

If your extension is using vscode-resource: in a content security policy, replace vscode-resource: with Webview.cspSource

Make sure your code always calls asWebviewUri and cspSource when generating html. These values may change between VS Code version, so it is import that you do not cache these values

If you see issues after making these changes, please file a new issue against VS Code and I'll take a look.

[RandomFractals]

wow @mjbvz I see you had a busy Friday night :)

I wonder if it's time we create webview channel in vscode ext. devs slack for you to join and make major announcements on these api changes to keep us in the loop, or some email subscription list.

There must be a better way to do this without so much effort on your part in addition to resolving those issues on vscode api's end.

In any case, I appreciate you looking into this and updating us with a recipe to fix it. Thanks!

[dzhavat]

Appreciate that you took the time to notify so many extensions.

I just looked at the API and found out that asWebviewUri and cspSource were introduced to stable in v1.38. Hopefully that will be helpful for other authors when planning for update.

[mjbvz]

@dzhavat Yes sorry I got the year wrong when writing the message.

To clarify, here's what is required to get asWebveiwUri to show up as a known API while writing your extension:

If your extension gets vscode.d.ts from the vscode package

• In your package.json set: "engines": { "vscode": "^1.38" }
• Run npm install again (or just the post install script so that the vscode package pulls in new typings)

If your extension gets vscode.d.ts from the @types/vscode package

• In your package.json set: "engines": { "vscode": "^1.38" }
• Also update: "@types/vscode": "^1.38"
• Run npm install again to pull in the new vscode.d.ts

In both cases, you should be able to safely update your extension to require VS Code 1.38+ without leaving many users behind. A very high percentage of VS Code users are on either current stable release or the previous release. We on VS Code also only support current release

[alefragnani]

Hi @mjbvz ,

Just out of curiosity, is there any ETA for #97777 to be released?

I mean, the PR itself has no milestone assigned, an the issue which it fixes (#89038) is still on Backlog.

Thank you

[mjbvz]

Closing this issue since there's not much more to do from the VS Code side.

All of our examples and documentation should now be using asWebviewUri. Additionally using an old style URI in a webview will generate a warning