大家好，我是韋恩，今天是鐵人賽的第八天。

今天，我們來客製化提供給套件使用者的extension個人設定，這個功能在實務上非常有幫助。準備好了嗎？

Workspace設定

在Contribution Point裡，我們可以在configuration為key的物件中設定Workspace的Settings或者是User Settings。在Contribution Point註冊後，我們即可以在preference -> settings的ui上讓user選取或填寫我們的extension設定選項。User也可以透過直接編輯settings.json來配置我們的extension設定。

Workspace的Configutation設定語法概覽如下：

{
...
"contributes": {
        ...
        "configuration": {
          "title": "${Extension專案設定的主標題}",
          "properties": {
            "${套件的Namespace}.${設定選項名稱}": {
              "type": "${使用者輸入資料類型: boolean、string、number...}",
              "default": "${選項預設值}",
              "description": "${選項內容描述}",
              ...
            },
          }
        }
        ...
	},
...
}

Extension Configuration的JSON設定格式涵蓋了JSON Schema的設定方式。JSON Schema是一種對JSON設定檔格式的規範。我們可以直接使用JSON Schema規範內的Property Key來規範使用者可以輸入的資料型態、長度、選項...等等，但Configuration不支援JSON Schema的$ref跟definition這些用於引用外部json檔案的設定，此處需留意。

除了JSON Schema的屬性來限制使用者輸入的資料以外，VSCode還提供了markdownDescriptions、deprecationMessage、 markdownDeprecationMessage、enumDescriptions、markdownEnumDescriptions...等等屬性，讓開發者可以讓使用者讀取到更多設定選項相關的訊息。

其中的markdownDescription，是我覺得相當貼心的一個設定，可以在value裡直接使用markdown語法，vscode會自動將markdown渲染出來，如下所示：

此處Markdown description的寫法請詳見今天的第一個範例喔！

好了，簡單介紹後，讓我們直接來練習這些配置與功能吧！練習才是掌握各項細節的最快途徑。

Day08練習：使用Configration提供客製選項吧！

環境準備

• 使用yoman產生extension專案:

yo code

• 依序輸入專案名稱、id等資訊

如果環境建立有問題，請再次參照之前的教學建立專案與環境喔！

Workspace設定練習：

首先，讓我們到contributes的commands屬性上方，在物件括弧裡輸入""

可以看到vscode自動補全各類contributes的屬性選項，讓我們選擇configuration。

接下來，我們在configuration之後輸入:，會看到跳出兩個補全的屬性選項，

通常我們只會設一個extension title，所以此處我們選第二個選項。

選擇後的結果如上，讓我們繼續輸入我們的title跟properties下面的設定選項吧！

我們輸入title為day08-workspace，properties屬性下面鍵入"day08-workspace.input"做為第一個設定的標題。一樣的，我們再度利用自動補全來列出key值。

上面自動跳出可選的JSON Schema properties，但請注意$ref是不能使用的，記得不要選取這個選項喔！

這裡我們先選擇type，再利用自動補全列出可選的value值

好的，以上這些就是我們可以輸入的所有type的類型。之後就不一一演示了，請讀者練習，並完成下方這樣的設定吧!

一切精髓盡在配置中。

{
    ...
    "configuration":{
			"title": "Day08-Workspace",
			"properties": {
				"day08-workspace.input": {
					"type": "string",
					"default": "defaultValue",
					"description": "provide a input for accepting value"
				},
				"day08-workspace.inputNum": {
					"type": "number",
					"default": "1.001",
					"description": "provide a input for accepting number"
				},
				"day08-workspace.inputInt": {
					"type": "integer",
					"default": "1",
					"markdownDescription": "MarkdownDescription: provide a input for accepting integer, See the [VSCode Docs (https://code.visualstudio.com/api/references/contribution-points#contributes.configuration) for more details.\n - a: item1\n - b: itemb"
				},
				"day08-workspace.checkbox": {
					"type": "boolean",
					"default": "0",
					"description": "provide a checkbox"
				},
				"day08-workspace.dropdown": {
					"type": "string",
					"default": "defaultValue",
					"enum": [
						"optionA",
						"optionB",
						"optionC"
					],
					"description": "provide a dropdown and options",
					"enumDescriptions": [
						"description for option A",
						"description for option B",
						"description for option C"
					]
				},
				"day08-workspace.array": {
					"type": "array",
					"default": [
						"defaultValue"
					],
					"description": "array settings is only available at settings.json"
				},
				"day08-workspace.object": {
					"type": "object",
					"default": { 
						"key" : "defaultValue"
					},
					"description": "object settings is only available at settings.json"
				},
				"day08-workspace.null.a": {
					"type": null,
					"default": null,
					"description": "null settings for showing group feature"
				},
				"day08-workspace.null.b": {
					"type": null,
					"default": null,
					"description": "null settings for showing group feature"
				}
			}
    }
    ...
}

範例成果檢視

照以上輸入完後，我們按F5執行extension，並置user settings頁面的extension下方，可以找到VSCode的Day08-Workspace設定，並可以看到各個不同type型態對應的UI元件，是不是很有趣呢?

以上是第一個範例的成果展示，讓我們再這個範例元件上檢視幾個貼心的小功能吧！

• 輸入錯誤型態跳出提示

當我們在元件輸入不合法的型態，輸入框下話自動跳出提示警告。此處我們設定的輸入框需為整數，不能有小數點。

• 下拉選單選項描述

下拉選單的enum選項可以另外配置enumDescription，讓我們可以針對每一個選項提供個別的說明。除了enumDescription外，vscode特別準備了markdownEnumDescriptions，這裡故意不多做說明，希望讀者能夠動手練習，培養舉一反三的能力，進而對這些api運用自如！

範例元件有許多小細節，讀者們請務必動手玩玩看，從中熟悉api的設定跟小撇步。若有問題，請隨時在留言板發問，我會與您一銅解決單元練習時所遇到的問題，

取得使用者Workspace設定

好啦，現在，我們已經知道如何配置給使用者輸入資料的元件了。但作為一個extension開發者，我們會如何取得workspace的設定呢?為此，今天我們準備了另一個相關命令小練習，請讀者們按順序配置吧！

• 設定Command：

首先，讓我們設定一個getSettings命令，如下所示：

{
    ...
    "contributes": {
		"commands": [
            {
				"command": "day08-workspace-api.getSettings",
				"title": "Day08: GetSettings"
			}
		]
	},
    ...
}

• 專案extension.ts範例程式配置：

命令配置後，我們在extension.ts這裡，可以使用workspace下面的getConfiguration方法，提供給定的namespace取得設定。
​

import * as vscode from 'vscode';
​
export function activate(context: vscode.ExtensionContext) {
​
	console.log('Congratulations, your extension "day08-workspace-api" is now active!');
 
    let getCmd = vscode.commands.registerCommand('day08-workspace-api.getSettings', async () => {
			const workspaceSettings = vscode.workspace.getConfiguration('day08-workspace');
			console.log(workspaceSettings);
	});

	context.subscriptions.push(getCmd);
​
export function deactivate() {}

• 執行Day08: GetSettings

執行命令後，我們可以看到取得的設定結果。

總結

總算結束啦，今天，我們練習配置了Workspace的各種選項，並利用簡單的命令取得了Workspace的Settings，Workspace設定是使用者常使用的功能，並且它的api使用仍有不少細節可以發掘喔!

明天，我們將會探討如何在本地儲存extension使用者的資料，也會更將其與workspace api做個比較說明，敬請期待吧，我們明天見，掰掰！

本日參考文件

• Contribution Points