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.