Represents the configuration. It is a merged view of

  • Default Settings
  • Global (User) Settings
  • Workspace settings
  • Workspace Folder settings - From one of the {@link workspace.workspaceFolders Workspace Folders} under which requested resource belongs to.
  • Language settings - Settings defined under requested language.

The effective value (returned by {@linkcode WorkspaceConfiguration.get get}) is computed by overriding or merging the values in the following order.

`defaultValue` (if defined in `package.json` otherwise derived from the value's type)
`globalValue` (if defined)
`workspaceValue` (if defined)
`workspaceFolderValue` (if defined)
`defaultLanguageValue` (if defined)
`globalLanguageValue` (if defined)
`workspaceLanguageValue` (if defined)
`workspaceFolderLanguageValue` (if defined)

Note: Only object value types are merged and all other value types are overridden.

Example 1: Overriding

defaultValue = 'on';
globalValue = 'relative'
workspaceFolderValue = 'off'
value = 'off'

Example 2: Language Values

defaultValue = 'on';
globalValue = 'relative'
workspaceFolderValue = 'off'
globalLanguageValue = 'on'
value = 'on'

Example 3: Object Values

defaultValue = { "a": 1, "b": 2 };
globalValue = { "b": 3, "c": 4 };
value = { "a": 1, "b": 3, "c": 4 };

Note: Workspace and Workspace Folder configurations contains launch and tasks settings. Their basename will be part of the section identifier. The following snippets shows how to retrieve all configurations from launch.json:

// launch.json configuration
const config = workspace.getConfiguration('launch', vscode.workspace.workspaceFolders[0].uri);

// retrieve values
const values = config.get('configurations');

Refer to Settings for more information.

Fields

update(section:String, value:Any, ?configurationTarget:EitherType<ConfigurationTarget, Bool>, ?overrideInLanguage:Bool):Thenable<Void>

Update a configuration value. The updated configuration values are persisted.

A value can be changed in

  • {@link ConfigurationTarget.Global Global settings}: Changes the value for all instances of the editor.
  • {@link ConfigurationTarget.Workspace Workspace settings}: Changes the value for current workspace, if available.
  • {@link ConfigurationTarget.WorkspaceFolder Workspace folder settings}: Changes the value for settings from one of the {@link workspace.workspaceFolders Workspace Folders} under which the requested resource belongs to.
  • Language settings: Changes the value for the requested languageId.

Note: To remove a configuration value use undefined, like so: config.update('somekey', undefined)

@link ConfigurationTarget configuration target} or a boolean value.

- If `true` updates {@link ConfigurationTarget.Global Global settings}.
- If `false` updates {@link ConfigurationTarget.Workspace Workspace settings}.
- If `undefined` or `null` updates to {@link ConfigurationTarget.WorkspaceFolder Workspace folder settings} if configuration is resource specific,
otherwise to {@link ConfigurationTarget.Workspace Workspace settings}.

@link WorkspaceConfiguration} is not scoped to a resource.

Parameters:

section

Configuration name, supports dotted names.

value

The new value.

configurationTarget

The {

overrideInLanguage

Whether to update the value in the scope of requested languageId or not. - If true updates the value under the requested languageId. - If undefined updates the value under the requested languageId only if the configuration is defined for the language.

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 {

inspect<T>(section:String):Null<{workspaceValue:Null<T>, workspaceLanguageValue:Null<T>, workspaceFolderValue:Null<T>, workspaceFolderLanguageValue:Null<T>, languageIds:Null<Array<String>>, key:String, globalValue:Null<T>, globalLanguageValue:Null<T>, defaultValue:Null<T>, defaultLanguageValue:Null<T>}>

Retrieve all information about a configuration setting. A configuration value often consists of a default value, a global or installation-wide value, a workspace-specific value, folder-specific value and language-specific values (if {@link WorkspaceConfiguration} is scoped to a language).

Also provides all language ids under which the given configuration setting is defined.

Note: The configuration name must denote a leaf in the configuration tree (editor.fontSize vs editor) otherwise no result is returned.

Parameters:

section

Configuration name, supports dotted names.

Returns:

Information about a configuration setting or undefined.

has(section:String):Bool

Check if this configuration has a certain value.

Parameters:

section

Configuration name, supports dotted names.

Returns:

true if the section doesn't resolve to undefined.

get<T>(section:String):Null<T>

get<T>(section:String, defaultValue:T):T

Return a value from this configuration.

Parameters:

section

Configuration name, supports dotted names.

Returns:

The value section denotes or undefined.