Extension API

Topics Overview Your First Extension Extension Anatomy Wrapping Up Overview Common Capabilities Theming Extending Workbench Overview AI Extensibility Language Model Tool MCP Dev Guide Chat Participant Chat Tutorial Language Model Language Model Tutorial Language Model Chat Provider Prompt TSX Command Color Theme File Icon Theme Product Icon Theme Tree View Webview Notebook Custom Editors Virtual Documents Virtual Workspaces Web Extensions Workspace Trust Task Provider Source Control Debugger Extension Markdown Extension Test Extension Custom Data Extension Telemetry Overview Activity Bar Sidebars Panel Status Bar Views Editor Actions Quick Picks Command Palette Notifications Webviews Context Menus Walkthroughs Settings Overview Syntax Highlight Guide Semantic Highlight Guide Snippet Guide Language Configuration Guide Programmatic Language Features Language Server Extension Guide Embedded Languages Testing Extensions Publishing Extensions Bundling Extensions Continuous Integration Extension Host Remote Development and Codespaces Using Proposed API Migrate from TSLint to ESLint Python Extension Template VS Code API Contribution Points Activation Events Extension Manifest Built-In Commands When Clause Contexts Theme Color Product Icon Reference Document Selector

Commands

Commands trigger actions in Visual Studio Code. If you have ever configured a keybinding, then you've worked with commands. Commands are also used by extensions to expose functionality to users, bind to actions in VS Code's UI, and implement internal logic.

Using Commands

VS Code includes a large set of built-in commands that you can use to interact with the editor, control the user interface, or perform background operations. Many extensions also expose their core functionality as commands that users and other extensions can leverage.

Programmatically executing a command

The vscode.commands.executeCommand API programmatically executes a command. This lets you use VS Code's built-in functionality, and build on extensions such as VS Code's built-in Git and Markdown extensions.

The editor.action.addCommentLine command, for example, comments the currently selected lines in the active text editor:

import * as vscode from 'vscode'; async function printDefinitionsForActiveEditor() { const activeEditor = vscode.window.activeTextEditor; if (!activeEditor) { return; } const definitions = await vscode.commands.executeCommand<vscode.Location[]>( 'vscode.executeDefinitionProvider', activeEditor.document.uri, activeEditor.selection.active ); for (const definition of definitions) { console.log(definition); } }

To find available commands:

Command URIs

Commands URIs are links that execute a given command. They can be used as clickable links in hover text, completion item details, or inside of webviews.

A command URI uses the command scheme followed by the command name. The command URI for the editor.action.addCommentLine command, for example, is command:editor.action.addCommentLine. Here's a hover provider that shows a link in the comments of the current line in the active text editor:

import * as vscode from 'vscode'; export function activate(context: vscode.ExtensionContext) { vscode.languages.registerHoverProvider( 'javascript', new (class implements vscode.HoverProvider { provideHover( document: vscode.TextDocument, _position: vscode.Position, _token: vscode.CancellationToken ): vscode.ProviderResult<vscode.Hover> { const args = [{ resourceUri: document.uri }]; const stageCommandUri = vscode.Uri.parse( `command:git.stage?${encodeURIComponent(JSON.stringify(args))}` ); const contents = new vscode.MarkdownString(`[Stage file](${stageCommandUri})`); contents.isTrusted = true; return new vscode.Hover(contents); } })() ); }

You can enable command URIs in webviews by setting enableCommandUris in the WebviewOptions when the webview is created.

Creating new commands

Registering a command

vscode.commands.registerCommand binds a command ID to a handler function in your extension:

{ "contributes": { "commands": [ { "command": "myExtension.sayHello", "title": "Say Hello" } ] } }

The commands contribution tells VS Code that your extension provides a given command and should be activated when that command is invoked, and also lets you control how the command is displayed in the UI. Make sure to follow the command naming conventions when creating commands.

Now when a user first invokes the myExtension.sayHello command from the Command Palette or through a keybinding, the extension will be activated and registerCommand will bind myExtension.sayHello to the proper handler.

Note: Extensions targeting VS Code versions prior to 1.74.0 must explicitly register an onCommand activationEvent for all user facing commands so that the extension activates and registerCommand executes:

{ "contributes": { "menus": { "commandPalette": [ { "command": "myExtension.sayHello", "when": "editorLangId == markdown" } ] } } }

Now the myExtension.sayHello command will only show up in the Command Palette when the user is in a Markdown file.

Enablement of commands

Commands support enablement via an enablement property - its value is a when-clause. Enablement applies to all menus and to registered keybindings.

Note: There is semantic overlap between enablement and the when condition of menu items. The latter is used to prevent menus full of disabled items. For example, a command that analyzes a JavaScript regular expression should show when the file is JavaScript and be enabled only when the cursor is over a regular expression. The when clause prevents clutter, by not showing the command for all other language files. Preventing cluttered menus is highly recommended.

Last, menus showing commands, like the Command Palette or context menus, implement different ways of dealing with enablement. Editor and explorer context menus render enablement/disablement items while the Command Palette filters them.

Using a custom when clause context

If you are authoring your own VS Code extension and need to enable/disable commands, menus, or views by using a when clause context and none of the existing keys suit your needs, then you can add your own context.

The first example below sets the key myExtension.showMyCommand to true, which you can use in enablement of commands or with the when property. The second example stores a value that you could use with a when clause to check if the number of cool open things is greater than 2.