The vscode:// url scheme usage is not documented

[adriancuadrado]

I asked a question in stack overflow to learn more about how to use vscode:// and what endpoints and parameters are available, but I got no aswers for a long time and I am going to assume that this is not documented at all.

[adriancuadrado]

In the product.json file that you can find in the VSCode's source file you can find a property called urlProtocol. This property is used to tell VSCode what the name of the protocol that urls must have is to have the web browser ask you if you want to open such urls with VSCode. However, you will see that it's value is code-oss instead of vscode as you would expect. This is because when VSCode is released, according to what chrisdias said in this comment, microsoft uses a different product.json file with their customizations:

Here's how it works. When you build from the vscode repository, you can configure the resulting tool by customizing the product.json file. This file controls things like the Gallery endpoints, “Send-a-Smile” endpoints, telemetry endpoints, logos, names, and more.

When we build Visual Studio Code, we do exactly this. We clone the vscode repository, we lay down a customized product.json that has Microsoft specific functionality (telemetry, gallery, logo, etc.), and then produce a build that we release under our license.

The protocol is accessed from extensions using vscode.env.uriScheme. This is the farthest I could come researching this. I've been trying to understand how the protocol is registered in the Windows registry. This article explains how this is done in general, but I don't see how VSCode does it and how the contents of urls with the vscode:// scheme are passed to VSCode to learn more about all available options.

[donfour]

Bump. I'm particularly looking into how vscode:// can open a vscode extension.

• The interface for the protocol url is defined here (with some inline comments) .
• The actual protocol url seems to be handled in handleProtocolUrl() function here.

I will spend more time researching, but at the moment I'm not able to find any code regarding how a url can open an extension, and how would an extension read information from the url.

Edit: sharing a bit of what I found

The handle uri sample project shows how you can trigger a function in an extension by opening a link in the browser. You basically have to register a handler using registerUriHandler. You also have to make sure that the authority of the url matches your extension ID.

• The authority is the vscode-samples.uri-handler-sample part of vscode://vscode-samples.uri-handler-sample.
• The extension ID comes from your package.json. Make sure you have both publisher and name set, and your extension ID will be {publisher}.{name}.

[tscrypter]

@donfour Good find!

I want to just add that if/when this is documented, I think it would go a long way to cover how to debug this handler logic while developing an extension. I'm currently dealing with a headache of the handler not being executed inside the extension shell because it's triggering either code-url-handler or code-insiders-handler.

I'm getting most of the information that I can out with a lot of console.log statements, but I'm attempting to use this as a callback endpoint for an OAuth 2.0 flow to acquire a token for my extension to access an external API.

[mlhiter]

Bump. I'm particularly looking into how vscode:// can open a vscode extension.撞。我特别研究vscode://如何打开 vscode 扩展。

• The interface for the protocol url is defined here (with some inline comments) .协议 url 的接口在此处定义（带有一些内联注释）。
• The actual protocol url seems to be handled in handleProtocolUrl() function here.实际的协议url似乎是在handleProtocolUrl()函数中处理的。

I will spend more time researching, but at the moment I'm not able to find any code regarding how a url can open an extension, and how would an extension read information from the url.我会花更多时间研究，但目前我无法找到任何有关 url 如何打开扩展程序以及扩展程序如何从 url 读取信息的代码。

Edit: sharing a bit of what I found

编辑：分享一些我发现的东西
The handle uri sample project shows how you can trigger a function in an extension by opening a link in the browser. You basically have to register a handler using registerUriHandler. You also have to make sure that the authority of the url matches your extension ID.处理 uri 示例项目展示了如何通过在浏览器中打开链接来触发扩展中的功能。您基本上必须使用registerUriHandler注册处理程序。您还必须确保 url 的权限与您的扩展 ID 匹配。

• The authority is the vscode-samples.uri-handler-sample part of vscode://vscode-samples.uri-handler-sample.权威机构是 vscode-samples.uri-handler-sample 的一部分 vscode://vscode-samples.uri-handler-sample 。
• The extension ID comes from your package.json. Make sure you have both publisher and name set, and your extension ID will be {publisher}.{name}.扩展 ID 来自您的package.json 。确保您设置了publisher和name ，并且您的扩展 ID 将为{publisher}.{name} 。

can we use special version of plugin?

[adriancuadrado]

@mlhiter

Bump. I'm particularly looking into how vscode:// can open a vscode extension.撞。我特别研究vscode://如何打开 vscode 扩展。

• The interface for the protocol url is defined here (with some inline comments) .协议 url 的接口在此处定义（带有一些内联注释）。
• The actual protocol url seems to be handled in handleProtocolUrl() function here.实际的协议url似乎是在handleProtocolUrl()函数中处理的。

I will spend more time researching, but at the moment I'm not able to find any code regarding how a url can open an extension, and how would an extension read information from the url.我会花更多时间研究，但目前我无法找到任何有关 url 如何打开扩展程序以及扩展程序如何从 url 读取信息的代码。

Edit: sharing a bit of what I found

编辑：分享一些我发现的东西
The handle uri sample project shows how you can trigger a function in an extension by opening a link in the browser. You basically have to register a handler using registerUriHandler. You also have to make sure that the authority of the url matches your extension ID.处理 uri 示例项目展示了如何通过在浏览器中打开链接来触发扩展中的功能。您基本上必须使用registerUriHandler注册处理程序。您还必须确保 url 的权限与您的扩展 ID 匹配。

• The authority is the vscode-samples.uri-handler-sample part of vscode://vscode-samples.uri-handler-sample.权威机构是 vscode-samples.uri-handler-sample 的一部分 vscode://vscode-samples.uri-handler-sample 。
• The extension ID comes from your package.json. Make sure you have both publisher and name set, and your extension ID will be {publisher}.{name}.扩展 ID 来自您的package.json 。确保您设置了publisher和name ，并且您的扩展 ID 将为{publisher}.{name} 。

can we use special version of plugin?

Why did you translate @donfour 's answer to chinese? (assuming it's chinese because that's what the characters look like, but I don't really know).

[mlhiter]

@mlhiter

Bump. I'm particularly looking into how vscode:// can open a vscode extension.撞。我特别研究vscode://如何打开 vscode 扩展。

• The interface for the protocol url is defined here (with some inline comments) .协议 url 的接口在此处定义（带有一些内联注释）。
• The actual protocol url seems to be handled in handleProtocolUrl() function here.实际的协议url似乎是在handleProtocolUrl()函数中处理的。

I will spend more time researching, but at the moment I'm not able to find any code regarding how a url can open an extension, and how would an extension read information from the url.我会花更多时间研究，但目前我无法找到任何有关 url 如何打开扩展程序以及扩展程序如何从 url 读取信息的代码。

Edit: sharing a bit of what I found

编辑：分享一些我发现的东西
The handle uri sample project shows how you can trigger a function in an extension by opening a link in the browser. You basically have to register a handler using registerUriHandler. You also have to make sure that the authority of the url matches your extension ID.处理 uri 示例项目展示了如何通过在浏览器中打开链接来触发扩展中的功能。您基本上必须使用registerUriHandler注册处理程序。您还必须确保 url 的权限与您的扩展 ID 匹配。

• The authority is the vscode-samples.uri-handler-sample part of vscode://vscode-samples.uri-handler-sample.权威机构是 vscode-samples.uri-handler-sample 的一部分 vscode://vscode-samples.uri-handler-sample 。
• The extension ID comes from your package.json. Make sure you have both publisher and name set, and your extension ID will be {publisher}.{name}.扩展 ID 来自您的package.json 。确保您设置了publisher和name ，并且您的扩展 ID 将为{publisher}.{name} 。

can we use special version of plugin?

Why did you translate @donfour 's answer to chinese? (assuming it's chinese because that's what the characters look like, but I don't really know).

I'm sorry, this is caused by my Chrome translation extension, I didn't notice, hahaha

[starball5]

I mean, there's some. Maybe not exactly what you're talking about though.

• https://code.visualstudio.com/docs/editor/command-line#_opening-vs-code-with-urls
• https://code.visualstudio.com/docs/remote/troubleshooting#_connect-to-a-remote-host-from-the-terminal

[PRO-2684]

Here's a list of URL schemes I've found:

Open a project or file

Ref: Opening VS Code with URLs - VSCode Documentation

• Open a project
  • vscode://file/{full-path-to-project}/
  • e.g. vscode://file/c:/myProject/
• Open a file
  • vscode://file/{full-path-to-file}
  • e.g. vscode://file/c:/myProject/package.json
• Open a file to line and column
  • vscode://file/{full-path-to-file}:{line}:{column}
  • e.g. vscode://file/c:/myProject/package.json:5:10

Open settings

Ref: Opening VS Code with URLs - VSCode Documentation

• vscode://settings/{setting-id}
• e.g. vscode://settings/editor.wordWrap

Open extensions

Inspect: Try installing any extension from Visual Studio Marketplace

• vscode:extension/{extension-id}
• e.g. vscode:extension/ms-vscode.cpptools

Extension registered URIs

Ref: What options are available to use with the vscode:// url scheme? - Stack Overflow

• vscode://{extension-id}/...
• e.g. vscode://vscode.git/clone?url=https://github.com/microsoft/vscode.git

[z-aki]

Is ~ supported?

vscode://file/~/foo.txt

The support was added long back..
microsoft/vscode#39122