管理對話框複雜度

發行項
03/10/2025

適用於： SDK v4

使用元件對話，您可以建立獨立的對話框來處理特定案例，將大型對話集分成更容易管理的部分。每個片段都有自己的對話組，並避免與其外的對話組發生任何名稱衝突。元件對話框可重複使用，因為它們可以是：

新增至您的機器人中的另一個 ComponentDialog 或 DialogSet。
匯出為套件的一部分。
在其他機器人內使用。

注意

Bot Framework JavaScript、C# 和 Python SDK 將會繼續受到支援，不過，Java SDK 即將淘汰，最終長期支援將於 2023 年 11 月結束。

使用 Java SDK 建置的現有 Bot 將繼續運作。

針對新的 Bot 建置，請考慮使用 Microsoft Copilot Studio ，並閱讀選擇正確的 Copilot 解決方案。

如需詳細資訊，請參閱 Bot 建置的未來。

必要條件

關於 bot 基本概念、對話庫以及如何管理交談的知識。
在 C#、JavaScript、Java 或 Python 中的多回合提示範例複本。

關於範例

在多回合提示範例中，我們使用瀑布式對話、一些提示詞和元件對話來建立互動，以便詢問使用者一系列問題。程式代碼會使用對話框來循環執行下列步驟：

步驟	提示類型
詢問使用者其運輸模式	選擇提示
詢問使用者他們的名稱	文字提示
詢問使用者是否要提供年齡	確認提示
如果他們回答是，詢問他們的年齡	進行驗證的數字提示，只接受大於0且小於150的年齡。
詢問收集到的資訊是否為「確定」	重用確認提示

最後，如果他們回答是，則顯示收集到的資訊;否則，請告知使用者不會保留其資訊。

實作您的元件對話框

在多回合提示範例中，我們使用 瀑布式對話、一些 提示語和 元件對話 來建立互動，詢問使用者一系列問題。

元件對話框會封裝一或多個對話。元件對話框具有內部對話集，而且您新增至這個內部對話集的對話框和提示有自己的標識碼，只能從元件對話內看見。

若要使用對話框，請安裝 Microsoft.Bot.Builder.Dialogs NuGet 套件。

Dialogs\UserProfileDialog.cs

在這裡，類別 UserProfileDialog 衍生自 ComponentDialog 類別。

public class UserProfileDialog : ComponentDialog

在建構函式中， AddDialog 方法會將對話框和提示新增至元件對話方塊。您使用這個方法新增的第一個項目會設定為初始對話框。您可以藉由明確設定 InitialDialogId 屬性來變更初始對話框。當您啟動元件對話框時，它會啟動其 初始對話方塊。

public UserProfileDialog(UserState userState)
    : base(nameof(UserProfileDialog))
{
    _userProfileAccessor = userState.CreateProperty<UserProfile>("UserProfile");

    // This array defines how the Waterfall will execute.
    var waterfallSteps = new WaterfallStep[]
    {
        TransportStepAsync,
        NameStepAsync,
        NameConfirmStepAsync,
        AgeStepAsync,
        PictureStepAsync,
        SummaryStepAsync,
        ConfirmStepAsync,
    };

    // Add named dialogs to the DialogSet. These names are saved in the dialog state.
    AddDialog(new WaterfallDialog(nameof(WaterfallDialog), waterfallSteps));
    AddDialog(new TextPrompt(nameof(TextPrompt)));
    AddDialog(new NumberPrompt<int>(nameof(NumberPrompt<int>), AgePromptValidatorAsync));
    AddDialog(new ChoicePrompt(nameof(ChoicePrompt)));
    AddDialog(new ConfirmPrompt(nameof(ConfirmPrompt)));
    AddDialog(new AttachmentPrompt(nameof(AttachmentPrompt), PicturePromptValidatorAsync));

    // The initial child Dialog to run.
    InitialDialogId = nameof(WaterfallDialog);
}

下列程式代碼代表瀑布式對話的第一個步驟。

private static async Task<DialogTurnResult> NameStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
{
    stepContext.Values["transport"] = ((FoundChoice)stepContext.Result).Value;

    return await stepContext.PromptAsync(nameof(TextPrompt), new PromptOptions { Prompt = MessageFactory.Text("Please enter your name.") }, cancellationToken);
}

如需實作瀑布式對話的詳細資訊，請參閱如何實作循序對話流程。

若要使用對話框，您的專案必須安裝 botbuilder-dialogs npm 套件。

dialogs/userProfileDialog.js

在這裡，UserProfileDialog 類別繼承自 ComponentDialog。

class UserProfileDialog extends ComponentDialog {

constructor(userState) {
    super('userProfileDialog');

    this.userProfile = userState.createProperty(USER_PROFILE);

    this.addDialog(new TextPrompt(NAME_PROMPT));
    this.addDialog(new ChoicePrompt(CHOICE_PROMPT));
    this.addDialog(new ConfirmPrompt(CONFIRM_PROMPT));
    this.addDialog(new NumberPrompt(NUMBER_PROMPT, this.agePromptValidator));
    this.addDialog(new AttachmentPrompt(ATTACHMENT_PROMPT, this.picturePromptValidator));

    this.addDialog(new WaterfallDialog(WATERFALL_DIALOG, [
        this.transportStep.bind(this),
        this.nameStep.bind(this),
        this.nameConfirmStep.bind(this),
        this.ageStep.bind(this),
        this.pictureStep.bind(this),
        this.summaryStep.bind(this),
        this.confirmStep.bind(this)
    ]));

    this.initialDialogId = WATERFALL_DIALOG;
}

下列程式代碼代表瀑布式對話的第一個步驟。

async transportStep(step) {
    // WaterfallStep always finishes with the end of the Waterfall or with another dialog; here it is a Prompt Dialog.
    // Running a prompt here means the next WaterfallStep will be run when the user's response is received.
    return await step.prompt(CHOICE_PROMPT, {
        prompt: 'Please enter your mode of transport.',
        choices: ChoiceFactory.toChoices(['Car', 'Bus', 'Bicycle'])
    });
}

如需實作瀑布式對話的詳細資訊，請參閱如何實作循序對話流程。

UserProfileDialog.java

在這裡，類別 UserProfileDialog 衍生自 ComponentDialog 類別。

警告

您要尋找的範例看起來已經移動！放心，我們正在努力解決這個問題。

在建構函式中， addDialog 方法會將對話框和提示新增至元件對話方塊。您使用這個方法新增的第一個項目會設定為初始對話框。您可以呼叫 setInitialDialogId 方法來變更初始對話，並提供初始對話的名稱。當您啟動元件對話框時，它會啟動其 初始對話方塊。

警告

您要尋找的範例看起來已經移動！放心，我們正在努力解決這個問題。

下列程式代碼代表瀑布式對話的第一個步驟。

警告

您要尋找的範例看起來已經移動！放心，我們正在努力解決這個問題。

如需實作瀑布式對話的詳細資訊，請參閱如何實作循序對話流程。

若要使用對話，請從終端機執行 pip install botbuilder-dialogs 和 pip install botbuilder-ai 以安裝 botbuilder-dialogs 和 botbuilder-ai 這些 PyPI 套件。

dialogs/user_profile_dialog.py

在這裡，類別 UserProfileDialog 擴充 ComponentDialog 。

class UserProfileDialog(ComponentDialog):

在建構函式中， add_dialog 方法會將對話框和提示新增至元件對話方塊。您使用這個方法新增的第一個項目會設定為初始對話框。您可以藉由明確設定 initial_dialog_id 屬性來變更初始對話框。當您啟動元件對話框時，它會啟動其 初始對話方塊。

class UserProfileDialog(ComponentDialog):
    def __init__(self, user_state: UserState):
        super(UserProfileDialog, self).__init__(UserProfileDialog.__name__)

        self.user_profile_accessor = user_state.create_property("UserProfile")

        self.add_dialog(
            WaterfallDialog(
                WaterfallDialog.__name__,
                [
                    self.transport_step,
                    self.name_step,
                    self.name_confirm_step,
                    self.age_step,
                    self.picture_step,
                    self.summary_step,
                    self.confirm_step,
                ],
            )
        )
        self.add_dialog(TextPrompt(TextPrompt.__name__))
        self.add_dialog(
            NumberPrompt(NumberPrompt.__name__, UserProfileDialog.age_prompt_validator)
        )
        self.add_dialog(ChoicePrompt(ChoicePrompt.__name__))
        self.add_dialog(ConfirmPrompt(ConfirmPrompt.__name__))
        self.add_dialog(
            AttachmentPrompt(
                AttachmentPrompt.__name__, UserProfileDialog.picture_prompt_validator
            )
        )

        self.initial_dialog_id = WaterfallDialog.__name__

下列程式代碼代表瀑布式對話的第一個步驟。

async def transport_step(
    self, step_context: WaterfallStepContext
) -> DialogTurnResult:
    # WaterfallStep always finishes with the end of the Waterfall or with another dialog;
    # here it is a Prompt Dialog. Running a prompt here means the next WaterfallStep will
    # be run when the users response is received.
    return await step_context.prompt(
        ChoicePrompt.__name__,
        PromptOptions(
            prompt=MessageFactory.text("Please enter your mode of transport."),
            choices=[Choice("Car"), Choice("Bus"), Choice("Bicycle")],
        ),
    )

如需實作瀑布式對話的詳細資訊，請參閱如何實作循序對話流程。

在運行時間，元件對話框會維護自己的對話堆疊。啟動元件對話框時：

實例會建立並新增至外部對話堆棧
它會建立一個內部對話堆疊，然後將其新增至狀態。
它會啟動其初始對話，並將它新增至內部對話堆疊。

父內容會將元件視為使用中的對話框。不過，對元件內的內容而言，它看起來像初始對話是作用中的對話框。

使用你的機器人呼叫對話框

在外部對話集中，您新增元件對話框的對話框，元件對話框具有您所建立的標識碼。在外部集合中，元件看起來像是單一對話框，就像提示所做的一樣。

若要使用元件對話框，請將它的實例新增至 Bot 的對話集。

Bots\DialogBot.cs

在範例中，這是透過從機器人的 OnMessageActivityAsync 方法呼叫的 RunAsync 方法來完成的。

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    Logger.LogInformation("Running dialog with Message Activity.");

    // Run the Dialog with the new message Activity.
    await Dialog.RunAsync(turnContext, ConversationState.CreateProperty<DialogState>(nameof(DialogState)), cancellationToken);
}

dialogs/userProfileDialog.js

在範例中，我們已在使用者配置檔對話方塊中新增一個方法 run。

async run(turnContext, accessor) {
    const dialogSet = new DialogSet(accessor);
    dialogSet.add(this);

    const dialogContext = await dialogSet.createContext(turnContext);
    const results = await dialogContext.continueDialog();
    if (results.status === DialogTurnStatus.empty) {
        await dialogContext.beginDialog(this.id);
    }
}

bots/dialogBot.js

run 方法從機器人的 onMessage 方法呼叫。

this.onMessage(async (context, next) => {
    console.log('Running dialog with Message Activity.');

    // Run the Dialog with the new message Activity.
    await this.dialog.run(context, this.dialogState);

    await next();
});

helpers/dialog_helper.py

在範例中，我們已將 run_dialog 方法新增到使用者配置檔對話方塊。

class DialogHelper:
    @staticmethod
    async def run_dialog(
        dialog: Dialog, turn_context: TurnContext, accessor: StatePropertyAccessor
    ):
        dialog_set = DialogSet(accessor)
        dialog_set.add(dialog)

        dialog_context = await dialog_set.create_context(turn_context)
        results = await dialog_context.continue_dialog()
        if results.status == DialogTurnStatus.Empty:
            await dialog_context.begin_dialog(dialog.id)

從 Bot 的on_message_activity方法呼叫的run_dialog方法。

bots/dialog_bot.py

async def on_message_activity(self, turn_context: TurnContext):
    await DialogHelper.run_dialog(
        self.dialog,
        turn_context,
        self.conversation_state.create_property("DialogState"),
    )

測試您的機器人

如果您尚未這麼做，請安裝 Bot Framework 模擬器。
在本機電腦上執行範例。
啟動模擬器、連線至 Bot，並傳送訊息，如下所示。

多回合提示對話框中的範例文字記錄。

其他資訊

元件對話框的取消運作方式

如果您從元件對話的內容呼叫 取消所有對話框 ，元件對話框將會取消其內部堆疊上的所有對話框，然後結束，將控制權傳回至外部堆疊上的下一個對話框。

如果您從外部內容呼叫 取消所有對話框 ，則會取消元件，以及外部內容上的其餘對話。

下一步

瞭解如何創建具有分支和迴圈的複雜交互作用。

處理用戶中斷

共用方式為

管理對話框複雜度

必要條件

關於範例

實作您的元件對話框

使用你的機器人呼叫對話框

測試您的機器人

其他資訊

元件對話框的取消運作方式

下一步

其他資源