Zarządzanie złożonością okna dialogowego

DOTYCZY: ZESTAW SDK w wersji 4

Za pomocą okien dialogowych składników można tworzyć niezależne okna dialogowe do obsługi określonych scenariuszy, przerywając duży zestaw okien dialogowych na bardziej zarządzane elementy. Każdy z tych elementów ma własny zestaw okien dialogowych i unika kolizji nazw z zestawami okien dialogowych poza nimi. Okna dialogowe składników są wielokrotnego użytku, które mogą być następujące:

• Dodano element do innego ComponentDialog lub DialogSet bota.
• Wyeksportowane jako część pakietu.
• Używane w innych botach.

Uwaga

Zestawy SDK języka JavaScript, C# i Python platformy Bot Framework będą nadal obsługiwane, jednak zestaw SDK języka Java jest wycofywany z ostatecznym długoterminowym wsparciem kończącym się w listopadzie 2023 r.

Istniejące boty utworzone za pomocą zestawu JAVA SDK będą nadal działać.

W przypadku tworzenia nowego bota rozważ użycie agentów usługi Power Virtual Agents i przeczytaj o wyborze odpowiedniego rozwiązania czatbota.

Aby uzyskać więcej informacji, zobacz Przyszłość tworzenia botów.

Wymagania wstępne

• Znajomość podstaw bota, biblioteki okien dialogowych i sposobu zarządzania konwersacjami.
• Kopia przykładu z wieloma krokami w języku C#, JavaScript, Java lub Python.

Informacje o przykładzie

W przykładzie z wieloma krokami użyjemy okna dialogowego kaskadowego, kilku monitów i okna dialogowego składnika, aby utworzyć interakcję, która zadaje użytkownikowi serię pytań. Kod używa okna dialogowego, aby wykonać następujące kroki:

Kroki	Typ monitu
Poproś użytkownika o sposób transportu	Monit o wybór
Poproś użytkownika o podanie swojej nazwy	Monit tekstowy
Zapytaj użytkownika, czy chce podać swój wiek	Potwierdź monit
Jeśli odpowiedzieli tak, poproś o swój wiek	Monit o podanie numeru z walidacją umożliwiający zaakceptowanie wieku większego niż 0 i mniej niż 150.
Zapytaj, czy zebrane informacje są "ok"	Ponowne użycie monitu potwierdzania

Na koniec, jeśli odpowiedzieli tak, wyświetl zebrane informacje; w przeciwnym razie poinformuj użytkownika, że ich informacje nie będą przechowywane.

Okno dialogowe Implementowanie składnika

W przykładzie z wieloma krokami użyjemy okna dialogowego kaskadowego, kilku monitów i okna dialogowego składnika, aby utworzyć interakcję, która zadaje użytkownikowi serię pytań.

Okno dialogowe składnika hermetyzuje co najmniej jedno okno dialogowe. Okno dialogowe składnika ma wewnętrzny zestaw okien dialogowych, a okna dialogowe i monity dodane do tego wewnętrznego zestawu okien dialogowych mają własne identyfikatory widoczne tylko w oknie dialogowym składnika.

C#

Aby użyć okien dialogowych, zainstaluj pakiet NuGet Microsoft.Bot.Builder.Dialogs .

Dialogs\UserProfileDialog.cs

W tym UserProfileDialog przypadku klasa pochodzi z ComponentDialog klasy .

public class UserProfileDialog : ComponentDialog

W konstruktorze AddDialog metoda dodaje okna dialogowe i monity do okna dialogowego składnika. Pierwszy element dodany za pomocą tej metody jest ustawiany jako początkowe okno dialogowe. Początkowe okno dialogowe można zmienić, jawnie ustawiając InitialDialogId właściwość . Po uruchomieniu okna dialogowego składnika zostanie uruchomione jego początkowe okno dialogowe.

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

Poniższy kod reprezentuje pierwszy krok okna dialogowego kaskadowego.

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

Aby uzyskać więcej informacji na temat implementowania okien dialogowych kaskadowych, zobacz implementowanie sekwencyjnego przepływu konwersacji.

JavaScript

Aby użyć okien dialogowych, projekt musi zainstalować pakiet npm botbuilder-dialogs .

okna dialogowe/userProfileDialog.js

W tym miejscu klasa rozszerza klasę UserProfileDialogComponentDialog.

class UserProfileDialog extends ComponentDialog {

W konstruktorze AddDialog metoda dodaje okna dialogowe i monity do okna dialogowego składnika. Pierwszy element dodany za pomocą tej metody jest ustawiany jako początkowe okno dialogowe. Początkowe okno dialogowe można zmienić, jawnie ustawiając InitialDialogId właściwość . Po uruchomieniu okna dialogowego składnika zostanie uruchomione jego początkowe okno dialogowe.

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

Poniższy kod reprezentuje pierwszy krok okna dialogowego kaskadowego.

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

Aby uzyskać więcej informacji na temat implementowania okien dialogowych kaskadowych, zobacz implementowanie sekwencyjnego przepływu konwersacji.

Java

UserProfileDialog.java

W tym UserProfileDialog przypadku klasa pochodzi z ComponentDialog klasy .

public class UserProfileDialog extends ComponentDialog {

W konstruktorze addDialog metoda dodaje okna dialogowe i monity do okna dialogowego składnika. Pierwszy element dodany za pomocą tej metody jest ustawiany jako początkowe okno dialogowe. Początkowe okno dialogowe można zmienić, wywołując metodę setInitialDialogId i podając nazwę początkowego okna dialogowego. Po uruchomieniu okna dialogowego składnika zostanie uruchomione jego początkowe okno dialogowe.

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

Poniższy kod reprezentuje pierwszy krok okna dialogowego kaskadowego.

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

Aby uzyskać więcej informacji na temat implementowania okien dialogowych kaskadowych, zobacz implementowanie sekwencyjnego przepływu konwersacji.

Python

Aby użyć okien dialogowych, zainstaluj pakiety botbuilder-dialogs i botbuilder-ai PyPI, uruchamiając pip install botbuilder-dialogs polecenie i pip install botbuilder-ai z terminalu.

okna dialogowe/user_profile_dialog.py

W tym miejscu klasa rozszerza klasę UserProfileDialogComponentDialog.

class UserProfileDialog(ComponentDialog):

W konstruktorze add_dialog metoda dodaje okna dialogowe i monity do okna dialogowego składnika. Pierwszy element dodany za pomocą tej metody jest ustawiany jako początkowe okno dialogowe. Początkowe okno dialogowe można zmienić, jawnie ustawiając initial_dialog_id właściwość . Po uruchomieniu okna dialogowego składnika zostanie uruchomione jego początkowe okno dialogowe.

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__

Poniższy kod reprezentuje pierwszy krok okna dialogowego kaskadowego.

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

Aby uzyskać więcej informacji na temat implementowania okien dialogowych kaskadowych, zobacz implementowanie sekwencyjnego przepływu konwersacji.

W czasie wykonywania okno dialogowe składnika utrzymuje własny stos okien dialogowych. Po uruchomieniu okna dialogowego składnika:

• Wystąpienie jest tworzone i dodawane do zewnętrznego stosu okien dialogowych
• Tworzy wewnętrzny stos okna dialogowego, który dodaje do stanu
• Uruchamia początkowe okno dialogowe i dodaje je do wewnętrznego stosu okien dialogowych.

Kontekst nadrzędny widzi składnik jako aktywne okno dialogowe. Jednak kontekst wewnątrz składnika wygląda tak, jakby początkowe okno dialogowe było aktywnym dialogem.

Wywoływanie okna dialogowego z bota

W zewnętrznym zestawie okien dialogowych, do którego dodano okno dialogowe składnika, okno dialogowe składnika ma identyfikator, za pomocą którego został utworzony. W zestawie zewnętrznym składnik wygląda jak pojedyncze okno dialogowe, podobnie jak monity.

Aby użyć okna dialogowego składnika, dodaj wystąpienie do zestawu okien dialogowych bota.

C#

Bots\DialogBot.cs

W przykładzie jest to wykonywane przy użyciu RunAsync metody wywoływanej z metody bota OnMessageActivityAsync .

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

okna dialogowe/userProfileDialog.js

W przykładzie dodaliśmy metodę run do okna dialogowego profilu użytkownika.

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

boty/dialogBot.js

Metoda run jest wywoływana z metody bota 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();
});

Java

DialogBot.java

W przykładzie jest to wykonywane przy użyciu run metody wywoływanej z metody bota onMessageActivity .

@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

pomocnicy/dialog_helper.py

W przykładzie dodaliśmy metodę run_dialog do okna dialogowego profilu użytkownika.

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)

Metoda run_dialog wywoływana z metody bota on_message_activity .

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

Testowanie bota

1. Jeśli jeszcze tego nie zrobiono, zainstaluj program Bot Framework Emulator.
2. Uruchom przykład lokalnie na maszynie.
3. Uruchom emulator, połącz się z botem i wyślij komunikaty, jak pokazano poniżej.

Dodatkowe informacje

Jak działa anulowanie w oknach dialogowych składników

Jeśli wywołasz anulowanie wszystkich okien dialogowych z kontekstu okna dialogowego składnika, okno dialogowe składnika spowoduje anulowanie wszystkich okien dialogowych na stosie wewnętrznym, a następnie zakończenie, powrót kontrolki do następnego okna dialogowego na stosie zewnętrznym.

Jeśli wywołasz anulowanie wszystkich okien dialogowych z kontekstu zewnętrznego, składnik zostanie anulowany wraz z resztą okien dialogowych w kontekście zewnętrznym.

Następne kroki

Dowiedz się, jak tworzyć złożone konwersacje, które rozgałęzić i pętli.

Obsługa przerw w działaniu użytkowników