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

getSession(providerId: string, scopes: string[], options: AuthenticationGetSessionOptions & {createIfNone: true}): Thenable<AuthenticationSession>

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 VS Code that implement GitHub and Microsoft authentication: their providerId’s are ‘github’ and ‘microsoft’.

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

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 VS Code that implement GitHub and Microsoft authentication: their providerId’s are ‘github’ and ‘microsoft’.

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 | undefined>

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.

breakpoints: 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.

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: 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 VS Code 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: Breakpoint[]): void

Remove breakpoints.

startDebugging(folder: WorkspaceFolder | undefined, 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

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.

language: string

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

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

Functions

asExternalUri(target: Uri): Thenable<Uri>

Resolves a uri to form that is accessible externally. Currently only supports https:, http: and vscode.env.uriScheme uris.

[

http: or https: scheme

](#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 VS Code 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

](#vscodeenvurischeme)

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

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: ReadonlyArray<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(extensionId: string): Extension<any> | undefined

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

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

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

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.

getDiagnostics(resource: Uri): Diagnostic[]

Get all diagnostics for a given resource.

getDiagnostics(): [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:
4. When the DocumentFilter is empty ({}) the result is 0
5. When scheme, language, or pattern are defined but one doesn’t match, the result is 0
6. Matching against * gives a score of 5, matching via equality or via a glob-pattern gives a score of 10
7. 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

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

Register a call hierarchy provider.

registerCodeActionsProvider(selector: DocumentSelector, provider: CodeActionProvider, 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): 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, …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.

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): 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.

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. VS Code 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.

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

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.

registerWorkspaceSymbolProvider(provider: WorkspaceSymbolProvider): 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.

scm

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: ReadonlyArray<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 VS Code. 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): Disposable

Register a task provider.

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.

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.

terminals: ReadonlyArray<Terminal>

The currently opened terminals or an empty array.

visibleTextEditors: 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.

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.

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.

onDidChangeVisibleTextEditors: Event<TextEditor[]>

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

onDidChangeWindowState: Event<WindowState>

An event which fires when the focus 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.

onDidOpenTerminal: Event<Terminal>

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

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): OutputChannel

Creates a new 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(alignment?: StatusBarAlignment, priority?: number): StatusBarItem

Creates a status bar item.

createTerminal(name?: string, shellPath?: string, shellArgs?: string[] | 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 | CustomEditorProvider, 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, VS Code fires an onCustomEditor:viewType activation event. Your extension must register a CustomTextEditorProvider, CustomReadonlyEditorProvider, CustomEditorProviderfor viewType as part of activation.

registerTerminalLinkProvider(provider: TerminalLinkProvider): Disposable

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

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): 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(message: string, …items: string[]): Thenable<string | undefined>

Show an error message.

• see - showInformationMessage

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

Show an error message.

• see - showInformationMessage

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

Show an error message.

• see - showInformationMessage

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

Show an error message.

• see - showInformationMessage

showInformationMessage(message: string, …items: string[]): Thenable<string | undefined>

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

showInformationMessage(message: string, options: MessageOptions, …items: string[]): Thenable<string | 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 - showInformationMessage

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

Show an information message.

• see - 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.

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: string[] | Thenable<string[]>, options: QuickPickOptions & {canPickMany: true}, token?: CancellationToken): Thenable<string[] | undefined>

Shows a selection list allowing multiple selections.

showQuickPick(items: string[] | Thenable<string[]>, options?: QuickPickOptions, token?: CancellationToken): Thenable<string | undefined>

Shows a selection list.

showQuickPick<T extends QuickPickItem>(items: T[] | Thenable<T[]>, options: QuickPickOptions & {canPickMany: true}, token?: CancellationToken): Thenable<T[] | undefined>

Shows a selection list allowing multiple selections.

showQuickPick<T extends QuickPickItem>(items: T[] | Thenable<T[]>, options?: QuickPickOptions, token?: CancellationToken): Thenable<T | undefined>

Shows a selection list.

showSaveDialog(options?: SaveDialogOptions): Thenable<Uri | undefined>

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

showTextDocument(document: TextDocument, column?: ViewColumn, preserveFocus?: boolean): Thenable<TextEditor>

Show the given document in a text editor. A column can be provided to control where the editor is being shown. Might change the active editor.

showTextDocument(document: TextDocument, options?: TextDocumentShowOptions): Thenable<TextEditor>

Show the given document in a text editor. Options can be provided to control options of the editor is being shown. Might change the active editor.

showTextDocument(uri: Uri, options?: TextDocumentShowOptions): Thenable<TextEditor>

A short-hand for openTextDocument(uri).then(document => showTextDocument(document, options)).

• see - openTextDocument

showWarningMessage(message: string, …items: string[]): Thenable<string | undefined>

Show a warning message.

• see - showInformationMessage

showWarningMessage(message: string, options: MessageOptions, …items: string[]): Thenable<string | undefined>

Show a warning message.

• see - showInformationMessage

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

Show a warning message.

• see - showInformationMessage

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

Show a warning message.

• see - showInformationMessage

showWorkspaceFolderPick(options?: WorkspaceFolderPickOptions): Thenable<WorkspaceFolder | undefined>

Shows a selection list of workspace folders to pick from. Returns undefined if no folder is open.

withProgress<R>(options: ProgressOptions, task: (progress: Progress<{increment: number, message: string}>, token: CancellationToken) => Thenable<R>): Thenable<R>

Show progress in the editor. Progress is shown while running the given callback and while the promise it returned isn’t resolved nor rejected. The location at which progress should show (and other details) is defined via the passed ProgressOptions.

withScmProgress<R>(task: (progress: Progress<number>) => Thenable<R>): Thenable<R>

Show progress in the Source Control viewlet while running the given callback and while its returned promise isn’t resolve or rejected.

• deprecated - Use withProgress instead.

workspace

Namespace for dealing with the current workspace. A workspace is the representation of the folder that has been opened. There is no workspace when just a file but not a folder has been opened.

The workspace offers support for listening to fs events and for finding files. Both perform well and run outside the editor-process so that they should be always used instead of nodejs-equivalents.

Variables

fs: FileSystem

A file system instance that allows to interact with local and remote files, e.g. vscode.workspace.fs.readDirectory(someUri) allows to retrieve all entries of a directory or vscode.workspace.fs.stat(anotherUri) returns the meta data for a file.

name: string | undefined

The name of the workspace. undefined when no folder has been opened.

rootPath: string | undefined

The folder that is open in the editor. undefined when no folder has been opened.

• deprecated - Use workspaceFolders instead.

textDocuments: ReadonlyArray<TextDocument>

All text documents currently known to the system.

workspaceFile: Uri | undefined

The location of the workspace file, for example:

file:///Users/name/Development/myProject.code-workspace

or

untitled:1555503116870

for a workspace that is untitled and not yet saved.

Depending on the workspace that is opened, the value will be:

• undefined when no workspace or a single folder is opened
• the path of the workspace file as Uri otherwise. if the workspace is untitled, the returned URI will use the untitled: scheme

The location can e.g. be used with the vscode.openFolder command to open the workspace again after it has been closed.

Example:

vscode.commands.executeCommand('vscode.openFolder', uriOfWorkspace);

Note: it is not advised to use workspace.workspaceFile to write configuration data into the file. You can use workspace.getConfiguration().update() for that purpose which will work both when a single folder is opened as well as an untitled or saved workspace.

workspaceFolders: ReadonlyArray<WorkspaceFolder> | undefined

List of workspace folders or undefined when no folder is open. Note that the first entry corresponds to the value of rootPath.

Events

onDidChangeConfiguration: Event<ConfigurationChangeEvent>

An event that is emitted when the configuration changed.

onDidChangeTextDocument: Event<TextDocumentChangeEvent>

An event that is emitted when a text document is changed. This usually happens when the contents changes but also when other things like the dirty-state changes.

onDidChangeWorkspaceFolders: Event<WorkspaceFoldersChangeEvent>

An event that is emitted when a workspace folder is added or removed.

onDidCloseTextDocument: Event<TextDocument>

An event that is emitted when a text document is disposed or when the language id of a text document has been changed.

Note 1: There is no guarantee that this event fires when an editor tab is closed, use the onDidChangeVisibleTextEditors-event to know when editors change.

Note 2: A document can be open but not shown in an editor which means this event can fire for a document that has not been shown in an editor.

onDidCreateFiles: Event<FileCreateEvent>

An event that is emitted when files have been created.

Note: This event is triggered by user gestures, like creating a file from the explorer, or from the workspace.applyEdit-api, but this event is not fired when files change on disk, e.g triggered by another application, or when using the workspace.fs-api.

onDidDeleteFiles: Event<FileDeleteEvent>

An event that is emitted when files have been deleted.

Note 1: This event is triggered by user gestures, like deleting a file from the explorer, or from the workspace.applyEdit-api, but this event is not fired when files change on disk, e.g triggered by another application, or when using the workspace.fs-api.

Note 2: When deleting a folder with children only one event is fired.

onDidOpenTextDocument: Event<TextDocument>

An event that is emitted when a text document is opened or when the language id of a text document has been changed.

To add an event listener when a visible text document is opened, use the TextEditor events in the window namespace. Note that:

• The event is emitted before the document is updated in the active text editor
• When a text document is already open (e.g.: open in another visible text editor) this event is not emitted

onDidRenameFiles: Event<FileRenameEvent>

An event that is emitted when files have been renamed.

Note 1: This event is triggered by user gestures, like renaming a file from the explorer, and from the workspace.applyEdit-api, but this event is not fired when files change on disk, e.g triggered by another application, or when using the workspace.fs-api.

Note 2: When renaming a folder with children only one event is fired.

onDidSaveTextDocument: Event<TextDocument>

An event that is emitted when a text document is saved to disk.

onWillCreateFiles: Event<FileWillCreateEvent>

An event that is emitted when files are being created.

Note 1: This event is triggered by user gestures, like creating a file from the explorer, or from the workspace.applyEdit-api. This event is not fired when files change on disk, e.g triggered by another application, or when using the workspace.fs-api.

Note 2: When this event is fired, edits to files that are are being created cannot be applied.

onWillDeleteFiles: Event<FileWillDeleteEvent>

An event that is emitted when files are being deleted.

Note 1: This event is triggered by user gestures, like deleting a file from the explorer, or from the workspace.applyEdit-api, but this event is not fired when files change on disk, e.g triggered by another application, or when using the workspace.fs-api.

Note 2: When deleting a folder with children only one event is fired.

onWillRenameFiles: Event<FileWillRenameEvent>

An event that is emitted when files are being renamed.

Note 1: This event is triggered by user gestures, like renaming a file from the explorer, and from the workspace.applyEdit-api, but this event is not fired when files change on disk, e.g triggered by another application, or when using the workspace.fs-api.

Note 2: When renaming a folder with children only one event is fired.

onWillSaveTextDocument: Event<TextDocumentWillSaveEvent>

An event that is emitted when a text document will be saved to disk.

Note 1: Subscribers can delay saving by registering asynchronous work. For the sake of data integrity the editor might save without firing this event. For instance when shutting down with dirty files.

Note 2: Subscribers are called sequentially and they can delay saving by registering asynchronous work. Protection against misbehaving listeners is implemented as such:

• there is an overall time budget that all listeners share and if that is exhausted no further listener is called
• listeners that take a long time or produce errors frequently will not be called anymore

The current thresholds are 1.5 seconds as overall time budget and a listener can misbehave 3 times before being ignored.

Functions

applyEdit(edit: WorkspaceEdit): Thenable<boolean>

Make changes to one or many resources or create, delete, and rename resources as defined by the given workspace edit.

All changes of a workspace edit are applied in the same order in which they have been added. If multiple textual inserts are made at the same position, these strings appear in the resulting text in the order the ‘inserts’ were made, unless that are interleaved with resource edits. Invalid sequences like ‘delete file a’ -> ‘insert text in file a’ cause failure of the operation.

When applying a workspace edit that consists only of text edits an ‘all-or-nothing’-strategy is used. A workspace edit with resource creations or deletions aborts the operation, e.g. consecutive edits will not be attempted, when a single edit fails.

asRelativePath(pathOrUri: string | Uri, includeWorkspaceFolder?: boolean): string

Returns a path that is relative to the workspace folder or folders.

When there are no workspace folders or when the path is not contained in them, the input is returned.

createFileSystemWatcher(globPattern: GlobPattern, ignoreCreateEvents?: boolean, ignoreChangeEvents?: boolean, ignoreDeleteEvents?: boolean): FileSystemWatcher

Creates a file system watcher.

A glob pattern that filters the file events on their absolute path must be provided. Optionally, flags to ignore certain kinds of events can be provided. To stop listening to events the watcher must be disposed.

Note that only files within the current workspace folders can be watched.

findFiles(include: GlobPattern, exclude?: GlobPattern | null, maxResults?: number, token?: CancellationToken): Thenable<Uri[]>

Find files across all workspace folders in the workspace.

• example - findFiles(‘*/.js’, ‘/node_modules/‘, 10)

getConfiguration(section?: string | undefined, scope?: ConfigurationScope | null): WorkspaceConfiguration

Get a workspace configuration object.

When a section-identifier is provided only that part of the configuration is returned. Dots in the section-identifier are interpreted as child-access, like { myExt: { setting: { doIt: true }}} and getConfiguration('myExt.setting').get('doIt') === true.

When a scope is provided configuration confined to that scope is returned. Scope can be a resource or a language identifier or both.

getWorkspaceFolder(uri: Uri): WorkspaceFolder | undefined

Returns the workspace folder that contains a given uri.

• returns undefined when the given uri doesn’t match any workspace folder
• returns the input when the given uri is a workspace folder itself

openTextDocument(uri: Uri): Thenable<TextDocument>

Opens a document. Will return early if this document is already open. Otherwise the document is loaded and the didOpen-event fires.

The document is denoted by an uri. Depending on the scheme the following rules apply:

• file-scheme: Open a file on disk, will be rejected if the file does not exist or cannot be loaded.
• untitled-scheme: A new file that should be saved on disk, e.g. untitled:c:\frodo\new.js. The language will be derived from the file name.
• For all other schemes contributed text document content providers and file system providers are consulted.

Note that the lifecycle of the returned document is owned by the editor and not by the extension. That means an onDidClose-event can occur at any time after opening it.

openTextDocument(fileName: string): Thenable<TextDocument>

A short-hand for openTextDocument(Uri.file(fileName)).

• see - openTextDocument

openTextDocument(options?: {content: string, language: string}): Thenable<TextDocument>

Opens an untitled text document. The editor will prompt the user for a file path when the document is to be saved. The options parameter allows to specify the language and/or the content of the document.

registerFileSystemProvider(scheme: string, provider: FileSystemProvider, options?: {isCaseSensitive: boolean, isReadonly: boolean}): Disposable

Register a filesystem provider for a given scheme, e.g. ftp.

There can only be one provider per scheme and an error is being thrown when a scheme has been claimed by another provider or when it is reserved.

registerTaskProvider(type: string, provider: TaskProvider): Disposable

Register a task provider.

• deprecated - Use the corresponding function on the tasks namespace instead

registerTextDocumentContentProvider(scheme: string, provider: TextDocumentContentProvider): Disposable

Register a text document content provider.

Only one provider can be registered per scheme.

saveAll(includeUntitled?: boolean): Thenable<boolean>

Save all dirty files.