# 來點 VScode Extension

VScode 使用者一定會安裝各種 Extension 來建立一個適合自己的開發環境，而這些強大的 Extension 大部分都由世界各地的愛用者開發並發布(publish) ，一切都是為了要讓 VSCode 更加實用上手甚至美觀

這篇就是要分享如何建立並發佈一個 Extension
英文程度不錯的建議直接閱讀[官方文件](https://code.visualstudio.com/api/get-started/your-first-extension)，會有更加詳細的解說

## 建立專案 Build

首先安裝`npm install -g yo generator-code`
在要建立專案的資料夾內執行

`yo code`


接著照著步驟填寫

> ? What type of extension do you want to create? New Extension (JavaScript)

選擇你要建立的專案類型
這裡我選擇 New Extension (JavaScript) 來個最普通的先

> ? What’s the name of your extension? ExampleForMedium

Extension名稱: 對應到 package.json `"displayName"`

> ? What’s the identifier of your extension? exampleformedium

描述: 對應到 package.json `"description"`

> ? Enable JavaScript type checking in ‘jsconfig.json’? Yes

是否要建立使用類型檢查檔案 jsconfig.json

> ? Initialize a git repository? No

是否要為此專案初始化一個 git repo。只是演示就不建立了

> ? Which package manager to use? yarn

npm 或者 yarn 二選一

建立成功

`cd exampleformedium` 進入專案資料夾
`code .` 用 vscode 打開你的專案

### 執行與開發 Development

恭喜！Extension 已經建立成功
可以開始開發與執行你的 Extension 了


按下`F5` 開始debug模式

長這樣

可以看到下方多了紅色一條，與Debug Console被打開了，console.log出來的資訊 都可以在這裡看到。VScode也會開啟另一個新視窗，並預設載入 Extension 了，讓我們來跑跑看官方給的 `Hello World`吧



到這裡，你已經可以開始開發了！
參考 [官方API文件](https://code.visualstudio.com/api/references/vscode-api)

打包與發佈 Package & Publish
[官方文件](https://code.visualstudio.com/api/working-with-extensions/publishing-extension)

## VSCE

使用 `vsce` 來打包與發佈自己的專案
安裝`npm i -g vsce` 後，cd 到 Extension 的資料夾內，準備打包吧

cd exampleformedium
vsce package

下完指令後你會得到一堆錯誤
得一一解開才能成功的打包


> Missing publisher name

忘記設定發佈器名稱了，請到 package.json 內加上 `"publisher": "publisher name"` 。發佈器需要使用 `vsce create-publisher` 建立並輸入 token 下面會有詳細的步驟

> Make sure to edit the README.md file before you package or publish your extension.

打包判斷到 README.md 從沒被修改過，README.md 就是這隻 Extension 的操作手冊，一定要好好的撰寫喔


> WARNING A ‘repository’ field is missing from the ‘package.json’ manifest file.

你還沒填寫你的 git 網址呢，如果有把他發在 github 上的話就把網址貼到 package.json 內吧

{
    "repository": {
      "type": "git",
      "url": "https://github.com/your_account/github_project_name"
    }
}


代表你完成打包了！可以準備發佈囉

### 發佈

輸入 `vsce publish` 就可以發佈你的第一個版本的Extension
也記得要到 package.json 內設定 version 你的第一個版本號


***記住！每次發佈都要幫版本號加一下***


是的！哪有那麼容易，我們又遇到問題了
vsce 要求 **Personal Access Token** 個人訪問金鑰

以下的步驟圖片來源為[官方說明文件](https://code.visualstudio.com/api/working-with-extensions/publishing-extension#get-a-personal-access-token)
首先請到 https://dev.azure.com/vscode 申請帳號並登入
在右上角打開Personal access tokens 頁面


點選 New Token 按鈕


給這個新Token一個名字，過期時間
重點是 Organization 請選擇 `All accessiable organization`
點選 Custom defined 並點選 Show all scopes 打開所有選項


找到 Marketplace 項目勾選 Acquire 與 Manage 後點選 Create


然後你會得到一個 Token 請複製下來

### 發佈器 Publisher

建立一個 Publisher 用來儲存發佈的 Token ，請在`package.json` 中指定要使用的發佈器`"publisher": (publisher name)`

#### 建立發佈器

`vsce create-publisher (publisher name)`

輸入取得的 **Personal access token**


vsce 將會記得這個 publisher 與 token 以方便快速發佈

#### Token更新

在我們建立token時，token是有效期的，當token 過期時，我們就需要以下這個指來更新 token

vsce login (publisher name) 

也可以在 `vsce publish` 時 直接指定 token

vsce publish -p <token>

到這裡你應該成功發佈你的第一個Extension了！恭喜

這是我寫的第一個 Extension ，功能很陽春
用途是把 i18n 資料夾內的 json 檔案轉成 .xls
下載數 1 … QQ


推薦使用 Typescript 會比較容易開發
不然要查 [官方API](https://code.visualstudio.com/api/references/vscode-api) 會看得很痛苦，畢竟範例不多或者都要下載才能看

實際撰寫時 會遇到 VScode API 到底有哪些功能可以使用的問題
甚至要去了解 VScode 的設計結構

就醬！馬上來試試看吧