使用活動處理常式的事件驅動對話

適用于: SDK v4

活動處理常式 是一種以事件為導向的方式,用來組織 bot 的對話式邏輯。 每個不同類型或子類型的活動都代表不同類型的對話事件。 在幕後,bot 的 回合處理 程式會針對其收到的任何活動類型,呼叫個別的活動處理常式。

例如,如果 bot 收到訊息活動,則回合處理常式會看到傳入活動,並將它傳送至「 訊息活動 」活動處理常式。 建立您的 bot 時,用於處理和回應訊息的 bot 邏輯會在 訊息活動 處理常式上進行。 同樣地,您處理新增至交談之成員的邏輯會進入 成員新增 的處理常式,每當有成員加入對話時,就會呼叫此處理程式。

如需其他組織 bot 邏輯的方式,請參閱 bot 運作方式bot 邏輯一節。

若要為這些處理常式執行您的邏輯,您將會覆寫 bot 中的這些方法,例如下列 範例活動處理常式 區段。 上述每個處理常式都沒有基底實作,所以只要新增您想要的覆寫邏輯即可。

在某些情況中,您會想要覆寫基底回合處理常式,例如在回合結束時儲存狀態。 若要這麼做,請務必先呼叫 await base.OnTurnAsync(turnContext, cancellationToken);,確保在其他程式碼之前執行 OnTurnAsync 的基底實作。 此外,該基底實作會負責呼叫其餘的活動處理常式,例如 OnMessageActivityAsync

活動處理

Bot 邏輯會處理來自從一或多個通道的傳入活動,並產生傳出活動來回應。

主要 bot 邏輯定義于 bot 程式碼中。 若要將 bot 實作為活動處理常式,請從執行介面的來衍生 bot 類別 ActivityHandler IBotActivityHandler 針對不同類型的活動定義各種處理常式,例如 OnMessageActivityAsyncOnMembersAddedAsync 。 這些方法會受到保護,但可加以覆寫,因為我們是衍生自 ActivityHandler

ActivityHandler 中定義的處理常式如下:

事件 處理常式 描述
收到的任何活動類型 OnTurnAsync 根據所收到的活動型別,呼叫其中一個其他處理常式。
收到的訊息活動 OnMessageActivityAsync 覆寫此項目以處理 message 活動。
收到的交談更新活動 OnConversationUpdateActivityAsync conversationUpdate 活動上,如有 Bot 以外的成員加入或離開交談,則會呼叫處理常式。
已加入交談的非 Bot 成員 OnMembersAddedAsync 覆寫此項目以處理要加入交談的成員。
已離開交談的非 Bot 成員 OnMembersRemovedAsync 覆寫此項目以處理要離開交談的成員。
收到的事件活動 OnEventActivityAsync event 活動上,呼叫事件類型特有的處理常式。
收到的權杖回應事件活動 OnTokenResponseEventAsync 覆寫此項目以處理權杖回應事件。
收到的非權杖回應事件活動 OnEventAsync 覆寫此項目以處理其他類型的事件。
已接收訊息回應活動 OnMessageReactionActivityAsync messageReaction 活動上,如果在訊息中新增或移除一或多個回應,則會呼叫處理常式。
新增至訊息的訊息反應 OnReactionsAddedAsync 覆寫此參數以處理新增至訊息的反應。
從訊息移除的訊息反應 OnReactionsRemovedAsync 覆寫此參數以處理從訊息移除的反應。
已收到安裝更新活動 OnInstallationUpdateActivityAsync installationUpdate 活動上,根據是否已安裝或卸載 bot 來呼叫處理常式。
已安裝 Bot OnInstallationUpdateAddAsync 覆寫此項,以新增在組織單位內安裝 bot 時的邏輯。
卸載 Bot OnInstallationUpdateRemoveAsync 覆寫此項,以新增在組織單位內卸載 bot 時的邏輯。
收到的其他活動類型 OnUnrecognizedActivityTypeAsync 覆寫此項目以處理任何未處理的活動類型。

這些不同的處理常式都有 turnContext,其可提供連入活動 (對應至輸入 HTTP 要求) 的相關資訊。 活動可以是各種類型,所以每個處理常式都會在其回合內容參數中提供強型別活動;在大部分情況下,一律處理通常最常見的 OnMessageActivityAsync

如同舊版 4.x 的這個架構,也有實作公用方法 OnTurnAsync 的選項。 目前,這個方法的基底實作會處理錯誤檢查,然後根據連入活動的類型,呼叫每個特定處理常式 (如我們在此範例中定義的兩個處理常式)。 在大部分的情況下,您可不理會該方法並使用個別的處理常式,但如果您的情況需要 OnTurnAsync 的自訂實作,這仍是一個選項。

重要

如果您覆寫 OnTurnAsync 方法,您必須呼叫 base.OnTurnAsync 來取得基底實作,以呼叫所有其他 On<activity>Async 處理常式或自行呼叫這些處理常式。 否則不會呼叫這些處理常式,且不會執行該程式碼。

範例活動處理常式

例如,您可以處理新增至歡迎使用者至對話的 成員 ,並處理 訊息 以回應傳送至 bot 的訊息。

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);
            }
        }
    }
}

後續步驟

  • Microsoft 團隊頻道引進一些小組專屬的活動,讓您的 bot 必須支援這些活動才能與小組正常搭配運作。 若要了解為 Microsoft Teams 開發 Bot 的重要概念,請參閱 Microsoft Teams Bot 的運作方式
  • 活動處理常式是設計 bot 的好方法,不需要追蹤回合之間的對話狀態。 對話方塊程式庫提供了一種方式,可讓您管理與使用者長時間執行的對話。