Link Search Menu Expand Document


=== workspace




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.


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

rootPath, deprecated

textDocuments: ReadonlyArray

workspaceFile: Uri | undefined

  • The location of the workspace file, for example:

  • eg:

    • file:///Users/name/Development/myProject.code-workspace
  • eg:note saved

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

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

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


onDidCreateFiles: Event

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.

onDidChangeTextDocument: Event

  • TextDocumentChangeEvent: Uri


  • 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


  • Event

  • this event is not fired when files change on disk, e.g triggered by another application, or when using the workspace.fs-api.

  • FileRenameEvent:

    • files: ReadonlyArray<{newUri: Uri, oldUri: Uri}>

onWillCreateFiles: Event

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

onWillSaveTextDocument: Event

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.



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

  • params

    • globPattern: A glob pattern that is applied to the absolute paths of created, changed, and deleted files. Use a relative pattern to limit events to a certain workspace folder.
  • note

    • only files within the current workspace folders can be watched #star
    • does not respect files.exclude setting, need to add watcher.exclude
    • only checks for changes made by vscode (eg. using vim and editing won't update the watcher)


  • signature
  include: GlobPattern, 
  exclude?: GlobPattern | null, 
  maxResults?: number, 
  token?: CancellationToken
): Thenable<Uri[]>
  • Find files across all workspace folders in the workspace.

  • eg:

findFiles("**/*.js", "**/node_modules/**", 10);


  • sig
(uri: Uri): WorkspaceFolder | undefined
  • return
    • 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


  • sig:
openTextDocument(uri: Uri): Thenable<TextDocument>
  • sig3
    • opens untitled document
openTextDocument(options?: {content: string, language: string}): 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.

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.


(decorationType: TextEditorDecorationType, rangesOrOptions: Range[] | DecorationOptions[]): void


  • signature
(start: number, deleteCount: number | undefined | null, ...workspaceFoldersToAdd: {name: string, uri: Uri}[]): boolean
  • params

    • start: the zero-based location in the list of currently opened workspace folders from which to start deleting workspace folders.
    • deleteCount: the optional number of workspace folders to remove.
    • workspaceFoldersToAdd: the optional variable set of workspace folders to add in place of the deleted ones. Each workspace is identified with a mandatory URI and an optional name.
  • return: boolean

    • true if the operation was successfully started and false otherwise if arguments were used that would result in invalid workspace folder state (e.g. 2 folders with the same URI).
  • eg: remove 1st ws folder

workspace.updateWorkspaceFolders(0, 1);
  • eg: replace existing ws folder
workspace.updateWorkspaceFolders(0, 1, { uri: ...});

  • note
    • It is valid to remove an existing workspace folder and add it again with a different name to rename that folder.
    • it is not valid to call updateWorkspaceFolders() multiple times without waiting for the onDidChangeWorkspaceFolders() to fire.



  • The clipboard provides read and write access to the system's clipboard.


  • A code action represents a change that can be performed in code, e.g. to fix a problem or to refactor code.


  • A code lens provider adds commands to source text. The commands will be shown as dedicated horizontal lines in between the source text.


  • Represents a reference to a command. Provides a title which will be used to represent a command in the UI and, optionally, an array of arguments which will be passed to the command handler function when invoked.


A comment is displayed within the editor or the Comments Panel, depending on how it is provided.



Completions that are triggered at the end of a word usually replace that word. However when completions are triggered inside words, it's not clear if the word-end should be replaced or not. Depending on the preference of the extension author, users get the one behavior or the other. That's not ideal and now there is an API to express the insert and replace ranges for a completion item.

For that, we have added a new OR-type to CompletionItem#range:

export class CompletionItem {
  range?: Range | { inserting: Range; replacing: Range };

  1. If the range is undefined, then VS Code uses the current word range for replacing and the same range cropped at the cursor position for inserting.
  2. If the range is a simple vscode.Range, then VS Code knows there is only one location for inserting or replacing.
  3. If the range is an object with inserting and replacing ranges, VS Code will use them directly.

This information is used in combination with editor.suggest.insertMode setting that allows users to define their preference. We ask extension authors to please adopt this API quickly because we have plans to make insert and replace behavior more visible in the next release.


resolveCompletionItem?(item: T, token: CancellationToken): ProviderResult;


  • Providers can delay the computation of

  • properties that are needed for the initial sorting and filtering, like sortText, filterText, insertText, and range, must not be changed during resolve.

  • Providers are asked for completions either explicitly by a user gesture or -depending on the configuration-implicitly when typing words or trigger characters.

  • release notes

    The CompletionItemProvider#resolveCompletionItem function allows providers to lazily enrich completions with more data. This "lazy" data must be optional and must not change the insert behavior of completions. Extensions can still fill in additionalTextEdits and if additional edits arrive after a completion has been inserted, the editor will still attempt to apply them. Note that this only applies to additional edits, not to the main edit (insertText) which must not change once provided.



Text based custom editors use a TextDocument as their data model. This considerably simplifies implementing a custom editor as it allows VS Code to handle many common operations such as undo and backup. The provider is responsible for synchronizing text changes between the webview and the TextDocument.


  • Represents a type which can release resources, such as event listening or a timer


new(callOnDispose: Function)


  • denotes a document by different properties like the language, the scheme of its resource, or a glob-pattern that is applied to the path.
  • eg: A language filter that applies to typescript files on disk: { language: 'typescript', scheme: 'file' }
  • eg2: A language filter that applies to all package.json paths: { language: 'json', scheme: 'untitled', pattern: '**/package.json' }


  • range inside a text document which deserves special attention. Usually a document highlight is visualized by changing the background color of its range.
  • range in a text document that links to an internal or external resource, like another text document or a web site.


  • Represents an end of line character sequence in a document.


Describes what to do when pressing Enter.


  • Represents a typed event

  • eg: A function that represents an event to which you subscribe by calling it with a listener function as argument.

item.onDidChange(function (event) {
  console.log("Event happened: " + event);


These collections are extension and workspace-specific and VS Code handles how conflicts between multiple extensions are dealt with. They are persisted across window reloads such that terminals created immediately after the window is loaded do not block on the extension host launching but instead use the last known version. These persisted collections are removed by disposing of the collection or when the extension is uninstalled.

When collections change, an indicator will appear on the terminal. Whether this indicator shows for any active change or just for "stale" terminals is defined by the terminal.integrated.environmentChangesIndicator setting. This API is now also used by the built-in Git extension to let VS Code be an authentication provider.

const collection = context.environmentVariableCollection;
const separator = process.platform === "win32" ? ";" : ":";
collection.prepend("PATH", `/foo${separator}`);
collection.replace("JAVA_HOME", "/bar");



  • #extensions

  • collection of utilities private to an extension.

  • prod

  "level": 30,
  "time": 1593449542864,
  "pid": 75542,
  "hostname": "Kevins-MacBook-Pro.local",
  "name": "dendron",
  "ctx": "activate",
  "logPath": "/Users/kevinlin/Library/Application Support/Code - Insiders/logs/20200628T153037/exthost10/dendron.dendron-plugin-core",
  "extensionPath": "/Users/kevinlin/.vscode-insiders/extensions/dendron.dendron-plugin-core-0.2.4",
  "extensionUri": {
    "$mid": 1,
    "fsPath": "/Users/kevinlin/.vscode-insiders/extensions/dendron.dendron-plugin-core-0.2.4",
    "path": "/Users/kevinlin/.vscode-insiders/extensions/dendron.dendron-plugin-core-0.2.4",
    "scheme": "file"
  "storagePath": "/Users/kevinlin/Library/Application Support/Code - Insiders/User/workspaceStorage/8404fce9717101a619601cf71dca457f/dendron.dendron-plugin-core",
  "globalStoragePath": "/Users/kevinlin/Library/Application Support/Code - Insiders/User/globalStorage/dendron.dendron-plugin-core"
  • 1st run
  "logPath": "/Users/kevinlin/Library/Application Support/Code/logs/20200624T200601/exthost137/dendron.@dendronhq/plugin-core",
  "extensionPath": "/Users/kevinlin/projects/dendronv2/dendron/packages/plugin-core",
  "extensionUri": {
    "$mid": 1,
    "fsPath": "/Users/kevinlin/projects/dendronv2/dendron/packages/plugin-core",
    "path": "/Users/kevinlin/projects/dendronv2/dendron/packages/plugin-core",
    "scheme": "file"
  "storagePath": "/Users/kevinlin/Library/Application Support/Code/User/workspaceStorage/60a7b37c990c01aec0c916623495a0b7/dendron.@dendronhq/plugin-core",
  "globalStoragePath": "/Users/kevinlin/Library/Application Support/Code/User/globalStorage/dendron.@dendronhq/plugin-core"
  • 2nd run
  "logPath": "/Users/kevinlin/Library/Application Support/Code/logs/20200624T200601/exthost137/dendron.@dendronhq/plugin-core",
  "extensionPath": "/Users/kevinlin/projects/dendronv2/dendron/packages/plugin-core",
  "extensionUri": {
    "$mid": 1,
    "fsPath": "/Users/kevinlin/projects/dendronv2/dendron/packages/plugin-core",
    "path": "/Users/kevinlin/projects/dendronv2/dendron/packages/plugin-core",
    "scheme": "file"
  "storagePath": "/Users/kevinlin/Library/Application Support/Code/User/workspaceStorage/60a7b37c990c01aec0c916623495a0b7/dendron.@dendronhq/plugin-core",
  "globalStoragePath": "/Users/kevinlin/Library/Application Support/Code/User/globalStorage/dendron.@dendronhq/plugin-core"



  • use:
    • to delete key, set value to undefined


  • good option if you need to store large files that are accessible from all workspaces.
  • VS Code takes care of cleaning up this path when the extension is removed.
 * An absolute file path in which the extension can store global state.
 * The directory might not exist on disk and creation is
 * up to the extension. However, the parent directory is guaranteed to be existent.
 * Use [`globalState`](#ExtensionContext.globalState) to store key value data.
globalStoragePath: string;

logPath: string

An absolute file path of a directory in which the extension can create log files. The directory might not exist on disk and creation is up to the extension. However, the parent directory is guaranteed to be existent.



asAbsolutePath(relativePath: string): string`
  • eg: "/Users/kevinlin/projects/vscode-extension/dendron/foo.exists"


  • can be used to create and manage an event for others to subscribe to. One emitter always owns one event
  • Use this class if you want to provide event from within your extension, for instance inside a TextDocumentContentProvider or when providing API to other extensions


id: a6fc2f9c-259f-4dc5-8b3c-124eff389441

Represents an extension.


exports: T

  • public API of extension
  • NOTE: extension must be activated before accessing thisf field

isActive: bool


  • parsed contents of package


activate: Promise

  • activate extension and return public API



The file system interface exposes the editor's built-in and contributed file system providers. It allows extensions to work with files from the local disk as well as files from remote places, like the remote extension host or ftp-servers.

Note that an instance of this interface is available as workspace.fs


  • defines what the editor needs to read, write, discover, and to manage files and folders
  • allows extensions to serve files from remote places, like ftp-servers, and to seamlessly integrate those into the editor
  • notes:
    • works with uris and assumes hierarchical paths, e.g. foo:/my/path is a child of foo:/my/ and a parent of foo:/my/path/deeper.
    • activation event onFileSystem: that fires when a file or folder is being accessed.
    • 'file' is often used to denote all kinds of files, e.g. folders, symbolic links, and regular files.



  • event to signal that a resource has been created, changed, or deleted


copy(source: Uri, destination: Uri, options: {overwrite: boolean}): void | Thenable

createDirectory(uri: Uri): void | Thenable

delete(uri: Uri, options: {recursive: boolean}): void | Thenable

readDirectory(uri: Uri): [string, FileType][] | Thenable<[string, FileType][]>

readFile(uri: Uri): Uint8Array | Thenable

rename(oldUri: Uri, newUri: Uri, options: {overwrite: boolean}): void | Thenable

stat(uri: Uri): FileStat | Thenable

watch(uri: Uri, options: {excludes: string[], recursive: boolean}): Disposable

writeFile(uri: Uri, content: Uint8Array, options: {create: boolean, overwrite: boolean}): void | Thenable


  • Enumeration of file types. The types File and Directory can also be a symbolic links, in that case use FileType.File | FileType.SymbolicLink and FileType.Directory | FileType.SymbolicLink.






  • either be a glob pattern string (like */.{ts,js} or *.{ts,js}) or a relative pattern

A file glob pattern to match file paths against. This can either be a glob pattern string (like */.{ts,js} or *.{ts,js}) or a relative pattern.

Glob patterns can have the following syntax:

* to match one or more characters in a path segment
? to match on one character in a path segment
** to match any number of path segments, including none
{} to group conditions (e.g. **/*.{ts,js} matches all TypeScript and JavaScript files)
[] to declare a range of characters to match in a path segment (e.g., example.[0-9] to match on example.0, example.1, …)
[!...] to negate a range of characters to match in a path segment (e.g., example.[!0-9] to match on example.a, example.b, but not example.0)

Note: a backslash () is not valid within a glob pattern. If you have an existing file path to match against, consider to use the relative pattern support that takes care of converting any backslash into slash. Otherwise, make sure to convert any backslash to slash when creating the glob pattern.


  • additional information for a symbol or word. Hovers are rendered in a tooltip-like widget



  • contract between extensions and the go to implementation feature.


  • concrete QuickInput to let the user input a text value.
  • 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



  • An output channel is a container for readonly textual information.


  • Represents a line and character position, such as the position of the cursor.

  • Position objects are immutable. Use the with or translate methods to derive new positions from an existing position.



  • #window


We've added a new option to the ProgressOptions.location of the window.withProgress API to allow progress to be shown on a specific view. To use, set ProgressOptions.location = { viewId: <view-id> }; where <view-id> specifies the ID of the view you'd like to show progress for. There is short video of this in action in the view progress section above.


  • A provider result represents the values a provider, like the HoverProvider, may return
  • this is the actual result type T, like Hover, or a thenable that resolves to that type T. In addition, null and undefined can be returned - either directly or from a thenable



  • user input UI that is initially not visible

  • After configuring it through its properties the extension can make it visible by calling

  • A user pressing Enter or some other gesture implying acceptance of the current state does not automatically hide this UI componen

  • When the extension no longer needs this input UI, it should QuickInput.dispose

  • consider using window.showInputBox


  • Represents an item that can be selected from a list of items.




  • type: boolean

If the UI should show a progress indicator. Defaults to false. Change this to true, e.g., while loading more data or validating user input.

label: string

description?: string

A human-readable string which is rendered less prominent in the same line. Supports rendering of theme icons via the $()-syntax.

detail?: string

A human-readable string which is rendered less prominent in a separate line. Supports rendering of theme icons via the $()-syntax.

picked?: boolean

Optional flag indicating if this item is picked initially. (Only honored when the picker allows multiple selections.)







  • template which allows to insert text and to control the editor cursor when insertion happens.



Represents a text document, such as a source file. Text documents have lines and knowledge about an underlying resource like a file.


export interface TextDocumentContentChangeEvent {
     * The range that got replaced.
    readonly range: Range;
     * The offset of the range that got replaced.
    readonly rangeOffset: number;
     * The length of the range that got replaced.
    readonly rangeLength: number;
     * The new text for the range.
    readonly text: string;


An event that is fired when a document will be saved.

To make modifications to the document before it is being saved, call the waitUntil-function with a thenable that resolves to an array of text edits.


document: TextDocument reason: TextDocumentSaveReason



  • sig: (thenable: Thenable<TextEdit[]>): void
workspace.onWillSaveTextDocument(event => {
    // async, will *throw* an error
    setTimeout(() => event.waitUntil(promise));

    // sync, OK


A text edit represents edits that should be applied to a document.



Perform an edit on the document associated with this text editor.

The given callback-function is invoked with an edit-builder which must be used to make edits. Note that the edit-builder is only valid while the callback executes.

  • sig
(callback: (editBuilder: TextEditorEdit) => void, options?: {undoStopAfter: boolean, undoStopBefore: boolean}): Thenable<boolean>


A complex edit that will be applied in one transaction on a TextEditor. This holds a description of the edits and if the edits are valid (i.e. no overlapping regions, document was not changed in the meantime, etc.) they can be applied on a document associated with a text editor.



  • codicons:

  • A reference to a named icon

  • Currently, File, Folder, and codicons are supported

  • Using a theme icon is preferred over a custom icon as it gives theme authors the possibility to change the icons.

  • Note that theme icons can also be rendered inside labels and descriptions

  • Places that support theme icons spell this out and they use the $()-syntax, for instance quickPick.label = "Hello World $(globe)".


localResourceRoots?: ReadonlyArray

Root paths from which the webview can load local (filesystem) resources using uris from asWebviewUri

Default to the root folders of the current workspace plus the extension's install directory.

Pass in an empty array to disallow access to any local resources.


Restore webview panels that have been persisted when vscode shuts down.

There are two types of webview persistence:

Persistence within a session.
Persistence across sessions (across restarts of VS Code).

A WebviewPanelSerializer is only required for the second case: persisting a webview across sessions.


  • merge of
    • Default Settings
    • Global (User) Settings
    • Workspace settings
    • Workspace Folder settings - From one of the Workspace Folders under which requested resource belongs to.
    • Language settings - Settings defined under requested language.



  • sig: update(section: string, value: any, configurationTarget?: ConfigurationTarget | boolean, overrideInLanguage?: boolean): Thenable<void>
  • Note: To remove a configuration value use undefined, like so: config.update('somekey', undefined)
  • params:
  • throws - error while updating configuration which is not registered. window configuration to workspace folder configuration to workspace or workspace folder when no workspace is opened. configuration to workspace folder when there is no workspace folder settings. configuration to workspace folder when WorkspaceConfiguration is not scoped to a resource.



  • sig
replace(uri: Uri, range: Range, newText: string, metadata?: WorkspaceEditEntryMetadata): void

Table of contents