大家好，我是韋恩，今天是鐵人賽的第五天，今天，我們將開始第一個extension專案，並練習使用VSCode的Command命令。

開發環境配置

在開始前，請照下方指示正確設置自己的環境。

1. 確認已安裝nodejs與npm:

node -v && npm -v 

如果正確安裝了以上兩者，會跳出兩行版本號資訊。

如未安裝兩者，請先至Nodejs官方網站下載。npm會隨著nodejs下載一併被安裝，有時候您可能使用過舊的npm，這時您可以使用以下指令更新它到最新版。

npm install -g npm@latest

2. 安裝yoman

[圖片來源：yoman官網截圖]

Yoman是一款流行已久的code generator，可以允許我們使用yoman設置專案的樣板，
並讓我們使用yo指令快速產生樣板專案。

[圖片來源：yoman官網截圖]

VSCode官方已經發布了VSCode Yoman專案，並且定期更新，因此我們可以直接使用yo指令產生VSCode Extension，無需手動開發yoman樣板。

請使用以下指令安裝yoman與VSCode Extension Generator:

npm install -g yo generator-code

安裝yoman後，再次使用版本號指令確認有無正確安裝：

yo --version

使用yo快速產生第一個Extesnion專案

首先，於terminal進入一個要放置專案的資料夾，使用

yo code

指令，generator會跳出提示，讓我們選擇要產生的extension種類：

這些Extension選項的描述與說明如下：

請選擇第一個New Extension(Typescript)選項，選後yo會請我們輸入extensnion name

這裡我們輸入: day05-first-command

輸入完成後，會再輸入id、description、是否要使用git、使用yarn還是npm開發，我們依序輸入如下：

輸入完成後，yoman即會開始幫我們產生extension，並使用npm或yarn安裝必須的node_modules。

全部完成後，在terminal輸入

cd day-05-first-command

讓terminal的根路徑位於專案資料夾。

Extension專案重點相關檔案介紹

現在，讓我們使用VSCode打開新產生的專案資料夾吧，打開後，我們會看到一個nodejs的typescript專案，結構如下：

    ├── .vscode
    │   ├── extensions.json
    │   ├── launch.json
    │   ├── settings.json
    │   └── tasks.json
    ├── node_modules
    ├── src
    │   ├── extension.ts
    │   └── test
    │       ├── runTest.ts
    │       └── suite
    │           ├── extension.test.ts
    │           └── index.ts
    ├── .eslintrc.json
    ├── .gitignore
    ├── .vscodeignore
    ├── CHANGELOG.md
    ├── README.md
    ├── package-lock.json
    ├── package.json
    ├── tsconfig.json
    └── vsc-extension-quickstart.md

• workspace設定(位於.vscode資料夾下)

• 主程式檔案： 位於src資料夾下方的extension.ts。
• 測試程式：位於src/test資料夾下方的檔案。
• .eslintrc.json: 用於extension專案的eslint設置。
• .vscodeignore: 用於忽略不打包進發佈套件的專案檔案。
• tsconfig.json: 用於專案ts compiler的設定選項。
• package.json: 用於配置node相關依賴與相關npm script，在extension專案裡，package.json亦用於配置extension重要相關設定(詳見: Extension Manifest)
• vsc-extension-quickstart.md：產生的extension專案的markdown說明文件。

Extension專案程式簡介

讓我們打開extension.ts吧，打開後可以看見extension.ts裡面有個
active function跟deactive function。

active function為extension程式的進入點。當extension被active事件啟動時，即會執行extension程式。

因此我們可以查看pakcage.json，package.json配置了activeEvents清單，可以看到清單裡列出跟active有關的設定activationEvents。

   {
    ...
	"activationEvents": [
		"onCommand:day05-first-command.helloWorld"
	],
    ...
   }

activationEvents指定了一個hello worldcommand，此即是說，當使用者執行hello world command時，extension即會活躍並執行active function。

此處的onCommand語法為：

onCommand: ${commandId}

那麼，command的id是在哪裡配置的呢? 一樣是在package.json裡，我們可以到contributes屬性(Contribution Point: 詳見Contribution Point)下面查看：

{
    ...
	"contributes": {
		"commands": [
			{
				"command": "day05-first-command.helloWorld",
				"title": "Hello World"
			}
		]
	},
    ...
} 

可以看到在contrubutes屬性下面已經配置了commands清單，裡面條列著一個command設定，此處command設定的語法為

{
   /**
    * 被產生的Command會預設使用extension的id作為namespace，亦可自訂其他Namespace名稱
    */
   "command": ${自定義的command-id},
   "title": ${Command的標題內容}
}

當我們使用Command Palette搜尋Command並執行時，是使用Command的Title搜尋。

好，現在我們已經了解如何在Contribution Point設定簡單的Command id跟title，以及設定它為活躍extension的event。現在回到extension.ts的active function吧!

export function activate(context: vscode.ExtensionContext) {
    ...
	console.log('Congratulations, your extension "ithome" is now active!');
    ...
	let disposable = vscode.commands.registerCommand('day05-first-command.helloWorld', () => {
        ...
		vscode.window.showInformationMessage('Hello World from day05-first-command!');
	});
    ...
	context.subscriptions.push(disposable);
}

我們可以看到，active function裡面在extenions活躍後將註冊我們在Contribution Point那邊設定的command id，並且有一個callback函式，當我們配置的command執行之後，即會在vscode裡跳出顯示「 Hello World from day05-first-command! 」的訊息。

這個註冊過後的command函式(disposable)會再push進extension context裡面，如此當extension被關閉後，VSCode就可以自動釋放listen這個command的相關資源。

執行extension專案應用程式

讓我們來執行extension吧，vscode專案已經幫我們配置好了lanunch.json，因此我們可以在debug mode裡執行extension。讓我們點開左上角Activity bar的第四個icon，再點擊sidebar上方的Run Extension旁的執行按鈕開始extension吧！(此處的快捷鍵為F5)

執行後，vscode會開啟一個新的vscode的window視窗，window視窗上的title會註明這個視窗為[Extension Development Host]，我們可以在這個視窗操作我們開發中的extension，並且使用中斷點偵錯。

• 檢查已被註冊的command

先來檢查一下剛才註冊的command，在Contribution Point裡宣告的Command，一樣在Keyboard Shortcuts下方可以搜尋的到。讓我們照昨天的教學先進入keyboard shortcuts頁中，並在搜尋條上輸入day05，使用extension id來列出剛才註冊的command。

輸入後我們可以看到，Command已正確被註冊。

• 執行註冊後的Command

現在，我們打開Command Palette，輸入hello world，使用註冊的Command Title查找到command。

然後，點擊下去，我們可以看到vscode的window正確跳出「 Hello World from day05-first-command! 」訊息。

然後，我們回到原本專案的Vscode Window，我們可以在專案的debug console檢視active function下面的console.log訊息。

結語

好啦，今天，我們已經建立並了解最基本的extension專案的架構，我們也註冊並執行了我們的第一個Command，明天我們來了解怎麼使用command api並且實際練習。

我們明天見，謝謝大家。

話說，今天的主題相當基本，可是居然花了我超過6000個字，我有很多想說的還沒說完啊啊! 從此處可以想見寫詳細的說明與文件真的相當的不容易呢，感謝所有文件跟教學的撰寫者們。

參考文件

• Extension官方文件