使用 Bot Builder SDK v4 建立對話機器人

June 27th, 2018

在兩年前的 Build 2016 大會，微軟正式推出了 Bot Framework 智能機器人開發框架，一個交談即平台 (conversation as a platform) 未來就此展開。在兩年後的今天，許多技術不斷迭代已經和過去不一樣了，在 Bot Builder SDK v3 以前，是用 .NET Framework 的 ASP.NET WebAPI 作為開發基礎，現在跨平台的 .NET Core 推出了，也成熟了，Bot Builder SDK v4 也理所當然的改用新的技術架構，讓開發者能輕鬆打造出跨平台、高效能的智能機器人。

請注意！目前為止 Bot Builder SDK v4 還在 Preview 階段，程式碼可能會有部分調整，請斟酌使用。

根據官方的 Roadmap，預計 2018 年 9 月會釋出穩定版、完整的文件與範例。

Table of Contents

開發環境
建立對話機器人
本機偵錯
發行至 Azure
註冊對話機器人服務
專案範本擴充套件

開發環境

需要用的到工具和服務相當多，這裡先條列出來。

主要使用 Visual Studio 2017 15.6 以上版本的 IDE 開發工具 (下載位置)
使用 ASP.NET Core 跨平台的 Web 開發技術
使用 Bot Framework Emulator (下載位置)
- Bot Framework Emulator v3 或 v4 都可以用，這裡使用 v4 的工具
需要 Microsoft Azure 訂閱 (申請免費 NT$6,100 的點數)

建立對話機器人

我們接下來會逐步建立一個回音機器人，也就是你跟機器人說什麼，他就會回你什麼，藉此做為練習。

使用 Visual Studio 建立新的 ASP.NET Core Web 應用程式。

使用 ASP.NET Core Web 應用程式專案範本建立專案

選擇空白專案，從甚麼都沒有開始。

選擇空白專案

對話機器人服務本身其實是個 WebAPI 網站服務，但為了簡單介紹這個網站服務的用途，可以在 wwwroot 資料夾中建立一個靜態的 index.html HTML 網頁，

<!DOCTYPE html>
<html>
<head>
    <title></title>
    <meta charset="utf-8" />
</head>
<body style="font-family:'Segoe UI'">
    <h1>使用 ASP.Net Core 2 建立 EchoBot</h1>
    <p>這個對話機器人會回傳接收到的對話。</p>
    <p>請使用 Bot Framework Emulator 對您的對話機器人進行偵錯，並將下列 URL 複製至模擬器 Endpoint URL 欄位中。</p>
    <div style="padding-left: 50px;" id="botBaseUrl"></div>
    <p>如需發行對話機器人服務，請至 <a href="https://www.botframework.com/">Bot Framework 網站</a>進行對話機器人註冊，請提供下列 URL 進行註冊。</p>
    <div style="padding-left: 50px;">
        https://<strong>{your domain name}</strong>/api/messages
    </div>
    <script>
        var urlDiv = document.getElementById("botBaseUrl");
        var aTag = document.createElement('a');
        aTag.setAttribute('href', location.protocol + "//" + location.host + "/api/messages");
        aTag.innerHTML = location.protocol + "//" + location.host + "/api/messages";
        urlDiv.appendChild(aTag);
    </script>
</body>
</html>

開啟專案的 NuGet 套件管理工具，勾選搶鮮版選項，並搜尋以下套件進行安裝：

Microsoft.Bot.Builder.Core
Microsoft.Bot.Builder.Core.Extensions
Microsoft.Bot.Builder.Integration.AspNet.Core
- 此套件用來將 Bot Builder 整合進 ASP.NET Core 專案中
- 提供中介程序做設定，如 UseBotFramework()

看目前 Bot Builder SDK 專案的發展，未來 Microsoft.Bot.Builder.Core 和 Microsoft.Bot.Builder.Core.Extensions 會收攏成一個 Microsoft.Bot.Builder 套件。

安裝 Microsoft.Bot.Builder.Core 和 Microsoft.Bot.Builder.Core.Extensions 套件

安裝 Microsoft.Bot.Builder.Integration.AspNet.Core 套件

新增 EchoState.cs 檔案，建立 EchoState 類別，裡面包含一個 TurnCount 屬性，作為記錄第幾次對話的計數器。

有時為了追蹤對話過程中的關鍵資訊，為對話機器人設計 State 作為資訊保留機制，能讓我們更容易處理程式邏輯，詳細請參考官方文件Save state using conversation and user properties。

namespace DemoBotBuilderV4
{
    public class EchoState
    {
        public int TurnCount { get; set; } = 0;
    }
}

新增 EchoBot.cs 主要處理對話邏輯的檔案，建立 EchoBot 類別並實作 IBot 介面，這個介面要求實作 OnTurn 方法，在這個方法裡面可以設計我們自己處理邏輯。

OnTurn 方法會接收一個 ITurnContext 類型的參數，這個參數裡面包含執行與使用者對話的所有資訊。

namespace DemoBotBuilderV4
{
    public class EchoBot : IBot
    {
        public async Task OnTurn(ITurnContext context)
        {
            // 當收到活動類型為 Messages 的訊息時執行以下程序
            if (context.Activity.Type is ActivityTypes.Message)
            {
                // 取得儲存在對話狀態中的自訂資訊
                var state = context.GetConversationState<EchoState>();

                // 增加對話計數器
                state.TurnCount++;

                // 回傳使用者傳送的的對話訊息
                await context.SendActivity($"Turn {state.TurnCount}: You sent '{context.Activity.Text}'");
            }
        }
    }
}

接著修改 Startup.cs，首先在建構式中注入應用程式的環境變數，並設定存取 appsettings.json 的 Configuration 屬性。

public Startup(IHostingEnvironment env)
{
    var builder = new ConfigurationBuilder()
        .SetBasePath(env.ContentRootPath)
        .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
        .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true)
        .AddEnvironmentVariables();

    Configuration = builder.Build();
}

public IConfiguration Configuration { get; }

在 Startup.cs 的 ConfigureServices() 中註冊對話機器人服務，請參考以下程式碼：

public void ConfigureServices(IServiceCollection services)
{
    services.AddBot<EchoBot>(options =>
    {
        // 對話機器人需要一組 Microsoft App ID，這通常會存在 appsettings.json 或應用程式環境變數中
        // 透過傳入 Configuration 給 CredentialProvider，藉此取得相關資訊
        options.CredentialProvider = new ConfigurationCredentialProvider(Configuration);

        // 為對話機器人加入處理最高層級的例外(Exception)控制，當有例外發生時，會執行以下動作
        // TraceActivity() 只會傳訊息給對話機器人模擬器，而 SendActivity() 會傳訊息給使用者
        options.Middleware.Add(new CatchExceptionMiddleware<Exception>(async (context, exception) =>
        {
            await context.TraceActivity("EchoBot Exception", exception);
            await context.SendActivity("Sorry, it looks like something went wrong!");
        }));

        // 本機偵錯時，建議使用記憶體來存放對話狀態資訊，每次重新啟動都會清空所存放的資訊
        IStorage dataStore = new MemoryStorage();

        // 若你的對話機器人運行在單一機器，且希望每次重新啟動能存取上一次的對話狀態資訊，請參考下列作法將資訊存成暫存檔案
        // IStorage dataStore = new FileStorage(System.IO.Path.GetTempPath());

        // 對於正是環境的對話機器人，你可以利用 Azure Table Store、Azure Blob 或 Azure CosmosDB 來保留對話狀態資訊
        // 請先至 NuGet 套件管理工具中搜尋並安裝 Microsoft.Bot.Builder.Azure，請參考以下作法將資訊存至 Azure 平台
        // IStorage dataStore = new Microsoft.Bot.Builder.Azure.AzureTableStorage("AzureTablesConnectionString", "TableName");
        // IStorage dataStore = new Microsoft.Bot.Builder.Azure.AzureBlobStorage("AzureBlobConnectionString", "containerName");

        options.Middleware.Add(new ConversationState<EchoState>(dataStore));
    });
}

在 Startup.cs 的 Configure() 設定中介程序

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseDefaultFiles()
        // 使網站可以開啟 index.html 網頁
        .UseStaticFiles()
        // 將所註冊的 Bot 加入網站運行的程序中
        .UseBotFramework();
}

到這裡我們程式就寫完了，請按 Ctrl + F5 啟動網站，會開啟如下圖的網站畫面。

啟動網站

下一段會使用 https://localhost/api/messages 這個端點來做對話機器人測試。

在測試之前，或許你會好奇，我們沒有建立 /api/messages 這個 API 端點，為什麼就忽然可以用了呢？原因是 Microsoft.Bot.Builder.Integration.AspNet.Core 套件所提供的 UseBotFramework() 會去偵測 Bot Builder 的預設 API 端點，也就是 /api/messages，我們可以從原始碼中找到這項設定。