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

Document Selectors

Extensions can filter their features based on document selectors by language, file type, and location. This topic discusses document selectors, document schemes, and what extensions authors should be aware about.

Text documents not on disk

Not all text documents are stored on disk, for example, newly created documents. Unless specified, a document selector applies to all document types. Use the DocumentFilter scheme property to narrow down on certain schemes, for example { scheme: 'file', language: 'typescript' } for TypeScript files that are stored on disk.

Document selectors

The Visual Studio Code extension API combines language-specific features, like IntelliSense, with document selectors through the DocumentSelector type. They are an easy mechanism to narrow down functionality to a specific language.

The snippet below registers a HoverProvider for TypeScript files and the document selector is the typescript language identifier string.

vscode.languages.registerHoverProvider( { pattern: '**/test/**' }, { provideHover(doc: vscode.TextDocument) { return new vscode.Hover('For documents inside `test`-folders only'); } } );

The next snippet uses the scheme filter and combines it with a language identifier. The untitled scheme is for new files that have not yet been saved to disk.

// 👎 too lax vscode.languages.registerHoverProvider('typescript', { provideHover(doc: vscode.TextDocument) { const { size } = fs.statSync(doc.uri.fsPath); // ⚠️ what about 'untitled:/Untitled1.ts' or others? return new vscode.Hover(`Size in bytes is ${size}`); } });

The hover provider above wants to display the size of a document on disk but it fails to check whether the document is actually stored on disk. For example, it could be newly created and not yet saved. The correct way would be to tell VS Code that the provider can only work with files on disk.