VS Code API

An Event which fires when the authentication sessions of an authentication provider have been added, removed, or changed.

Get an authentication session matching the desired scopes. Rejects if a provider with providerId is not registered, or if the user does not consent to sharing authentication information with the extension. If there are multiple sessions with the same scopes, the user will be shown a quickpick to select which account they would like to use.

Currently, there are only two authentication providers that are contributed from built in extensions to the editor that implement GitHub and Microsoft authentication: their providerId's are 'github' and 'microsoft'.

Get an authentication session matching the desired scopes. Rejects if a provider with providerId is not registered, or if the user does not consent to sharing authentication information with the extension. If there are multiple sessions with the same scopes, the user will be shown a quickpick to select which account they would like to use.

Currently, there are only two authentication providers that are contributed from built in extensions to the editor that implement GitHub and Microsoft authentication: their providerId's are 'github' and 'microsoft'.

Get an authentication session matching the desired scopes. Rejects if a provider with providerId is not registered, or if the user does not consent to sharing authentication information with the extension. If there are multiple sessions with the same scopes, the user will be shown a quickpick to select which account they would like to use.

Currently, there are only two authentication providers that are contributed from built in extensions to the editor that implement GitHub and Microsoft authentication: their providerId's are 'github' and 'microsoft'.

Register an authentication provider.

There can only be one provider per id and an error is being thrown when an id has already been used by another provider. Ids are case-sensitive.

• params - options Additional options for the provider.

Executes the command denoted by the given command identifier.

• Note 1: When executing an editor command not all types are allowed to be passed as arguments. Allowed are the primitive types string, boolean, number, undefined, and null, as well as Position, Range, Uri and Location.
• Note 2: There are no restrictions when executing commands that have been contributed by extensions.

Retrieve the list of all available commands. Commands starting with an underscore are treated as internal commands.

Registers a command that can be invoked via a keyboard shortcut, a menu item, an action, or directly.

Registering a command with an existing command identifier twice will cause an error.

Registers a text editor command that can be invoked via a keyboard shortcut, a menu item, an action, or directly.

Text editor commands are different from ordinary commands as they only execute when there is an active editor when the command is called. Also, the command handler of an editor command has access to the active editor and to an edit-builder. Note that the edit-builder is only valid while the callback executes.

Creates a new comment controller instance.

The currently active debug console. If no debug session is active, output sent to the debug console is not shown.

The currently active debug session or undefined. The active debug session is the one represented by the debug action floating window or the one currently shown in the drop down menu of the debug action floating window. If no debug session is active, the value is undefined.

List of breakpoints.

An Event which fires when the active debug session has changed. Note that the event also fires when the active debug session changes to undefined.

An Event that is emitted when the set of breakpoints is added, removed, or changed.

An Event which fires when a custom DAP event is received from the debug session.

An Event which fires when a new debug session has been started.

An Event which fires when a debug session has terminated.

Add breakpoints.

Converts a "Source" descriptor object received via the Debug Adapter Protocol into a Uri that can be used to load its contents. If the source descriptor is based on a path, a file Uri is returned. If the source descriptor uses a reference number, a specific debug Uri (scheme 'debug') is constructed that requires a corresponding ContentProvider and a running debug session

If the "Source" descriptor has insufficient information for creating the Uri, an error is thrown.

Register a debug adapter descriptor factory for a specific debug type. An extension is only allowed to register a DebugAdapterDescriptorFactory for the debug type(s) defined by the extension. Otherwise an error is thrown. Registering more than one DebugAdapterDescriptorFactory for a debug type results in an error.

Register a debug adapter tracker factory for the given debug type.

Register a debug configuration provider for a specific debug type. The optional triggerKind can be used to specify when the provideDebugConfigurations method of the provider is triggered. Currently two trigger kinds are possible: with the value Initial (or if no trigger kind argument is given) the provideDebugConfigurations method is used to provide the initial debug configurations to be copied into a newly created launch.json. With the trigger kind Dynamic the provideDebugConfigurations method is used to dynamically determine debug configurations to be presented to the user (in addition to the static configurations from the launch.json). Please note that the triggerKind argument only applies to the provideDebugConfigurations method: so the resolveDebugConfiguration methods are not affected at all. Registering a single provider with resolve methods for different trigger kinds, results in the same resolve methods called multiple times. More than one provider can be registered for the same type.

Remove breakpoints.

Start debugging by using either a named launch or named compound configuration, or by directly passing a DebugConfiguration. The named configurations are looked up in '.vscode/launch.json' found in the given folder. Before debugging starts, all unsaved files are saved and the launch configurations are brought up-to-date. Folder specific variables used in the configuration (e.g. '${workspaceFolder}') are resolved against the given folder.

Stop the given debug session or stop all debug sessions if session is omitted.

The hosted location of the application On desktop this is 'desktop' In the web this is the specified embedder i.e. 'github.dev', 'codespaces', or 'web' if the embedder does not provide that information

The application name of the editor, like 'VS Code'.

The application root folder from which the editor is running.

Note that the value is the empty string when running in an environment that has no representation of an application root folder.

The system clipboard.

Indicates that this is a fresh install of the application. true if within the first day of installation otherwise false.

Indicates whether the users has telemetry enabled. Can be observed to determine if the extension should send telemetry.

Represents the preferred user-language, like de-CH, fr, or en-US.

The current log level of the editor.

A unique identifier for the computer.

The name of a remote. Defined by extensions, popular samples are wsl for the Windows Subsystem for Linux or ssh-remote for remotes using a secure shell.

Note that the value is undefined when there is no remote extension host but that the value is defined in all extension hosts (local and remote) in case a remote extension host exists. Use extensionKind to know if a specific extension runs remote or not.

A unique identifier for the current session. Changes each time the editor is started.

The detected default shell for the extension host, this is overridden by the terminal.integrated.defaultProfile setting for the extension host's platform. Note that in environments that do not support a shell the value is the empty string.

The UI kind property indicates from which UI extensions are accessed from. For example, extensions could be accessed from a desktop application or a web browser.

The custom uri scheme the editor registers to in the operating system.

An Event which fires when the log level of the editor changes.

An Event which fires when the user enabled or disables telemetry. true if the user has enabled telemetry or false if the user has disabled telemetry.

Resolves a uri to a form that is accessible externally.

http: or https: scheme

Resolves an external uri, such as a http: or https: link, from where the extension is running to a uri to the same resource on the client machine.

This is a no-op if the extension is running on the client machine.

If the extension is running remotely, this function automatically establishes a port forwarding tunnel from the local machine to target on the remote and returns a local uri to the tunnel. The lifetime of the port forwarding tunnel is managed by the editor and the tunnel can be closed by the user.

Note that uris passed through openExternal are automatically resolved and you should not call asExternalUri on them.

vscode.env.uriScheme

Creates a uri that - if opened in a browser (e.g. via openExternal) - will result in a registered UriHandler to trigger.

Extensions should not make any assumptions about the resulting uri and should not alter it in any way. Rather, extensions can e.g. use this uri in an authentication flow, by adding the uri as callback query argument to the server to authenticate to.

Note that if the server decides to add additional query parameters to the uri (e.g. a token or secret), it will appear in the uri that is passed to the UriHandler.

Example of an authentication flow:

vscode.window.registerUriHandler({
  handleUri(uri: vscode.Uri): vscode.ProviderResult<void> {
    if (uri.path === '/did-authenticate') {
      console.log(uri.toString());
    }
  }
});

const callableUri = await vscode.env.asExternalUri(
  vscode.Uri.parse(vscode.env.uriScheme + '://my.extension/did-authenticate')
);
await vscode.env.openExternal(callableUri);

Note that extensions should not cache the result of asExternalUri as the resolved uri may become invalid due to a system or user action — for example, in remote cases, a user may close a port forwarding tunnel that was opened by asExternalUri.

Any other scheme

Any other scheme will be handled as if the provided URI is a workspace URI. In that case, the method will return a URI which, when handled, will make the editor open the workspace.

Creates a new telemetry logger.

Opens a link externally using the default application. Depending on the used scheme this can be:

• a browser (http:, https:)
• a mail client (mailto:)
• VSCode itself (vscode: from vscode.env.uriScheme)

Note that showTextDocument is the right way to open a text document inside the editor, not this function.

All extensions currently known to the system.

An event which fires when extensions.all changes. This can happen when extensions are installed, uninstalled, enabled or disabled.

Get an extension by its full identifier in the form of: publisher.name.

The bundle of localized strings that have been loaded for the extension. It's undefined if no bundle has been loaded. The bundle is typically not loaded if there was no bundle found or when we are running with the default language.

The URI of the localization bundle that has been loaded for the extension. It's undefined if no bundle has been loaded. The bundle is typically not loaded if there was no bundle found or when we are running with the default language.

Marks a string for localization. If a localized bundle is available for the language specified by language and the bundle has a localized value for this message, then that localized value will be returned (with injected args values for any templated values).

• example - ```ts l10n.t('Hello {0}!', 'World');

```

Marks a string for localization. If a localized bundle is available for the language specified by language and the bundle has a localized value for this message, then that localized value will be returned (with injected args values for any templated values).

• example - ```ts l10n.t('Hello {name}', { name: 'Erich' });

```

Marks a string for localization. If a localized bundle is available for the language specified by language and the bundle has a localized value for this message, then that localized value will be returned (with injected args values for any templated values).

An Event which fires when the global set of diagnostics changes. This is newly added and removed diagnostics.

Create a diagnostics collection.

Creates a new language status item.

Get all diagnostics for a given resource.

Get all diagnostics.

Return the identifiers of all known languages.

Compute the match between a document selector and a document. Values greater than zero mean the selector matches the document.

A match is computed according to these rules:

1. When DocumentSelector is an array, compute the match for each contained DocumentFilter or language identifier and take the maximum value.
2. A string will be desugared to become the language-part of a DocumentFilter, so "fooLang" is like { language: "fooLang" }.
3. A DocumentFilter will be matched against the document by comparing its parts with the document. The following rules apply:
   1. When the DocumentFilter is empty ({}) the result is 0
   2. When scheme, language, pattern, or notebook are defined but one doesn't match, the result is 0
   3. Matching against * gives a score of 5, matching via equality or via a glob-pattern gives a score of 10
   4. The result is the maximum value of each match

Samples:

// default document from disk (file-scheme)
doc.uri; //'file:///my/file.js'
doc.languageId; // 'javascript'
match('javascript', doc); // 10;
match({ language: 'javascript' }, doc); // 10;
match({ language: 'javascript', scheme: 'file' }, doc); // 10;
match('*', doc); // 5
match('fooLang', doc); // 0
match(['fooLang', '*'], doc); // 5

// virtual document, e.g. from git-index
doc.uri; // 'git:/my/file.js'
doc.languageId; // 'javascript'
match('javascript', doc); // 10;
match({ language: 'javascript', scheme: 'git' }, doc); // 10;
match('*', doc); // 5

// notebook cell document
doc.uri; // `vscode-notebook-cell:///my/notebook.ipynb#gl65s2pmha`;
doc.languageId; // 'python'
match({ notebookType: 'jupyter-notebook' }, doc); // 10
match({ notebookType: 'fooNotebook', language: 'python' }, doc); // 0
match({ language: 'python' }, doc); // 10
match({ notebookType: '*' }, doc); // 5

Register a call hierarchy provider.

Register a code action provider.

Multiple providers can be registered for a language. In that case providers are asked in parallel and the results are merged. A failing provider (rejected promise or exception) will not cause a failure of the whole operation.

Register a code lens provider.

Multiple providers can be registered for a language. In that case providers are asked in parallel and the results are merged. A failing provider (rejected promise or exception) will not cause a failure of the whole operation.

Register a color provider.

Multiple providers can be registered for a language. In that case providers are asked in parallel and the results are merged. A failing provider (rejected promise or exception) will not cause a failure of the whole operation.

Register a completion provider.

Multiple providers can be registered for a language. In that case providers are sorted by their score and groups of equal score are sequentially asked for completion items. The process stops when one or many providers of a group return a result. A failing provider (rejected promise or exception) will not fail the whole operation.

A completion item provider can be associated with a set of triggerCharacters. When trigger characters are being typed, completions are requested but only from providers that registered the typed character. Because of that trigger characters should be different than word characters, a common trigger character is . to trigger member completions.

Register a declaration provider.

Multiple providers can be registered for a language. In that case providers are asked in parallel and the results are merged. A failing provider (rejected promise or exception) will not cause a failure of the whole operation.

Register a definition provider.

Multiple providers can be registered for a language. In that case providers are asked in parallel and the results are merged. A failing provider (rejected promise or exception) will not cause a failure of the whole operation.

Registers a new DocumentDropEditProvider.

Register a formatting provider for a document.

Multiple providers can be registered for a language. In that case providers are sorted by their score and the best-matching provider is used. Failure of the selected provider will cause a failure of the whole operation.

Register a document highlight provider.

Multiple providers can be registered for a language. In that case providers are sorted by their score and groups sequentially asked for document highlights. The process stops when a provider returns a non-falsy or non-failure result.

Register a document link provider.

Multiple providers can be registered for a language. In that case providers are asked in parallel and the results are merged. A failing provider (rejected promise or exception) will not cause a failure of the whole operation.

Register a formatting provider for a document range.

Note: A document range provider is also a document formatter which means there is no need to register a document formatter when also registering a range provider.

Multiple providers can be registered for a language. In that case providers are sorted by their score and the best-matching provider is used. Failure of the selected provider will cause a failure of the whole operation.

Register a semantic tokens provider for a document range.

Note: If a document has both a DocumentSemanticTokensProvider and a DocumentRangeSemanticTokensProvider, the range provider will be invoked only initially, for the time in which the full document provider takes to resolve the first request. Once the full document provider resolves the first request, the semantic tokens provided via the range provider will be discarded and from that point forward, only the document provider will be used.

Multiple providers can be registered for a language. In that case providers are sorted by their score and the best-matching provider is used. Failure of the selected provider will cause a failure of the whole operation.

Register a semantic tokens provider for a whole document.

Multiple providers can be registered for a language. In that case providers are sorted by their score and the best-matching provider is used. Failure of the selected provider will cause a failure of the whole operation.

Register a document symbol provider.

Multiple providers can be registered for a language. In that case providers are asked in parallel and the results are merged. A failing provider (rejected promise or exception) will not cause a failure of the whole operation.

Register a provider that locates evaluatable expressions in text documents. The editor will evaluate the expression in the active debug session and will show the result in the debug hover.

If multiple providers are registered for a language an arbitrary provider will be used.

Register a folding range provider.

Multiple providers can be registered for a language. In that case providers are asked in parallel and the results are merged. If multiple folding ranges start at the same position, only the range of the first registered provider is used. If a folding range overlaps with an other range that has a smaller position, it is also ignored.

A failing provider (rejected promise or exception) will not cause a failure of the whole operation.

Register a hover provider.

Multiple providers can be registered for a language. In that case providers are asked in parallel and the results are merged. A failing provider (rejected promise or exception) will not cause a failure of the whole operation.

Register an implementation provider.

Multiple providers can be registered for a language. In that case providers are asked in parallel and the results are merged. A failing provider (rejected promise or exception) will not cause a failure of the whole operation.

Register a inlay hints provider.

Multiple providers can be registered for a language. In that case providers are asked in parallel and the results are merged. A failing provider (rejected promise or exception) will not cause a failure of the whole operation.

Registers an inline completion provider.

Multiple providers can be registered for a language. In that case providers are asked in parallel and the results are merged. A failing provider (rejected promise or exception) will not cause a failure of the whole operation.

Register a provider that returns data for the debugger's 'inline value' feature. Whenever the generic debugger has stopped in a source file, providers registered for the language of the file are called to return textual data that will be shown in the editor at the end of lines.

Multiple providers can be registered for a language. In that case providers are asked in parallel and the results are merged. A failing provider (rejected promise or exception) will not cause a failure of the whole operation.

Register a linked editing range provider.

Multiple providers can be registered for a language. In that case providers are sorted by their score and the best-matching provider that has a result is used. Failure of the selected provider will cause a failure of the whole operation.

Register a formatting provider that works on type. The provider is active when the user enables the setting editor.formatOnType.

Multiple providers can be registered for a language. In that case providers are sorted by their score and the best-matching provider is used. Failure of the selected provider will cause a failure of the whole operation.

Register a reference provider.

Multiple providers can be registered for a language. In that case providers are asked in parallel and the results are merged. A failing provider (rejected promise or exception) will not cause a failure of the whole operation.

Register a rename provider.

Multiple providers can be registered for a language. In that case providers are sorted by their score and asked in sequence. The first provider producing a result defines the result of the whole operation.

Register a selection range provider.

Multiple providers can be registered for a language. In that case providers are asked in parallel and the results are merged. A failing provider (rejected promise or exception) will not cause a failure of the whole operation.

Register a signature help provider.

Multiple providers can be registered for a language. In that case providers are sorted by their score and called sequentially until a provider returns a valid result.

Register a type definition provider.

Multiple providers can be registered for a language. In that case providers are asked in parallel and the results are merged. A failing provider (rejected promise or exception) will not cause a failure of the whole operation.

Register a type hierarchy provider.

Register a workspace symbol provider.

Multiple providers can be registered. In that case providers are asked in parallel and the results are merged. A failing provider (rejected promise or exception) will not cause a failure of the whole operation.

Set a language configuration for a language.

Set (and change) the language that is associated with the given document.

Note that calling this function will trigger the onDidCloseTextDocument event followed by the onDidOpenTextDocument event.

Creates a new notebook controller.

Creates a new messaging instance used to communicate with a specific renderer.

• Note 1: Extensions can only create renderer that they have defined in their package.json-file
• Note 2: A renderer only has access to messaging if requiresMessaging is set to always or optional in its notebookRenderer contribution.

Register a cell statusbar item provider for the given notebook type.

The input box for the last source control created by the extension.

• deprecated - Use SourceControl.inputBox instead

Creates a new source control instance.

The currently active task executions or an empty array.

Fires when a task ends.

Fires when the underlying process has ended. This event will not fire for tasks that don't execute an underlying process.

Fires when a task starts.

Fires when the underlying process has been started. This event will not fire for tasks that don't execute an underlying process.

Executes a task that is managed by the editor. The returned task execution can be used to terminate the task.

• throws - When running a ShellExecution or a ProcessExecution task in an environment where a new process cannot be started. In such an environment, only CustomExecution tasks can be run.

Fetches all tasks available in the systems. This includes tasks from tasks.json files as well as tasks from task providers contributed through extensions.

Register a task provider.

Creates a new test controller.

The currently active color theme as configured in the settings. The active theme can be changed via the workbench.colorTheme setting.

The currently active notebook editor or undefined. The active editor is the one that currently has focus or, when none has focus, the one that has changed input most recently.

The currently active terminal or undefined. The active terminal is the one that currently has focus or most recently had focus.

The currently active editor or undefined. The active editor is the one that currently has focus or, when none has focus, the one that has changed input most recently.

Represents the current window's state.

Represents the grid widget within the main editor area

The currently opened terminals or an empty array.

The currently visible notebook editors or an empty array.

The currently visible editors or an empty array.

An Event which fires when the active color theme is changed or has changes.

An Event which fires when the active notebook editor has changed. Note that the event also fires when the active editor changes to undefined.

An Event which fires when the active terminal has changed. Note that the event also fires when the active terminal changes to undefined.

An Event which fires when the active editor has changed. Note that the event also fires when the active editor changes to undefined.

An Event which fires when the notebook editor selections have changed.

An Event which fires when the notebook editor visible ranges have changed.

An Event which fires when a terminal's state has changed.

An Event which fires when the options of an editor have changed.

An Event which fires when the selection in an editor has changed.

An Event which fires when the view column of an editor has changed.

An Event which fires when the visible ranges of an editor has changed.

An Event which fires when the visible notebook editors has changed.

An Event which fires when the array of visible editors has changed.

An Event which fires when the focus state of the current window changes. The value of the event represents whether the window is focused.

An Event which fires when a terminal is disposed.

An Event which fires when a terminal has been created, either through the createTerminal API or commands.

Creates a InputBox to let the user enter some text input.

Note that in many cases the more convenient showInputBox is easier to use. createInputBox should be used when showInputBox does not offer the required flexibility.

Creates a new output channel with the given name and language id If language id is not provided, then Log is used as default language id.

You can access the visible or active output channel as a text document from visible editors or active editor and use the language id to contribute language features like syntax coloring, code lens etc.,

Creates a new log output channel with the given name.

Creates a QuickPick to let the user pick an item from a list of items of type T.

Note that in many cases the more convenient showQuickPick is easier to use. createQuickPick should be used when showQuickPick does not offer the required flexibility.

Creates a status bar item.

Creates a status bar item.

Creates a Terminal with a backing shell process. The cwd of the terminal will be the workspace directory if it exists.

• throws - When running in an environment where a new process cannot be started.

Creates a Terminal with a backing shell process.

• throws - When running in an environment where a new process cannot be started.

Creates a Terminal where an extension controls its input and output.

Create a TextEditorDecorationType that can be used to add decorations to text editors.

Create a TreeView for the view contributed using the extension point views.

Create and show a new webview panel.

Register a provider for custom editors for the viewType contributed by the customEditors extension point.

When a custom editor is opened, an onCustomEditor:viewType activation event is fired. Your extension must register a CustomTextEditorProvider, CustomReadonlyEditorProvider, CustomEditorProviderfor viewType as part of activation.

Register a file decoration provider.

Register provider that enables the detection and handling of links within the terminal.

Registers a provider for a contributed terminal profile.

Register a TreeDataProvider for the view contributed using the extension point views. This will allow you to contribute data to the TreeView and update if the data changes.

Note: To get access to the TreeView and perform operations on it, use createTreeView.

Registers a uri handler capable of handling system-wide uris. In case there are multiple windows open, the topmost window will handle the uri. A uri handler is scoped to the extension it is contributed from; it will only be able to handle uris which are directed to the extension itself. A uri must respect the following rules:

• The uri-scheme must be vscode.env.uriScheme;
• The uri-authority must be the extension id (e.g. my.extension);
• The uri-path, -query and -fragment parts are arbitrary.

For example, if the my.extension extension registers a uri handler, it will only be allowed to handle uris with the prefix product-name://my.extension.

An extension can only register a single uri handler in its entire activation lifetime.

• Note: There is an activation event onUri that fires when a uri directed for the current extension is about to be handled.

Registers a webview panel serializer.

Extensions that support reviving should have an "onWebviewPanel:viewType" activation event and make sure that registerWebviewPanelSerializer is called during activation.

Only a single serializer may be registered at a time for a given viewType.

Register a new provider for webview views.

Set a message to the status bar. This is a short hand for the more powerful status bar items.

Set a message to the status bar. This is a short hand for the more powerful status bar items.

Set a message to the status bar. This is a short hand for the more powerful status bar items.

Note that status bar messages stack and that they must be disposed when no longer used.

Show an error message.

See also showInformationMessage

Show an error message.

See also showInformationMessage

Show an error message.

See also showInformationMessage

Show an error message.

See also showInformationMessage

Show an information message to users. Optionally provide an array of items which will be presented as clickable buttons.

Show an information message to users. Optionally provide an array of items which will be presented as clickable buttons.

Show an information message.

See also showInformationMessage

Show an information message.

See also showInformationMessage

Opens an input box to ask the user for input.

The returned value will be undefined if the input box was canceled (e.g. pressing ESC). Otherwise the returned value will be the string typed by the user or an empty string if the user did not type anything but dismissed the input box with OK.

Show the given NotebookDocument in a notebook editor.

Shows a file open dialog to the user which allows to select a file for opening-purposes.

Shows a selection list allowing multiple selections.

Shows a selection list.

Shows a selection list allowing multiple selections.

Shows a selection list.

Shows a file save dialog to the user which allows to select a file for saving-purposes.