Hantera dialogkomplexitet

GÄLLER FÖR: SDK v4

Med komponentdialogrutor kan du skapa oberoende dialogrutor för att hantera specifika scenarier och dela upp en stor dialogruta i mer hanterbara delar. Var och en av dessa delar har en egen dialogruta och undviker eventuella namnkollisioner med dialogrutorna utanför den. Komponentdialogrutor kan återanvändas på så sätt att de kan vara:

• Har lagts till i en annan ComponentDialog eller DialogSet i din robot.
• Exporteras som en del av ett paket.
• Används i andra robotar.

Kommentar

Bot Framework JavaScript-, C#- och Python-SDK:erna fortsätter att stödjas, men Java SDK dras tillbaka med slutligt långsiktigt stöd som slutar i november 2023.

Befintliga robotar som skapats med Java SDK fortsätter att fungera.

Om du vill skapa en ny robot kan du använda Microsoft Copilot Studio och läsa om hur du väljer rätt copilot-lösning.

Mer information finns i Framtiden för robotbygge.

Förutsättningar

• Kunskap om grunderna i roboten , dialogrutebiblioteket och hur du hanterar konversationer.
• En kopia av exemplet med fråga med flera svar i C#, JavaScript, Java eller Python.

Om exemplet

I exemplet med fråga med flera svar använder vi en vattenfallsdialogruta, några frågor och en komponentdialogruta för att skapa en interaktion som ställer en rad frågor till användaren. Koden använder en dialogruta för att gå igenom följande steg:

Steg	Typ av fråga
Be användaren om deras transportsätt	Kommandotolk för val
Be användaren om deras namn	Textprompt
Fråga användaren om de vill ange sin ålder	Bekräfta uppmaning
Om de svarade ja, be om deras ålder	Talprompt med validering för att endast acceptera åldrar som är större än 0 och mindre än 150.
Fråga om den insamlade informationen är "ok"	Fråga om att bekräfta återanvändning

Slutligen, om de svarade ja, visa den insamlade informationen; Annars kan du tala om för användaren att deras information inte sparas.

Implementera din komponentdialogruta

I exemplet med fråga med flera svar använder vi en vattenfallsdialogruta, några frågor och en komponentdialogruta för att skapa en interaktion som ställer en rad frågor till användaren.

En komponentdialogruta kapslar in en eller flera dialogrutor. Komponentdialogrutan har en inre dialogruta, och dialogrutorna och uppmaningarna som du lägger till i den inre dialogrutan har egna ID:n som endast visas inifrån komponentdialogrutan.

C#

Om du vill använda dialogrutor installerar du NuGet-paketet Microsoft.Bot.Builder.Dialogs .

Dialogrutor\UserProfileDialog.cs

UserProfileDialog Här härleds klassen från ComponentDialog klassen.

public class UserProfileDialog : ComponentDialog

I konstruktorn AddDialog lägger metoden till dialogrutor och uppmaningar i komponentdialogrutan. Det första objektet som du lägger till med den här metoden anges som den inledande dialogrutan. Du kan ändra den inledande dialogrutan genom att uttryckligen ange egenskapen InitialDialogId . När du startar en komponentdialogruta startar den sin inledande dialogruta.

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

Följande kod representerar det första steget i vattenfallsdialogrutan.

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

Mer information om hur du implementerar vattenfallsdialogrutor finns i implementera sekventiellt konversationsflöde.

JavaScript

Om du vill använda dialogrutor måste projektet installera npm-paketet botbuilder-dialogs .

dialogrutor/userProfileDialog.js

UserProfileDialog Här utökas ComponentDialogklassen .

class UserProfileDialog extends ComponentDialog {

I konstruktorn AddDialog lägger metoden till dialogrutor och uppmaningar i komponentdialogrutan. Det första objektet som du lägger till med den här metoden anges som den inledande dialogrutan. Du kan ändra den inledande dialogrutan genom att uttryckligen ange egenskapen InitialDialogId . När du startar en komponentdialogruta startar den sin inledande dialogruta.

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

Följande kod representerar det första steget i vattenfallsdialogrutan.

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

Mer information om hur du implementerar vattenfallsdialogrutor finns i implementera sekventiellt konversationsflöde.

Java

UserProfileDialog.java

UserProfileDialog Här härleds klassen från ComponentDialog klassen.

public class UserProfileDialog extends ComponentDialog {

I konstruktorn addDialog lägger metoden till dialogrutor och uppmaningar i komponentdialogrutan. Det första objektet som du lägger till med den här metoden anges som den inledande dialogrutan. Du kan ändra den inledande dialogrutan genom att anropa setInitialDialogId metoden och ange namnet på den inledande dialogrutan. När du startar en komponentdialogruta startar den sin inledande dialogruta.

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

Följande kod representerar det första steget i vattenfallsdialogrutan.

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

Mer information om hur du implementerar vattenfallsdialogrutor finns i implementera sekventiellt konversationsflöde.

Python

Om du vill använda dialogrutor installerar du botbuilder-dialogrutor och botbuilder-ai PyPI-paket genom att köra pip install botbuilder-dialogs och pip install botbuilder-ai från en terminal.

dialogrutor/user_profile_dialog.py

UserProfileDialog Här utökas ComponentDialogklassen .

class UserProfileDialog(ComponentDialog):

I konstruktorn add_dialog lägger metoden till dialogrutor och uppmaningar i komponentdialogrutan. Det första objektet som du lägger till med den här metoden anges som den inledande dialogrutan. Du kan ändra den inledande dialogrutan genom att uttryckligen ange egenskapen initial_dialog_id . När du startar en komponentdialogruta startar den sin inledande dialogruta.

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__

Följande kod representerar det första steget i vattenfallsdialogrutan.

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

Mer information om hur du implementerar vattenfallsdialogrutor finns i implementera sekventiellt konversationsflöde.

Vid körning behåller komponentdialogrutan en egen dialogstack. När komponentdialogrutan startas:

• En instans skapas och läggs till i den yttre dialogstacken
• Den skapar en inre dialogstack som läggs till i dess tillstånd
• Den startar den inledande dialogrutan och lägger till den i den inre dialogstacken.

Den överordnade kontexten ser komponenten som den aktiva dialogrutan. För kontexten i komponenten ser det dock ut som att den inledande dialogrutan är den aktiva dialogrutan.

Anropa dialogrutan från din robot

I den yttre dialogrutan, den som du lade till komponentdialogrutan till, har komponentdialogrutan det ID som du skapade den med. I den yttre uppsättningen ser komponenten ut som en enda dialogruta, ungefär som prompterna gör.

Om du vill använda en komponentdialogruta lägger du till en instans av den i robotens dialogruta.

C#

Robotar\DialogBot.cs

I exemplet görs detta med hjälp av metoden RunAsync som anropas från robotens OnMessageActivityAsync metod.

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

dialogrutor/userProfileDialog.js

I exemplet har vi lagt till en run metod i dialogrutan användarprofil.

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

robotar/dialogBot.js

Metoden run anropas från robotens onMessage metod.

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

I exemplet görs detta med hjälp av metoden run som anropas från robotens onMessageActivity metod.

@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

hjälp/dialog_helper.py

I exemplet har vi lagt till en run_dialog metod i dialogrutan användarprofil.

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)

Den run_dialog metod som anropas från robotens on_message_activity metod.

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

Testa din robot

1. Om du inte redan har gjort det installerar du Bot Framework-emulatorn.
2. Kör exemplet lokalt på datorn.
3. Starta emulatorn, anslut till roboten och skicka meddelanden enligt nedan.

Ytterligare information

Så här fungerar annullering för komponentdialogrutor

Om du anropar avbryt alla dialogrutor från komponentdialogrutans kontext kommer komponentdialogrutan att avbryta alla dialogrutor i den inre stacken och sedan avslutas, vilket returnerar kontrollen till nästa dialogruta i den yttre stacken.

Om du anropar avbryt alla dialogrutor från den yttre kontexten avbryts komponenten, tillsammans med resten av dialogrutorna i den yttre kontexten.

Nästa steg

Lär dig hur du skapar komplexa konversationer som förgrenar och loopar.

Hantera användaravbrott