# 使用 Teams Toolkit 開發 Teams 應用程式：起手式

前幾年若要開發 Teams 應用程式的門檻非常高，你必須查看非常多的文件之後，還不知道怎樣完成第一個測試用的應用程式。但是微軟近期發佈了 [Teams Toolkit](https://marketplace.visualstudio.com/items?itemName=TeamsDevApp.ms-teams-vscode-extension) 擴充套件，可以說大幅降低了首次開發 Teams apps 的難度，許多繁瑣的過程與背景知識，透過 VS Code 的 [Teams Toolkit](https://marketplace.visualstudio.com/items?itemName=TeamsDevApp.ms-teams-vscode-extension) 擴充套件或 [TeamsFx CLI](https://learn.microsoft.com/en-us/microsoftteams/platform/toolkit/teamsfx-cli?WT.mc_id=DT-MVP-4015686) 命令列工具，就可以非常簡易的建置出開發環境，若要部署到 Azure 也都有相對應的工具與命令可以使用。今天這篇文章我就來跟大家分享開發 Teams App 的起手式。

通常我們要開始學習如何開發 Teams App 大概會有以下步驟：

1.  準備 Microsoft 365 組織與調整 Teams apps 原則設定
2.  準備 Teams app 所需的開發工具
3.  瞭解 Teams app 的 "Capabilities" (能力)
4.  建立 Teams app 應用程式
5.  修改範例程式碼以符合你的需求
6.  預覽 / 測試 Teams 應用程式
7.  部署 Teams 應用程式

今天這篇文章的重點，將會專注在 1, 2, 3, 4, 6, 7 等步驟。

### 準備 Microsoft 365 組織與調整 Teams apps 原則設定

1.  準備一個 Microsoft 365 組織 (Tenant)
    
    [Prepare your Microsoft 365 tenant - Teams | Microsoft Docs](https://learn.microsoft.com/en-us/microsoftteams/platform/concepts/build-and-test/prepare-your-o365-tenant#enable-custom-teams-apps-and-turn-on-custom-app-uploading?WT.mc_id=DT-MVP-4015686)
    
    > 你若沒有 Microsoft 365 可用，可以申請免費的 [Microsoft 365 Developer Program](https://aka.ms/teamsfx-prepare-365-tenant) 即可開始開發！
    
2.  到 Teams admin center [設定 Teams apps 原則](https://admin.teams.microsoft.com/policies/app-setup) (允許上傳自訂的 Teams 應用程式)
    
    [Prepare accounts to build Teams apps](https://learn.microsoft.com/en-us/microsoftteams/platform/toolkit/accounts?WT.mc_id=DT-MVP-4015686)
    

### 準備 Teams app 所需的開發工具

-   [Visual Studio Code](https://code.visualstudio.com/)
    
    主要的開發工具
    
    ```bash
    choco install vscode -y
    ```
    
-   [Teams Toolkit extension](https://marketplace.visualstudio.com/items?itemName=TeamsDevApp.ms-teams-vscode-extension)
    
    主要的開發工具擴充套件
    
    ```bash
    code --install-extension TeamsDevApp.ms-teams-vscode-extension
    ```
    
-   [Node.js LTS](https://aka.ms/teamsfx-nodejs-download)
    
    ```bash
    choco install nodejs-lts -y
    ```
    
-   [TeamsFx CLI](https://learn.microsoft.com/en-us/microsoftteams/platform/toolkit/teamsfx-cli?WT.mc_id=DT-MVP-4015686)
    
    主要的 CI/CD 與透過命令列發行應用程式的工具，可大幅降低首次開發 Teams App 的上手門檻！
    
    ```bash
    npm install -g @microsoft/teamsfx-cli
    ```
    

### 瞭解 Teams App 的 "Capabilities" (能力)

在開發你的第一個 Teams 應用程式之前，你可能要先瞭解你可以拿 Teams App 來開發些什麼應用，然後再來學習用什麼樣的工具來開發！

基本上，Teams App 的 **Capabilities** 有以下三種：

1.  **Tabs** (索引標籤)
    
    這種 Teams 應用程式主要跑在 Teams **聊天室**或**頻道**中的**索引標籤** (Tabs)，簡單來說，這種類型的 Teams App 就是一個 Web 網頁而已，你只要會 HTML, CSS, JS 就可以開發出一個 Teams App，即便你是使用純前端的框架 (Angular, Vue, React) 也都可以實現 **Tabs** 類型的應用。
    
    這種 Teams App 主要應用於 **查詢資訊** 或是提供 **單人** 或 **多人** 相同功能的使用情境。例如：查詢個人的特休剩餘天數、查詢團隊的 CI 的成功率。
    
    ![image](https://stwillblogassets.blob.core.windows.net/files/images/external/user-images.githubusercontent.com/098037fbdc27230db908-151584739-6ab37f2a-42ff-470f-b693-57b0b345d2e3.png)
    
    你可能會搭配 [TeamsFx SDK](https://learn.microsoft.com/en-us/javascript/api/@microsoft/teamsfx/?view=msteams-client-js-latest&preserve-view=true&WT.mc_id=DT-MVP-4015686) 或 [Teams JavaScript client SDK](https://learn.microsoft.com/en-us/javascript/api/overview/msteams-client?view=msteams-client-js-latest&preserve-view=true&WT.mc_id=DT-MVP-4015686) 來開發這些頁面。
    
2.  **Bots** (聊天機器人)
    
    這種 Teams 應用程式主要就是透過**文字聊天**的方式，提供**對談式互動**介面，讓使用者可以跟機器人說話，做到一些自動化工作。
    
    這種 Teams App 主要應用於 **聊天機器人** 與 **用戶** 之間的「一對一」對話互動。例如：員工請假、查詢資訊、回報工時記錄、...等等。
    
    > 如果該聊天機器人安裝在頻道中，所有的跟機器人的互動都會讓所有人看見，是一種相當透明的互動方式。
    
    這部分你可能會用到 [TeamsFx SDK](https://learn.microsoft.com/en-us/javascript/api/@microsoft/teamsfx/?view=msteams-client-js-latest&preserve-view=true&WT.mc_id=DT-MVP-4015686) 或 [Bot Framework SDK](https://dev.botframework.com/) 來開發這些聊天機器人。
    
3.  **Messaging extension** (訊息擴展)
    
    這種 Teams 應用程式主要是透過「搜尋」、「行為」或「對話」，在原本的訊息上插入一些額外的資訊，你可能會透過 [Adaptive Cards](https://adaptivecards.io/) 來設計複雜的版面。例如你可以在訊息內容的下方自動加上一些按鈕或欄位，增加訊息的表達能力與互動能力。
    
    訊息擴展類型的應用，大致可以分成三種類型：
    
    1.  分析輸入的內容，自動添加額外的附加資訊 (例如: 輸入網址會自動加上網頁預覽的摘要資訊)
        
        ![image](https://stwillblogassets.blob.core.windows.net/files/images/external/user-images.githubusercontent.com/6474aa28113b5022a487-151584028-ca0bb6e8-66c2-44f5-ab57-2de2393624fb.png)
        
    2.  輸入訊息時，可以透過互動的方式，在訊息中加入額外的資訊
        
        ![image](https://stwillblogassets.blob.core.windows.net/files/images/external/user-images.githubusercontent.com/ce3709b4979f660c966c-151583831-88449545-c134-4796-a622-18e61475cb9e.png)
        
    3.  在 Teams 的搜尋框輸入 `/` 時，可以出現的選項，這也是透過 **Messaging extension** 來提供的
        
        ![image](https://stwillblogassets.blob.core.windows.net/files/images/external/user-images.githubusercontent.com/4c59929ee1cf3c1d883b-151584134-c07814e2-543d-4f53-979b-c6b7085b4118.png)
        

> 一個 Teams app 可以同時包含多種 "Capabilities" (能力)！

### 建立 Teams app 應用程式

1.  建立一個空資料夾
    
    ```powershell
    mkdir G:\Projects
    cd G:\Projects
    ```
    
2.  直接從專案範本建立全新專案
    
    ```powershell
    teamsfx new template hello-world-tab
    
    cd hello-world-tab
    
    code .
    ```
    
3.  開啟 VS Code 之後直接按下 `F5` 快速鍵，就可以立即啟動本機開發伺服器，並開啟 Teams 網站後自動上傳 Teams app 自訂應用程式
    
    你可以直接將 Teams app 新增至指定的「頻道」或「聊天室」即可安裝完成：
    
    ![image](https://stwillblogassets.blob.core.windows.net/files/images/external/user-images.githubusercontent.com/39fbdd6e97d9d0dd3cce-151599810-a1496ae3-d7c3-47e4-afc6-8777fb07d9e4.png)
    
    此時你就可以開始使用這個 **Tabs** (索引標籤) 來使用 Teams app 應用程式，整個流程一鼓作氣、一氣呵成，對開發人員來說非常友善。
    

### 部署 Teams 應用程式

透過 [TeamsFx CLI](https://learn.microsoft.com/en-us/microsoftteams/platform/toolkit/teamsfx-cli?WT.mc_id=DT-MVP-4015686) 可以非常方便的幫你設定好 Teams app 所有必須的各種資源，其中包含 Teams 所屬的 Microsoft 365 組織 (Tenant) 必須先註冊一個 **App registration** (Service Principal)，還有自動建立執行 Teams app 網站/API 所需的 Azure 資源。

1.  設定 Azure AD 與建立必要的 Azure 資源
    
    由於 Teams app 本身必須先在 Azure AD 註冊一個應用程式才能運作，這個步驟牽涉到 OAuth 2.0 的相關知識，對大多數開發人員來說過於陌生，所以這個步驟已經被包含在 `teamsfx provision` 命令之中，開發過程已經大幅簡化。
    
    另外，為了要能夠有個地方可以執行你的 Teams app，你會需要在 Azure 建立一些重要的資源，例如 Storage, App Service Plan, Function App, ... 等等。
    
    > 注意: Microsoft 365 的 Azure AD 與 Azure 資源的 Azure AD 可以不一樣，事實上，你的 Teams app 就算要安裝在 AWS 或地端機房也都是可以的。
    
    首先，你必須先透過 [Azure CLI](https://learn.microsoft.com/zh-tw/cli/azure/install-azure-cli?WT.mc_id=DT-MVP-4015686) 登入 Azure 組織，登入後才會讓你選取你想要部署的**訂用帳戶** (Subscription)。
    
    ```bash
    az login
    ```
    
    以下這個步驟首先會請你登入 Teams 所在的 Microsoft 365 組織 (Azure AD)，因為他需要在你的 Azure AD 建立一個 **服務主體** (Service Principal) 物件。然後會直接詢問你要選用哪一個 **Azure 訂用帳戶** (Subscription)，然後讓你建立 **資源群組** (Resource Group) 並設定**資料中心地區** (Location)，接著就會全自動幫你建立好必要的 Azure 資源，並且會幫你產生一個 Teams Package 檔案 (`appPackage.dev.zip`)。
    
    ```bash
    teamsfx provision
    ```
    
    ![image](https://stwillblogassets.blob.core.windows.net/files/images/external/user-images.githubusercontent.com/aa85af9a6677f3a30b66-151596810-67655fcd-292c-48c3-8e3b-1448eba0cc7b.png)
    
    > 注意: 這裡建立的 `appPackage.dev.zip` 很重要，壓縮檔內有一個 `manifest.json` 定義了 Teams app 所有的必要資訊，包含 Tabs 要顯示的網頁網址與 Teams app 權限。其實所有的 Teams app 要部署的時候，所有的檔案都是放在網站上，上架 Teams app 就只要準備 `manifest.json` 即可，因此你可以將網站部署到任何地方，不一定要部署到 Azure 雲端平台。
    
2.  部署 Teams 應用程式到 Azure
    
    ```bash
    teamsfx deploy
    ```
    
3.  上傳自訂應用程式
    
    直接從 Teams Client 點擊左下角的「應用程式」>「上傳自訂應用程式」，並將 Teams app 新增至指定的「頻道」或「聊天室」之中：
    
    ![上傳自訂應用程式](https://stwillblogassets.blob.core.windows.net/files/images/external/user-images.githubusercontent.com/a7c1e35cbf5a81ca7034-151598328-7881d4bb-2894-4cc4-82b7-3463bb9dcbc8.png)
    
    安裝好之後，就可以點開 **My Tab** (索引標籤) 就可以看到頁面，並且使用者可以按下 **Authorize** 按鈕來取得使用者的基本資訊。
    
    ![image](https://stwillblogassets.blob.core.windows.net/files/images/external/user-images.githubusercontent.com/724c0a00187a30ab0ddb-151598968-e61fbb12-6b2a-4c55-beb8-ff963b0030e5.png)
    
    > 這裡的 **Authorize** 按鈕所呼叫的程式，事實上是透過 OAuth 2.0 向 Microsoft Graph 取得一個 `accessToken`，然後透過這個 `accessToken` 取得使用者資料，你也可以透過同樣的流程，許得該使用者在 Microsoft 365 中的任何資料，過程中走的就是 OAuth 2.0 的授權流程。
    

### 專案機會

我們公司使用 Office 365 已經非常多年，多年前我們從 Slack 全面轉換到 Teams 平台，一開始不太會用，還會覺得有些地方實在設計的很爛。但是用了一段時間才發現，這套設計的理念與架構，其實跟 Slack 不太一樣，很多時候不能相比。我們公司現在已經很少使用沒有效率的 E-mail 來協作，公司內部所有的協調工作，全都透過 Teams 完成，而且專案的資訊全部都集中的 Teams 的團隊與頻道中，所有的溝通過程、會議、錄影、教學、檔案共享、文件管理，與任何第三方資訊 (Azure Boards, PR 通知, Trello, ...) 也都可以全部整合在一起，甚至於連常見的重開網站、開啟防火牆、遠端 VM 開關機、查詢 VPN 資訊、...等功能，也都可以非常方便的在 Teams 完成，完全不需要外開網頁，而且所有資訊都是透明化的，對於組織的溝通效率大幅提升，人越多的公司應該會越有感覺。

由於 Teams app 的開發門檻已經降低許多，可以想見的，這個領域的專案開發需求應該會有不小的市場，只是還需要一些時間醞釀，大家其實還沒發現 Teams 如何改善組織效率的方法。如果你的公司也有在使用或正在考慮使用 Teams，是可以想想看客製化 Teams app 可以為你的公司帶來什麼協作效率的提升，如果有機會的話，可以[找我們](https://m.me/will.fans)幫你們開發完全客製化的 Teams 應用程式，大幅提昇組織的工作效率，降低各種繁文縟節的無形損耗。

### 相關連結

-   [Get started for building and deploying customized apps for Microsoft Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/get-started/get-started-overview?tabs=vscode&WT.mc_id=DT-MVP-4015686)
-   [Build apps with the Teams Toolkit and Visual Studio Code](https://learn.microsoft.com/en-us/microsoftteams/platform/toolkit/visual-studio-code-overview?WT.mc_id=DT-MVP-4015686)
-   [Build your first app using C#](https://learn.microsoft.com/en-us/microsoftteams/platform/sbs-gs-csharp?WT.mc_id=DT-MVP-4015686)
-   [Teams Toolkit (Preview) - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=TeamsDevApp.ms-teams-vscode-extension)
-   [Microsoft Teams Framework (TeamsFx)](https://github.com/OfficeDev/TeamsFx)
    -   [Microsoft Teams Framework (TeamsFx) Sample Gallery](https://github.com/OfficeDev/TeamsFx-Samples)
-   TeamsFx CLI
    -   建立測試環境與正式環境 ([Manage multiple environments in Teams Toolkit](https://learn.microsoft.com/en-us/microsoftteams/platform/toolkit/teamsfx-multi-env?WT.mc_id=DT-MVP-4015686))
    -   多人共同開發 Teams App 需設定必要的權限 ([Collaborate on Teams project using Teams Toolkit](https://aka.ms/teamsfx-arm-templates))
    -   使用 ARM Template 建立 Azure 雲端資源 ([Use Teams Toolkit to provision cloud resources](https://aka.ms/teamsfx-arm-templates))
-   [Publish a custom app by uploading an app package](https://learn.microsoft.com/en-us/microsoftteams/upload-custom-apps#upload?WT.mc_id=DT-MVP-4015686)
-   [线下活动 | 从零开始开发一款属于你的Microsoft Teams小程序！](https://www.bilibili.com/video/BV1PL411t7Er)