了解 echo bot 的結構

適用于: SDK v4

Bot Framework 的範本和範例是針對 ASP.NET (c # ) 、restify (JavaScript) 和 >aioHTTP (Python) 所撰寫。 不過,web 服務功能不是 Bot Framework SDK 的一部分,而是您選擇使用的 web 架構的一部分。

所有 bot 應用程式都會共用一些常用功能。

功能 描述
資源佈建 作為 web 應用程式的 bot 需要建立 web 服務、bot 介面卡和 bot 物件。
傳訊端點 Web 應用程式必須執行訊息端點,以接收活動並將活動轉送至 bot 介面卡。
Bot 介面卡 介面卡會接收來自訊息端點的活動、將它們轉送至 bot 的回合處理常式,並攔截 bot 邏輯未攔截的任何錯誤或例外狀況。
Bot 物件 Bot 物件會處理 bot 的回合原因或邏輯。

您可以從範本建立 echo bot,如 c #JavaScriptPython) 快速入門 (所述,也可以從 Microsoft/BotBuilder 範例 存放庫複製 echo bot 專案。

C # 和 JavaScript 範本具有串流連接的內建支援。 本文涵蓋串流功能。 如需有關串流連接的詳細資訊,請參閱如何 將 bot 連線到 Direct Line 語音

Prerequisites

Bot 範本

Bot 是一種 Web 應用程式,而每種語言都有範本可用。

Bot Framework 包含 VSIX 和 dotnet 範本。

範本會產生 ASP.NET MVC Core web 應用程式。 如果您查看 ASP.NET 基礎,您會在 Program.csStartup.cs 等檔案中看到類似的程式碼。 所有 Web 應用程式都需要這些檔案,並不是 Bot 特有的。

注意

VSIX封裝包含 .net core 2.1 和 .net core 3.1 版本的 c # 範本。 在 Visual Studio 2019 中建立新的 Bot 時,您應該使用 .NET Core 3.1 範本。 目前的 Bot 範例會使用 .NET Core 3.1 範本。 您可以在 BotBuilder-Samples 存放庫的 4.7-archive 分支中,找到使用 .NET Core 2.1 範本的範例。 如需將 .NET Core 3.1 bot 部署至 Azure 的詳細資訊,請參閱如何將 您的 bot 部署至 azure

檔案 上的appsettings.js 會指定 bot 的設定資訊,例如其應用程式識別碼和密碼等等。 如果在生產環境中使用特定技術或使用此 Bot,您必須將您的特定金鑰或 URL 新增至此組態。 但是在此 echo bot 中,您現在不需要在這裡進行任何動作;應用程式識別碼和密碼此時可能會保持未定義狀態。

EchoBot .csproj 檔案會為您的 bot 指定相依性及其相關聯的版本。 這是由範本和您的系統所設定。 您可以使用 NuGet 套件管理員或命令來安裝其他相依性 dotnet add package

資源佈建

作為 web 應用程式的 bot 需要建立 web 服務、bot 介面卡和 bot 物件。

許多 bot 也會建立 bot 的儲存層和記憶體管理物件,但 echo bot 不需要狀態。 其他 bot 也會建立任何需要取用之 bot 物件或介面卡外部的物件。

在 ASP.NET 中,您會在 啟動 .cs 檔案中註冊物件和物件建立方法。 ConfigureServices方法會將已連線的服務及其金鑰從 appsettings.js開啟 或 Azure Key Vault (如果有任何) 、連接狀態等等。 在這裡,介面卡和 bot 會定義為可透過相依性插入來使用。 然後, Configure 方法會完成您應用程式的設定。

ConfigureServicesConfigure 會在應用程式啟動由執行階段呼叫。

傳訊端點

此範本會使用訊息端點來執行 web 服務。 服務會將驗證標頭和要求承載解壓縮,並將其轉送至介面卡。

C # 和 JavaScript Sdk 支援串流連接。 雖然 echo bot 不會使用任何串流功能,但範本中的介面卡是設計來支援它們。

每個連入要求都代表新回合的起點。

控制器 \ BotController .cs

// This ASP Controller is created to handle a request. Dependency Injection will provide the Adapter and IBot
// implementation at runtime. Multiple different IBot implementations running at different endpoints can be
// achieved by specifying a more specific type for the bot constructor argument.
[Route("api/messages")]
[ApiController]
public class BotController : ControllerBase
{
    private readonly IBotFrameworkHttpAdapter Adapter;
    private readonly IBot Bot;

    public BotController(IBotFrameworkHttpAdapter adapter, IBot bot)
    {
        Adapter = adapter;
        Bot = bot;
    }

    [HttpPost, HttpGet]
    public async Task PostAsync()
    {
        // Delegate the processing of the HTTP POST to the adapter.
        // The adapter will invoke the bot.
        await Adapter.ProcessAsync(Request, Response, Bot);
    }
}

Bot 介面卡

介面卡會接收來自訊息端點的活動、將它們轉送至 bot 的回合處理常式,並攔截 bot 邏輯未攔截的任何錯誤或例外狀況。

介面卡可讓您新增自己 的 on 回合錯誤 處理常式。

Startup.cs

要使用的介面卡定義于 ConfigureServices 方法中。

// Create the Bot Framework Adapter with error handling enabled.
services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>();

AdapterWithErrorHandler.cs

public class AdapterWithErrorHandler : CloudAdapter
{
    public AdapterWithErrorHandler(IConfiguration configuration, IHttpClientFactory httpClientFactory, ILogger<IBotFrameworkHttpAdapter> logger)
        : base(configuration, httpClientFactory, logger)
    {
        OnTurnError = async (turnContext, exception) =>
        {
            // Log any leaked exception from the application.
            // NOTE: In production environment, you should consider logging this to
            // Azure Application Insights. Visit https://aka.ms/bottelemetry to see how
            // to add telemetry capture to your bot.
            logger.LogError(exception, $"[OnTurnError] unhandled error : {exception.Message}");

            // Send a message to the user
            await turnContext.SendActivityAsync("The bot encountered an error or bug.");
            await turnContext.SendActivityAsync("To continue to run this bot, please fix the bot source code.");

            // Send a trace activity, which will be displayed in the Bot Framework Emulator
            await turnContext.TraceActivityAsync("OnTurnError Trace", exception.Message, "https://www.botframework.com/schemas/error", "TurnError");
        };
    }
}

Bot 邏輯

Echo bot 會使用 活動處理常式 ,並針對它將辨識和回應的活動類型(在此案例中為 對話更新訊息 活動)執行處理常式。

  • 對話更新活動包含誰已加入或離開交談的資訊。 針對非群組交談,bot 和使用者啟動時都會加入交談。 針對群組交談,每當有人加入或離開交談(不論是 bot 或使用者)時,就會產生對話更新。
  • 訊息活動代表使用者傳送至 bot 的訊息。

當使用者加入對話並回顯傳送給 bot 的任何訊息時,echo bot 會歡迎使用者。

Startup.cs

要使用的 bot 定義于方法中 ConfigureServices

// Create the bot as a transient. In this case the ASP Controller is expecting an IBot.
services.AddTransient<IBot, EchoBot>();

Bots\EchoBot.cs

public class EchoBot : ActivityHandler
{
    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
    {
        var replyText = $"Echo: {turnContext.Activity.Text}";
        await turnContext.SendActivityAsync(MessageFactory.Text(replyText, replyText), cancellationToken);
    }

    protected override async Task OnMembersAddedAsync(IList<ChannelAccount> membersAdded, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
    {
        var welcomeText = "Hello and welcome!";
        foreach (var member in membersAdded)
        {
            if (member.Id != turnContext.Activity.Recipient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text(welcomeText, welcomeText), cancellationToken);
            }
        }
    }
}

下一步