A párbeszédpanel összetettségének kezelése

A KÖVETKEZŐKRE VONATKOZIK: SDK v4

Az összetevők párbeszédpaneleivel önálló párbeszédablakokat hozhat létre adott forgatókönyvek kezelésére, így a nagy párbeszédpanelek kezelhetőbb részekre bonthatók. Mindegyik darab saját párbeszédpanelkészlettel rendelkezik, és elkerüli, hogy a név összeütközjön a rajta kívüli párbeszédpanel-csoportokkal. Az összetevők párbeszédpanelei a következő módon használhatók újra:

• Hozzáadva egy másikhoz ComponentDialog vagy DialogSet a robothoz.
• Csomag részeként exportálva.
• Más robotokon belül használatos.

Feljegyzés

A Bot Framework JavaScript, C# és Python SDK-k továbbra is támogatottak lesznek, a Java SDK-t azonban 2023 novemberében végső hosszú távú támogatással kivonják.

A Java SDK-val létrehozott meglévő robotok továbbra is működni fognak.

Új robotépítéshez fontolja meg a Power Virtual Agents használatát, és olvassa el a megfelelő csevegőrobot-megoldás kiválasztását.

További információ: A robotépítés jövője.

Előfeltételek

• A robot alapjainak, a párbeszédtárnak és a beszélgetések kezelésének ismerete.
• A többfordulós parancssori minta másolata c#, JavaScript, Java vagy Python nyelven.

Tudnivalók a mintáról

A többfordulós parancssori mintában egy vízesés párbeszédpanelt, néhány kérdést és egy összetevő párbeszédpanelt használunk egy olyan interakció létrehozásához, amely kérdések sorozatát kérdezi fel a felhasználótól. A kód egy párbeszédpanel használatával lépeget az alábbi lépéseken:

Lépések	Parancssor típusa
Kérje meg a felhasználót a szállítás módjára	Választási lehetőségekre vonatkozó kérdés
Kérje meg a felhasználót, hogy adja meg a nevét	Szöveges üzenet
Kérdezze meg a felhasználót, hogy meg szeretné-e adni az életkorát	Megerősítési kérés
Ha igennel válaszoltak, kérjék meg a korukat	0-nál nagyobb és 150-nél kisebb korú, érvényesítéssel rendelkező számkérés.
Kérdezze meg, hogy az összegyűjtött adatok "rendben" vannak-e	Ismételt megerősítési kérés

Végül, ha igennel válaszoltak, jelenítse meg az összegyűjtött információkat; ellenkező esetben közölje a felhasználóval, hogy az adatai nem lesznek megőrzve.

Az összetevő implementálása párbeszédpanel

A többfordulós parancssori mintában egy vízesés párbeszédpanelt, néhány kérdést és egy összetevő párbeszédpanelt használunk egy olyan interakció létrehozásához, amely kérdések sorozatát kérdezi fel a felhasználótól.

Az összetevők párbeszédpaneljei egy vagy több párbeszédpanelt foglalnak össze. Az összetevő párbeszédpaneljének belső párbeszédpanel-készlete van, és a belső párbeszédpanel-készlethez hozzáadott párbeszédpanelek és kérések saját azonosítókkal rendelkeznek, amelyek csak az összetevő párbeszédpaneljén belül láthatók.

C#

A párbeszédpanelek használatához telepítse a Microsoft.Bot.Builder.Dialogs NuGet csomagot.

Párbeszédpanelek\UserProfileDialog.cs

Itt az UserProfileDialog osztály az ComponentDialog osztályból származik.

public class UserProfileDialog : ComponentDialog

A konstruktoron belül a AddDialog metódus párbeszédpaneleket és utasításokat ad hozzá az összetevő párbeszédpaneléhez. Az ezzel a módszerrel hozzáadott első elem a kezdeti párbeszédpanel. A kezdeti párbeszédpanelt módosíthatja a InitialDialogId tulajdonság explicit beállításával. Amikor elindít egy összetevő párbeszédpanelt, az elindítja a kezdeti párbeszédpanelt.

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

Az alábbi kód a vízesés párbeszédpanel első lépését jelöli.

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

A vízesés párbeszédpanelek implementálásával kapcsolatos további információkért tekintse meg a szekvenciális beszélgetési folyamat implementálását.

JavaScript

A párbeszédpanelek használatához a projektnek telepítenie kell a botbuilder-dialogs npm csomagot.

párbeszédpanelek/userProfileDialog.js

Itt az osztály kiterjeszti ComponentDialog.UserProfileDialog

class UserProfileDialog extends ComponentDialog {

A konstruktoron belül a AddDialog metódus párbeszédpaneleket és utasításokat ad hozzá az összetevő párbeszédpaneléhez. Az ezzel a módszerrel hozzáadott első elem a kezdeti párbeszédpanel. A kezdeti párbeszédpanelt módosíthatja a InitialDialogId tulajdonság explicit beállításával. Amikor elindít egy összetevő párbeszédpanelt, az elindítja a kezdeti párbeszédpanelt.

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

Az alábbi kód a vízesés párbeszédpanel első lépését jelöli.

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

A vízesés párbeszédpanelek implementálásával kapcsolatos további információkért tekintse meg a szekvenciális beszélgetési folyamat implementálását.

Java

UserProfileDialog.java

Itt az UserProfileDialog osztály az ComponentDialog osztályból származik.

public class UserProfileDialog extends ComponentDialog {

A konstruktoron belül a addDialog metódus párbeszédpaneleket és utasításokat ad hozzá az összetevő párbeszédpaneléhez. Az ezzel a módszerrel hozzáadott első elem a kezdeti párbeszédpanel. A kezdeti párbeszédpanelt a metódus meghívásával setInitialDialogId és a kezdeti párbeszédpanel nevének megadásával módosíthatja. Amikor elindít egy összetevő párbeszédpanelt, az elindítja a kezdeti párbeszédpanelt.

public UserProfileDialog(UserState withUserState) {
    super("UserProfileDialog");

    userProfileAccessor = withUserState.createProperty("UserProfile");

    WaterfallStep[] waterfallSteps = {
        UserProfileDialog::transportStep,
        UserProfileDialog::nameStep,
        this::nameConfirmStep,
        this::ageStep,
        UserProfileDialog::pictureStep,
        this::confirmStep,
        this::summaryStep
    };

    // Add named dialogs to the DialogSet. These names are saved in the dialog state.
    addDialog(new WaterfallDialog("WaterfallDialog", Arrays.asList(waterfallSteps)));
    addDialog(new TextPrompt("TextPrompt"));
    addDialog(new NumberPrompt<Integer>("NumberPrompt", UserProfileDialog::agePromptValidator, Integer.class));
    addDialog(new ChoicePrompt("ChoicePrompt"));
    addDialog(new ConfirmPrompt("ConfirmPrompt"));
    addDialog(new AttachmentPrompt("AttachmentPrompt", UserProfileDialog::picturePromptValidator));

    // The initial child Dialog to run.
    setInitialDialogId("WaterfallDialog");
}

Az alábbi kód a vízesés párbeszédpanel első lépését jelöli.

private static CompletableFuture<DialogTurnResult> nameStep(WaterfallStepContext stepContext) {
    stepContext.getValues().put("transport", ((FoundChoice) stepContext.getResult()).getValue());

    PromptOptions promptOptions = new PromptOptions();
    promptOptions.setPrompt(MessageFactory.text("Please enter your name."));
    return stepContext.prompt("TextPrompt", promptOptions);
}

A vízesés párbeszédpanelek implementálásával kapcsolatos további információkért tekintse meg a szekvenciális beszélgetési folyamat implementálását.

Python

A párbeszédpanelek használatához telepítse a botbuilder-dialogs és botbuilder-aiPyPI csomagokat egy terminál futtatásával pip install botbuilder-dialogs és pip install botbuilder-aihasználatával.

párbeszédpanelek/user_profile_dialog.py

Itt az osztály kiterjeszti ComponentDialog.UserProfileDialog

class UserProfileDialog(ComponentDialog):

A konstruktoron belül a add_dialog metódus párbeszédpaneleket és utasításokat ad hozzá az összetevő párbeszédpaneléhez. Az ezzel a módszerrel hozzáadott első elem a kezdeti párbeszédpanel. A kezdeti párbeszédpanelt módosíthatja a initial_dialog_id tulajdonság explicit beállításával. Amikor elindít egy összetevő párbeszédpanelt, az elindítja a kezdeti párbeszédpanelt.

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__

Az alábbi kód a vízesés párbeszédpanel első lépését jelöli.

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")],
        ),
    )

A vízesés párbeszédpanelek implementálásával kapcsolatos további információkért tekintse meg a szekvenciális beszélgetési folyamat implementálását.

Futtatáskor az összetevő párbeszédpanelje saját párbeszédpanel-vermet tart fenn. Az összetevő párbeszédpaneljének indításakor:

• Létrejön egy példány, és hozzáadódik a külső párbeszédpanel-veremhez
• Létrehoz egy belső párbeszédpanel-vermet, amelyet hozzáad az állapotához
• Elindítja a kezdeti párbeszédpanelt, és hozzáadja azt a belső párbeszédpanel-veremhez.

A szülőkörnyezet aktív párbeszédpanelként látja az összetevőt. Az összetevő környezetében azonban úgy tűnik, hogy a kezdeti párbeszédpanel az aktív párbeszédpanel.

A párbeszédpanel meghívása a robotból

A külső párbeszédpanel-készletben, amelyhez hozzáadta az összetevő párbeszédpanelt, az összetevő párbeszédpanelje rendelkezik azzal az azonosítóval, amellyel létrehozta. A külső csoportban az összetevő egyetlen párbeszédpanelnek tűnik, hasonlóan a parancssorokhoz.

Összetevő párbeszédpanel használatához adjon hozzá egy példányt a robot párbeszédpanelkészletéhez.

C#

Robotok\DialogBot.cs

A mintában ez a RunAsync robot OnMessageActivityAsync metódusából meghívott metódussal történik.

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

JavaScript

párbeszédpanelek/userProfileDialog.js

A mintában hozzáadtunk egy metódust run a felhasználói profil párbeszédpanelhez.

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

robotok/dialogBot.js

A run metódust a robot metódusából hívjuk onMessage meg.

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

Java

DialogBot.java

A mintában ez a run robot onMessageActivity metódusából meghívott metódussal történik.

@Override
protected CompletableFuture<Void> onMessageActivity(
    TurnContext turnContext
) {
    LoggerFactory.getLogger(DialogBot.class).info("Running dialog with Message Activity.");

    // Run the Dialog with the new message Activity.
    return Dialog.run(dialog, turnContext, conversationState.createProperty("DialogState"));
}

Python

segítők/dialog_helper.py

A mintában hozzáadtunk egy metódust run_dialog a felhasználói profil párbeszédpanelhez.

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)

A run_dialog robot on_message_activity metódusából hívott metódus.

robotok/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"),
    )

A robot tesztelése

1. Ha még nem tette meg, telepítse a Bot Framework Emulatort.
2. Futtassa a mintát helyileg a számítógépen.
3. Indítsa el az Emulátort, csatlakozzon a robothoz, és küldjön üzeneteket az alábbiak szerint.

További információk

A lemondás működése az összetevők párbeszédpaneljeinél

Ha az összetevő párbeszédpaneljének környezetéből az összes párbeszédpanel lemondását hívja meg, az összetevő párbeszédpanelje megszakítja a belső verem összes párbeszédpaneljét, majd véget ér, és visszakerül a külső verem következő párbeszédpaneljére.

Ha a külső környezet összes párbeszédpaneljének megszakítását hívja meg, az összetevőt a külső környezet többi párbeszédpanelével együtt a rendszer megszakítja.

Következő lépések

Megtudhatja, hogyan hozhat létre olyan összetett beszélgetéseket, amelyek elágaznak és hurkolnak.

Felhasználói megszakítások kezelése