vscode-api-reference

name: vscode-api-reference description: this is the entire vscode api reference

VS Code API

VS Code API is a set of JavaScript APIs that you can invoke in your Visual Studio Code extension. This page lists all VS Code APIs available to extension authors.

API namespaces and classes

This listing is compiled from the vscode.d.ts file from the VS Code repository.

authentication

Namespace for authentication.

Events

onDidChangeSessions: Event<AuthenticationSessionsChangeEvent>

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

Functions

getAccounts(providerId: string): Thenable<readonly AuthenticationSessionAccountInformation[]>

Get all accounts that the user is logged in to for the specified provider. Use this paired with getSession in order to get an authentication session for a specific account.

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'.

Note: Getting accounts does not imply that your extension has access to that account or its authentication sessions. You can verify access to the account by calling getSession.

getSession(providerId: string, scopeListOrRequest: readonly string[] | AuthenticationWwwAuthenticateRequest, options: AuthenticationGetSessionOptions & {createIfNone: true | AuthenticationGetSessionPresentationOptions}): Thenable<AuthenticationSession>

Get an authentication session matching the desired scopes or satisfying the WWW-Authenticate request. 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.

Built-in auth providers include:

• 'github' - For GitHub.com
• 'microsoft' For both personal & organizational Microsoft accounts
• (less common) 'github-enterprise' - for alternative GitHub hostings, GHE.com, GitHub Enterprise Server
• (less common) 'microsoft-sovereign-cloud' - for alternative Microsoft clouds

getSession(providerId: string, scopeListOrRequest: readonly string[] | AuthenticationWwwAuthenticateRequest, options: AuthenticationGetSessionOptions & {forceNewSession: true | AuthenticationGetSessionPresentationOptions}): Thenable<AuthenticationSession>

Get an authentication session matching the desired scopes or request. 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.

Built-in auth providers include:

• 'github' - For GitHub.com
• 'microsoft' For both personal & organizational Microsoft accounts
• (less common) 'github-enterprise' - for alternative GitHub hostings, GHE.com, GitHub Enterprise Server
• (less common) 'microsoft-sovereign-cloud' - for alternative Microsoft clouds

getSession(providerId: string, scopeListOrRequest: readonly string[] | AuthenticationWwwAuthenticateRequest, options?: AuthenticationGetSessionOptions): Thenable<AuthenticationSession | undefined>

Get an authentication session matching the desired scopes or request. 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.

Built-in auth providers include:

• 'github' - For GitHub.com
• 'microsoft' For both personal & organizational Microsoft accounts
• (less common) 'github-enterprise' - for alternative GitHub hostings, GHE.com, GitHub Enterprise Server
• (less common) 'microsoft-sovereign-cloud' - for alternative Microsoft clouds

registerAuthenticationProvider(id: string, label: string, provider: AuthenticationProvider, options?: AuthenticationProviderOptions): Disposable

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.

chat

Namespace for chat functionality. Users interact with chat participants by sending messages to them in the chat view. Chat participants can respond with markdown or other types of content via the ChatResponseStream.

Functions

createChatParticipant(id: string, handler: ChatRequestHandler): ChatParticipant

Create a new chat participant instance.

commands

Namespace for dealing with commands. In short, a command is a function with a unique identifier. The function is sometimes also called command handler.

Commands can be added to the editor using the registerCommand and registerTextEditorCommand functions. Commands can be executed manually or from a UI gesture. Those are:

• palette - Use the commands-section in package.json to make a command show in the command palette.
• keybinding - Use the keybindings-section in package.json to enable keybindings for your extension.

Commands from other extensions and from the editor itself are accessible to an extension. However, when invoking an editor command not all argument types are supported.

This is a sample that registers a command handler and adds an entry for that command to the palette. First register a command handler with the identifier extension.sayHello.

commands.registerCommand('extension.sayHello', () => {
  window.showInformationMessage('Hello World!');
});

Second, bind the command identifier to a title under which it will show in the palette (package.json).

{
  "contributes": {
    "commands": [
      {
        "command": "extension.sayHello",
        "title": "Hello World"
      }
    ]
  }
}

Functions

executeCommand<T>(command: string, ...rest: any[]): Thenable<T>

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.

getCommands(filterInternal?: boolean): Thenable<string[]>

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

registerCommand(command: string, callback: (args: any[]) => any, thisArg?: any): Disposable

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.

registerTextEditorCommand(command: string, callback: (textEditor: TextEditor, edit: TextEditorEdit, args: any[]) => void, thisArg?: any): Disposable

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.

comments

Functions

createCommentController(id: string, label: string): CommentController

Creates a new comment controller instance.

debug

Namespace for debug functionality.

Variables

activeDebugConsole: DebugConsole

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

activeDebugSession: DebugSession | undefined

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.

activeStackItem: DebugThread | DebugStackFrame | undefined

The currently focused thread or stack frame, or undefined if no thread or stack is focused. A thread can be focused any time there is an active debug session, while a stack frame can only be focused when a session is paused and the call stack has been retrieved.

breakpoints: readonly Breakpoint[]

List of breakpoints.

Events

onDidChangeActiveDebugSession: Event<DebugSession | undefined>

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.

onDidChangeActiveStackItem: Event<DebugThread | DebugStackFrame | undefined>

An event which fires when the debug.activeStackItem has changed.

onDidChangeBreakpoints: Event<BreakpointsChangeEvent>

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

onDidReceiveDebugSessionCustomEvent: Event<DebugSessionCustomEvent>

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

onDidStartDebugSession: Event<DebugSession>

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

onDidTerminateDebugSession: Event<DebugSession>

An Event which fires when a debug session has terminated.

Functions

addBreakpoints(breakpoints: readonly Breakpoint[]): void

Add breakpoints.

asDebugSourceUri(source: DebugProtocolSource, session?: DebugSession): Uri

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.

registerDebugAdapterDescriptorFactory(debugType: string, factory: DebugAdapterDescriptorFactory): Disposable

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.

registerDebugAdapterTrackerFactory(debugType: string, factory: DebugAdapterTrackerFactory): Disposable

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

registerDebugConfigurationProvider(debugType: string, provider: DebugConfigurationProvider, triggerKind?: DebugConfigurationProviderTriggerKind): Disposable

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.

removeBreakpoints(breakpoints: readonly Breakpoint[]): void

Remove breakpoints.

startDebugging(folder: WorkspaceFolder, nameOrConfiguration: string | DebugConfiguration, parentSessionOrOptions?: DebugSession | DebugSessionOptions): Thenable<boolean>

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.

stopDebugging(session?: DebugSession): Thenable<void>

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

env

Namespace describing the environment the editor runs in.

Variables

appHost: string

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

appName: string

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

appRoot: string

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.

clipboard: Clipboard

The system clipboard.

isNewAppInstall: boolean

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

isTelemetryEnabled: boolean

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

language: string

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

logLevel: LogLevel

The current log level of the editor.

machineId: string

A unique identifier for the computer.

remoteName: string | undefined

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 Extension.extensionKind to know if a specific extension runs remote or not.

sessionId: string

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

shell: string

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.

uiKind: UIKind

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.

uriScheme: string

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

Events

onDidChangeLogLevel: Event<LogLevel>

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

onDidChangeShell: Event<string>

An Event which fires when the default shell changes. This fires with the new shell path.

onDidChangeTelemetryEnabled: Event<boolean>

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.

Functions

asExternalUri(target: Uri): Thenable<Uri>

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.

createTelemetryLogger(sender: TelemetrySender, options?: TelemetryLoggerOptions): TelemetryLogger

Creates a new telemetry logger.

openExternal(target: Uri): Thenable<boolean>

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.

extensions

Namespace for dealing with installed extensions. Extensions are represented by an Extension-interface which enables reflection on them.

Extension writers can provide APIs to other extensions by returning their API public surface from the activate-call.

export function activate(context: vscode.ExtensionContext) {
  let api = {
    sum(a, b) {
      return a + b;
    },
    mul(a, b) {
      return a * b;
    }
  };
  // 'export' public api-surface
  return api;
}

When depending on the API of another extension add an extensionDependencies-entry to package.json, and use the getExtension-function and the exports-property, like below:

let mathExt = extensions.getExtension('genius.math');
let importedApi = mathExt.exports;

console.log(importedApi.mul(42, 1));

Variables

all: readonly Extension<any>[]

All extensions currently known to the system.

Events

onDidChange: Event<void>

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

Functions

getExtension<T>(extensionId: string): Extension<T> | undefined

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

l10n

Namespace for localization-related functionality in the extension API. To use this properly, you must have l10n defined in your extension manifest and have bundle.l10n..json files. For more information on how to generate bundle.l10n..json files, check out the vscode-l10n repo.

Note: Built-in extensions (for example, Git, TypeScript Language Features, GitHub Authentication) are excluded from the l10n property requirement. In other words, they do not need to specify a l10n in the extension manifest because their translated strings come from Language Packs.

Variables

bundle: | undefined

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.

uri: Uri | undefined

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.

Functions

t(message: string, ...args: Array<string | number | boolean>): string

Marks a string for localization. If a localized bundle is available for the language specified by env.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

l10n.t('Hello {0}!', 'World');

t(message: string, args: Record<string, string | number | boolean>): string

Marks a string for localization. If a localized bundle is available for the language specified by env.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

l10n.t('Hello {name}', { name: 'Erich' });

t(options: {args: Array<string | number | boolean> | Record<string, string | number | boolean>, comment: string | string[], message: string}): string

Marks a string for localization. If a localized bundle is available for the language specified by env.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).

languages

Namespace for participating in language-specific editor features, like IntelliSense, code actions, diagnostics etc.

Many programming languages exist and there is huge variety in syntaxes, semantics, and paradigms. Despite that, features like automatic word-completion, code navigation, or code checking have become popular across different tools for different programming languages.

The editor provides an API that makes it simple to provide such common features by having all UI and actions already in place and by allowing you to participate by providing data only. For instance, to contribute a hover all you have to do is provide a function that can be called with a TextDocument and a Position returning hover info. The rest, like tracking the mouse, positioning the hover, keeping the hover stable etc. is taken care of by the editor.

languages.registerHoverProvider('javascript', {
  provideHover(document, position, token) {
    return new Hover('I am a hover!');
  }
});

Registration is done using a document selector which is either a language id, like javascript or a more complex filter like { language: 'typescript', scheme: 'file' }. Matching a document against such a selector will result in a score that is used to determine if and how a provider shall be used. When scores are equal the provider that came last wins. For features that allow full arity, like hover, the score is only checked to be >0, for other features, like IntelliSense the score is used for determining the order in which providers are asked to participate.

Events

onDidChangeDiagnostics: Event<DiagnosticChangeEvent>

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

Functions

createDiagnosticCollection(name?: string): DiagnosticCollection

Create a diagnostics collection.

createLanguageStatusItem(id: string, selector: DocumentSelector): LanguageStatusItem

Creates a new language status item.

getDiagnostics(resource: Uri): Diagnostic[]

Get all diagnostics for a given resource.

getDiagnostics(): Array<[Uri, Diagnostic[]]>

Get all diagnostics.

getLanguages(): Thenable<string[]>

Return the identifiers of all known languages.

match(selector: DocumentSelector, document: TextDocument): number

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

registerCallHierarchyProvider(selector: DocumentSelector, provider: CallHierarchyProvider): Disposable

Register a call hierarchy provider.

registerCodeActionsProvider(selector: DocumentSelector, provider: CodeActionProvider<CodeAction>, metadata?: CodeActionProviderMetadata): Disposable

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.

registerCodeLensProvider(selector: DocumentSelector, provider: CodeLensProvider<CodeLens>): Disposable

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.

registerColorProvider(selector: DocumentSelector, provider: DocumentColorProvider): Disposable

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.

registerCompletionItemProvider(selector: DocumentSelector, provider: CompletionItemProvider<CompletionItem>, ...triggerCharacters: string[]): Disposable

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.

registerDeclarationProvider(selector: DocumentSelector, provider: DeclarationProvider): Disposable

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.

registerDefinitionProvider(selector: DocumentSelector, provider: DefinitionProvider): Disposable

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.

registerDocumentDropEditProvider(selector: DocumentSelector, provider: DocumentDropEditProvider<DocumentDropEdit>, metadata?: DocumentDropEditProviderMetadata): Disposable

Registers a new DocumentDropEditProvider.

Multiple drop providers can be registered for a language. When dropping content into an editor, all registered providers for the editor's language will be invoked based on the mimetypes they handle as specified by their DocumentDropEditProviderMetadata.

Each provider can return one or more DocumentDropEdits. The edits are sorted using the DocumentDropEdit.yieldTo property. By default the first edit will be applied. If there are any additional edits, these will be shown to the user as selectable drop options in the drop widget.

registerDocumentFormattingEditProvider(selector: DocumentSelector, provider: DocumentFormattingEditProvider): Disposable

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.

registerDocumentHighlightProvider(selector: DocumentSelector, provider: DocumentHighlightProvider): Disposable

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.

registerDocumentLinkProvider(selector: DocumentSelector, provider: DocumentLinkProvider<DocumentLink>): Disposable

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.

registerDocumentPasteEditProvider(selector: DocumentSelector, provider: DocumentPasteEditProvider<DocumentPasteEdit>, metadata: DocumentPasteProviderMetadata): Disposable

Registers a new DocumentPasteEditProvider.

Multiple providers can be registered for a language. All registered providers for a language will be invoked for copy and paste operations based on their handled mimetypes as specified by the DocumentPasteProviderMetadata.

For copy operations, changes to the DataTransfer made by each provider will be merged into a single DataTransfer that is used to populate the clipboard.

For [DocumentPasteEditProvider.providerDocumentPasteEdits paste operations](#_DocumentPasteEditProvider.providerDocumentPasteEdits paste operations), each provider will be invoked and can return one or more DocumentPasteEdits. The edits are sorted using the DocumentPasteEdit.yieldTo property. By default the first edit will be applied and the rest of the edits will be shown to the user as selectable paste options in the paste widget.

registerDocumentRangeFormattingEditProvider(selector: DocumentSelector, provider: DocumentRangeFormattingEditProvider): Disposable

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.

registerDocumentRangeSemanticTokensProvider(selector: DocumentSelector, provider: DocumentRangeSemanticTokensProvider, legend: SemanticTokensLegend): Disposable

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.

registerDocumentSemanticTokensProvider(selector: DocumentSelector, provider: DocumentSemanticTokensProvider, legend: SemanticTokensLegend): Disposable

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.

registerDocumentSymbolProvider(selector: DocumentSelector, provider: DocumentSymbolProvider, metaData?: DocumentSymbolProviderMetadata): Disposable

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.

registerEvaluatableExpressionProvider(selector: DocumentSelector, provider: EvaluatableExpressionProvider): Disposable

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.

registerFoldingRangeProvider(selector: DocumentSelector, provider: FoldingRangeProvider): Disposable

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.

registerHoverProvider(selector: DocumentSelector, provider: HoverProvider): Disposable

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.

registerImplementationProvider(selector: DocumentSelector, provider: ImplementationProvider): Disposable

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.

registerInlayHintsProvider(selector: DocumentSelector, provider: InlayHintsProvider<InlayHint>): Disposable

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.

registerInlineCompletionItemProvider(selector: DocumentSelector, provider: InlineCompletionItemProvider): Disposable

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.

registerInlineValuesProvider(selector: DocumentSelector, provider: InlineValuesProvider): Disposable

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.

registerLinkedEditingRangeProvider(selector: DocumentSelector, provider: LinkedEditingRangeProvider): Disposable

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.

registerOnTypeFormattingEditProvider(selector: DocumentSelector, provider: OnTypeFormattingEditProvider, firstTriggerCharacter: string, ...moreTriggerCharacter: string[]): Disposable

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.

registerReferenceProvider(selector: DocumentSelector, provider: ReferenceProvider): Disposable

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.

registerRenameProvider(selector: DocumentSelector, provider: RenameProvider): Disposable

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.

registerSelectionRangeProvider(selector: DocumentSelector, provider: SelectionRangeProvider): Disposable

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.

registerSignatureHelpProvider(selector: DocumentSelector, provider: SignatureHelpProvider, ...triggerCharacters: string[]): Disposable

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.

registerSignatureHelpProvider(selector: DocumentSelector, provider: SignatureHelpProvider, metadata: SignatureHelpProviderMetadata): Disposable

See also languages.registerSignatureHelpProvider

registerTypeDefinitionProvider(selector: DocumentSelector, provider: TypeDefinitionProvider): Disposable

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.

registerTypeHierarchyProvider(selector: DocumentSelector, provider: TypeHierarchyProvider): Disposable

Register a type hierarchy provider.

registerWorkspaceSymbolProvider(provider: WorkspaceSymbolProvider<SymbolInformation>): Disposable

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.

setLanguageConfiguration(language: string, configuration: LanguageConfiguration): Disposable

Set a language configuration for a language.

setTextDocumentLanguage(document: TextDocument, languageId: string): Thenable<TextDocument>

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.

lm

Namespace for language model related functionality.

Variables

tools: readonly LanguageModelToolInformation[]

A list of all available tools that were registered by all extensions using lm.registerTool. They can be called with lm.invokeTool with input that match their declared inputSchema.

Events

onDidChangeChatModels: Event<void>

An event that is fired when the set of available chat models changes.

Functions

invokeTool(name: string, options: LanguageModelToolInvocationOptions<object>, token?: CancellationToken): Thenable<LanguageModelToolResult>

Invoke a tool listed in lm.tools by name with the given input. The input will be validated against the schema declared by the tool

A tool can be invoked by a chat participant, in the context of handling a chat request, or globally by any extension in any custom flow.

In the former case, the caller shall pass the toolInvocationToken, which comes from a chat request. This makes sure the chat UI shows the tool invocation for the correct conversation.

A tool result is an array of text- and prompt-tsx-parts. If the tool caller is using vscode/prompt-tsx, it can incorporate the response parts into its prompt using a ToolResult. If not, the parts can be passed along to the LanguageModelChat via a user message with a LanguageModelToolResultPart.

If a chat participant wants to preserve tool results for requests across multiple turns, it can store tool results in the ChatResult.metadata returned from the handler and retrieve them on the next turn from ChatResponseTurn.result.

registerLanguageModelChatProvider(vendor: string, provider: LanguageModelChatProvider<LanguageModelChatInformation>): Disposable

Registers a LanguageModelChatProvider Note: You must also define the language model chat provider via the languageModelChatProviders contribution point in package.json

registerMcpServerDefinitionProvider(id: string, provider: McpServerDefinitionProvider<McpServerDefinition>): Disposable

Registers a provider that publishes Model Context Protocol servers for the editor to consume. This allows MCP servers to be dynamically provided to the editor in addition to those the user creates in their configuration files.

Before calling this method, extensions must register the contributes.mcpServerDefinitionProviders extension point with the corresponding id, for example:

    "contributes": {
        "mcpServerDefinitionProviders": [
            {
                "id": "cool-cloud-registry.mcp-servers",
                "label": "Cool Cloud Registry",
            }
        ]
    }

When a new McpServerDefinitionProvider is available, the editor will, by default, automatically invoke it to discover new servers and tools when a chat message is submitted. To enable this flow, extensions should call registerMcpServerDefinitionProvider during activation.

registerTool<T>(name: string, tool: LanguageModelTool<T>): Disposable

Register a LanguageModelTool. The tool must also be registered in the package.json languageModelTools contribution point. A registered tool is available in the lm.tools list for any extension to see. But in order for it to be seen by a language model, it must be passed in the list of available tools in LanguageModelChatRequestOptions.tools.

selectChatModels(selector?: LanguageModelChatSelector): Thenable<LanguageModelChat[]>

Select chat models by a selector. This can yield multiple or no chat models and extensions must handle these cases, esp. when no chat model exists, gracefully.

const models = await vscode.lm.selectChatModels({ family: 'gpt-3.5-turbo' });
if (models.length > 0) {
    const [first] = models;
    const response = await first.sendRequest(...)
    // ...
} else {
    // NO chat models available
}

A selector can be written to broadly match all models of a given vendor or family, or it can narrowly select one model by ID. Keep in mind that the available set of models will change over time, but also that prompts may perform differently in different models.

Note that extensions can hold on to the results returned by this function and use them later. However, when the onDidChangeChatModels-event is fired the list of chat models might have changed and extensions should re-query.

notebooks

Namespace for notebooks.

The notebooks functionality is composed of three loosely coupled components:

1. NotebookSerializer enable the editor to open, show, and save notebooks
2. NotebookController own the execution of notebooks, e.g they create output from code cells.
3. NotebookRenderer present notebook output in the editor. They run in a separate context.

Functions

createNotebookController(id: string, notebookType: string, label: string, handler?: (cells: NotebookCell[], notebook: NotebookDocument, controller: NotebookController) => void | Thenable<void>): NotebookController

Creates a new notebook controller.

createRendererMessaging(rendererId: string): NotebookRendererMessaging

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.

registerNotebookCellStatusBarItemProvider(notebookType: string, provider: NotebookCellStatusBarItemProvider): Disposable

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

scm

Namespace for source control management.

Variables

inputBox: SourceControlInputBox

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

• deprecated - Use SourceControl.inputBox instead

Functions

createSourceControl(id: string, label: string, rootUri?: Uri): SourceControl

Creates a new source control instance.

tasks

Namespace for tasks functionality.

Variables

taskExecutions: readonly TaskExecution[]

The currently active task executions or an empty array.

Events

onDidEndTask: Event<TaskEndEvent>

Fires when a task ends.

onDidEndTaskProcess: Event<TaskProcessEndEvent>

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

onDidStartTask: Event<TaskStartEvent>

Fires when a task starts.

onDidStartTaskProcess: Event<TaskProcessStartEvent>

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

Functions

executeTask(task: Task): Thenable<TaskExecution>

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.

fetchTasks(filter?: TaskFilter): Thenable<Task[]>

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

registerTaskProvider(type: string, provider: TaskProvider<Task>): Disposable

Register a task provider.

tests

Namespace for testing functionality. Tests are published by registering TestController instances, then adding TestItems. Controllers may also describe how to run tests by creating one or more TestRunProfile instances.

Functions

createTestController(id: string, label: string): TestController

Creates a new test controller.

window

Namespace for dealing with the current window of the editor. That is visible and active editors, as well as, UI elements to show messages, selections, and asking for user input.

Variables

activeColorTheme: ColorTheme

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

activeNotebookEditor: NotebookEditor | undefined

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.

activeTerminal: Terminal | undefined

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

activeTextEditor: TextEditor | undefined

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.

state: WindowState

Represents the current window's state.

tabGroups: TabGroups

Represents the grid widget within the main editor area

terminals: readonly Terminal[]

The currently opened terminals or an empty array.

visibleNotebookEditors: readonly NotebookEditor[]

The currently visible notebook editors or an empty array.

visibleTextEditors: readonly TextEditor[]

The currently visible editors or an empty array.

Events

onDidChangeActiveColorTheme: Event<ColorTheme>

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

onDidChangeActiveNotebookEditor: Event<NotebookEditor | undefined>

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

onDidChangeActiveTerminal: Event<Terminal | undefined>

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

onDidChangeActiveTextEditor: Event<TextEditor | undefined>

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

onDidChangeNotebookEditorSelection: Event<NotebookEditorSelectionChangeEvent>

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

onDidChangeNotebookEditorVisibleRanges: Event<NotebookEditorVisibleRangesChangeEvent>

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

onDidChangeTerminalShellIntegration: Event<TerminalShellIntegrationChangeEvent>

Fires when shell integration activates or one of its properties changes in a terminal.

onDidChangeTerminalState: Event<Terminal>

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

onDidChangeTextEditorOptions: Event<TextEditorOptionsChangeEvent>

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

onDidChangeTextEditorSelection: Event<TextEditorSelectionChangeEvent>

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

onDidChangeTextEditorViewColumn: Event<TextEditorViewColumnChangeEvent>

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

onDidChangeTextEditorVisibleRanges: Event<TextEditorVisibleRangesChangeEvent>

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

onDidChangeVisibleNotebookEditors: Event<readonly NotebookEditor[]>

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

onDidChangeVisibleTextEditors: Event<readonly TextEditor[]>

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

onDidChangeWindowState: Event<WindowState>

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

onDidCloseTerminal: Event<Terminal>

An Event which fires when a terminal is disposed.

onDidEndTerminalShellExecution: Event<TerminalShellExecutionEndEvent>

This will be fired when a terminal command is ended. This event will fire only when shell integration is activated for the terminal.

onDidOpenTerminal: Event<Terminal>

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

onDidStartTerminalShellExecution: Event<TerminalShellExecutionStartEvent>

This will be fired when a terminal command is started. This event will fire only when shell integration is activated for the terminal.

Functions

createInputBox(): InputBox

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

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

createOutputChannel(name: string, languageId?: string): OutputChannel

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.,

createOutputChannel(name: string, options: {log: true}): LogOutputChannel

Creates a new log output channel with the given name.

createQuickPick<T extends QuickPickItem>(): QuickPick<T>

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 window.showQuickPick is easier to use. window.createQuickPick should be used when window.showQuickPick does not offer the required flexibility.

createStatusBarItem(id: string, alignment?: StatusBarAlignment, priority?: number): StatusBarItem

Creates a status bar item.

createStatusBarItem(alignment?: StatusBarAlignment, priority?: number): StatusBarItem

Creates a status bar item.

See also createStatusBarItem for creating a status bar item with an identifier.

createTerminal(name?: string, shellPath?: string, shellArgs?: string | readonly string[]): Terminal

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.

createTerminal(options: TerminalOptions): Terminal

Creates a Terminal with a backing shell process.

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

createTerminal(options: ExtensionTerminalOptions): Terminal

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

createTextEditorDecorationType(options: DecorationRenderOptions): TextEditorDecorationType

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

createTreeView<T>(viewId: string, options: TreeViewOptions<T>): TreeView<T>

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

createWebviewPanel(viewType: string, title: string, showOptions: ViewColumn | {preserveFocus: boolean, viewColumn: ViewColumn}, options?: WebviewPanelOptions & WebviewOptions): WebviewPanel

Create and show a new webview panel.

registerCustomEditorProvider(viewType: string, provider: CustomTextEditorProvider | CustomReadonlyEditorProvider<CustomDocument> | CustomEditorProvider<CustomDocument>, options?: {supportsMultipleEditorsPerDocument: boolean, webviewOptions: WebviewPanelOptions}): Disposable

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.

registerFileDecorationProvider(provider: FileDecorationProvider): Disposable

Register a file decoration provider.

registerTerminalLinkProvider(provider: TerminalLinkProvider<TerminalLink>): Disposable

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

registerTerminalProfileProvider(id: string, provider: TerminalProfileProvider): Disposable

Registers a provider for a contributed terminal profile.

registerTreeDataProvider<T>(viewId: string, treeDataProvider: TreeDataProvider<T>): Disposable

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.

registerUriHandler(handler: UriHandler): Disposable

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.

registerWebviewPanelSerializer(viewType: string, serializer: WebviewPanelSerializer<unknown>): Disposable

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.

registerWebviewViewProvider(viewId: string, provider: WebviewViewProvider, options?: {webviewOptions: {retainContextWhenHidden: boolean}}): Disposable

Register a new provider for webview views.

setStatusBarMessage(text: string, hideAfterTimeout: number): Disposable

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

setStatusBarMessage(text: string, hideWhenDone: Thenable<any>): Disposable

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

setStatusBarMessage(text: string): Disposable

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.

showErrorMessage<T extends string>(message: string, ...items: T[]): Thenable<T | undefined>

Show an error message.

See also showInformationMessage

showErrorMessage<T extends string>(message: string, options: MessageOptions, ...items: T[]): Thenable<T | undefined>

Show an error message.

See also showInformationMessage

showErrorMessage<T extends MessageItem>(message: string, ...items: T[]): Thenable<T | undefined>

Show an error message.

See also showInformationMessage

showErrorMessage<T extends MessageItem>(message: string, options: MessageOptions, ...items: T[]): Thenable<T | undefined>

Show an error message.

See also showInformationMessage

showInformationMessage<T extends string>(message: string, ...items: T[]): Thenable<T | undefined>

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

showInformationMessage<T extends string>(message: string, options: MessageOptions, ...items: T[]): Thenable<T | undefined>

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

showInformationMessage<T extends MessageItem>(message: string, ...items: T[]): Thenable<T | undefined>

Show an information message.

See also showInformationMessage

showInformationMessage<T extends MessageItem>(message: string, options: MessageOptions, ...items: T[]): Thenable<T | undefined>

Show an information message.

See also showInformationMessage

showInputBox(options?: InputBoxOptions, token?: CancellationToken): Thenable<string | undefined>

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.

showNotebookDocument(document: NotebookDocument, options?: NotebookDocumentShowOptions): Thenable<NotebookEditor>

Show the given NotebookDocument in a notebook editor.

showOpenDialog(options?: OpenDialogOptions): Thenable<Uri[] | undefined>

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

showQuickPick(items: readonly string[] |

Content truncated for page performance. Open the source repository for the full SKILL.md file.