İletişim kutusu karmaşıklığını yönetme

ŞUNLAR IÇIN GEÇERLIDIR: SDK v4

Bileşen iletişim kutularıyla, belirli senaryoları işlemek için bağımsız iletişim kutuları oluşturabilir ve büyük bir iletişim kutusu kümesini daha yönetilebilir parçalara ayırabilirsiniz. Bu parçaların her birinin kendi iletişim kutusu kümesi vardır ve dışındaki iletişim kutusu kümeleriyle ad çakışmalarını önler. Bileşen iletişim kutuları şu şekilde yeniden kullanılabilir:

• Başka bir ComponentDialog bota veya DialogSet botunuza eklendi.
• Bir paketin parçası olarak dışarı aktarılır.
• Diğer botlarda kullanılır.

Not

Bot Framework JavaScript, C# ve Python SDK'ları desteklenmeye devam edecektir, ancak Java SDK'sı son uzun vadeli destek Kasım 2023'te sona erecek şekilde kullanımdan kaldırılacaktır.

Java SDK ile oluşturulan mevcut botlar çalışmaya devam edecektir.

Yeni bot derlemesi için Power Virtual Agents'ı kullanmayı göz önünde bulundurun ve doğru sohbet botu çözümünü seçme hakkında bilgi edinin.

Daha fazla bilgi için bkz . Bot oluşturmanın geleceği.

Önkoşullar

• Bot temel bilgileri, iletişim kutusu kitaplığı ve konuşmaların nasıl yönetileceğini öğrenme.
• C#, JavaScript, Java veya Python'da çok aşamalı istem örneğinin bir kopyası.

Örnek hakkında

Çok aşamalı istem örneğinde, kullanıcıya bir dizi soru soran bir etkileşim oluşturmak için bir şelale iletişim kutusu, birkaç istem ve bir bileşen iletişim kutusu kullanırız. Kod, şu adımlar arasında geçiş yapmak için bir iletişim kutusu kullanır:

Adımlar	İstem türü
Kullanıcıdan taşıma modunu isteyin	Seçim istemi
Kullanıcıdan adını isteyin	Metin istemi
Kullanıcıya yaşını sağlamak isteyip istemediğini sorun	İstemi onayla
Evet yanıtı verdilerse, yaşını sorun	Yalnızca 0'dan büyük ve 150'den küçük yaşları kabul etmek için doğrulamaya sahip sayı istemi.
Toplanan bilgilerin "tamam" olup olmadığını sorun	Onayla istemini yeniden kullan

Son olarak evet yanıtı verdiyseniz toplanan bilgileri görüntüleyin; aksi takdirde, kullanıcıya bilgilerinin saklanmayacağını söyleyin.

Bileşen iletişim kutunuzu uygulama

Çok aşamalı istem örneğinde, kullanıcıya bir dizi soru soran bir etkileşim oluşturmak için bir şelale iletişim kutusu, birkaç istem ve bir bileşen iletişim kutusu kullanırız.

Bileşen iletişim kutusu bir veya daha fazla iletişim kutusunu kapsüller. Bileşen iletişim kutusunda bir iç iletişim kutusu kümesi vardır ve bu iç iletişim kutusu kümesine eklediğiniz iletişim kutuları ve istemler, yalnızca bileşen iletişim kutusunun içinden görünen kendi kimliklerine sahiptir.

C#

İletişim kutularını kullanmak için Microsoft.Bot.Builder.Dialogs NuGet paketini yükleyin.

İletişim Kutuları\UserProfileDialog.cs

UserProfileDialog Burada sınıfı sınıfından ComponentDialog türetilir.

public class UserProfileDialog : ComponentDialog

Oluşturucunun içinde yöntemi, AddDialog bileşen iletişim kutusuna iletişim kutuları ve istemler ekler. Bu yöntemle eklediğiniz ilk öğe, ilk iletişim kutusu olarak ayarlanır. özelliğini açıkça ayarlayarak InitialDialogId ilk iletişim kutusunu değiştirebilirsiniz. Bir bileşen iletişim kutusunu başlattığınızda, ilk iletişim kutusu başlatılır.

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

Aşağıdaki kod şelale iletişim kutusunun ilk adımını temsil eder.

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

Şelale iletişim kutularını uygulama hakkında daha fazla bilgi için bkz. Sıralı konuşma akışını uygulama.

JavaScript

İletişim kutularını kullanmak için projenizin botbuilder-dialogs npm paketini yüklemesi gerekir.

iletişim kutuları/userProfileDialog.js

UserProfileDialog Burada sınıfı genişletirComponentDialog.

class UserProfileDialog extends ComponentDialog {

Oluşturucunun içinde yöntemi, AddDialog bileşen iletişim kutusuna iletişim kutuları ve istemler ekler. Bu yöntemle eklediğiniz ilk öğe, ilk iletişim kutusu olarak ayarlanır. özelliğini açıkça ayarlayarak InitialDialogId ilk iletişim kutusunu değiştirebilirsiniz. Bir bileşen iletişim kutusunu başlattığınızda, ilk iletişim kutusu başlatılır.

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

Aşağıdaki kod şelale iletişim kutusunun ilk adımını temsil eder.

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

Şelale iletişim kutularını uygulama hakkında daha fazla bilgi için bkz. Sıralı konuşma akışını uygulama.

Java

UserProfileDialog.java

UserProfileDialog Burada sınıfı sınıfından ComponentDialog türetilir.

public class UserProfileDialog extends ComponentDialog {

Oluşturucunun içinde yöntemi, addDialog bileşen iletişim kutusuna iletişim kutuları ve istemler ekler. Bu yöntemle eklediğiniz ilk öğe, ilk iletişim kutusu olarak ayarlanır. yöntemini çağırarak setInitialDialogId ilk iletişim kutusunu değiştirebilir ve ilk iletişim kutusunun adını sağlayabilirsiniz. Bir bileşen iletişim kutusunu başlattığınızda, ilk iletişim kutusu başlatılır.

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

Aşağıdaki kod şelale iletişim kutusunun ilk adımını temsil eder.

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

Şelale iletişim kutularını uygulama hakkında daha fazla bilgi için bkz. Sıralı konuşma akışını uygulama.

Python

İletişim kutularını kullanmak için bir terminalden çalıştırarak pip install botbuilder-aipip install botbuilder-dialogs botbuilder-dialogs ve botbuilder-ai PyPI paketlerini yükleyin.

iletişim kutuları/user_profile_dialog.py

UserProfileDialog Burada sınıfı genişletirComponentDialog.

class UserProfileDialog(ComponentDialog):

Oluşturucunun içinde yöntemi, add_dialog bileşen iletişim kutusuna iletişim kutuları ve istemler ekler. Bu yöntemle eklediğiniz ilk öğe, ilk iletişim kutusu olarak ayarlanır. özelliğini açıkça ayarlayarak initial_dialog_id ilk iletişim kutusunu değiştirebilirsiniz. Bir bileşen iletişim kutusunu başlattığınızda, ilk iletişim kutusu başlatılır.

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__

Aşağıdaki kod şelale iletişim kutusunun ilk adımını temsil eder.

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

Şelale iletişim kutularını uygulama hakkında daha fazla bilgi için bkz. Sıralı konuşma akışını uygulama.

Çalışma zamanında, bileşen iletişim kutusu kendi iletişim kutusu yığınını korur. Bileşen iletişim kutusu başlatıldığında:

• Bir örnek oluşturulur ve dış iletişim kutusu yığınına eklenir
• Durumuna eklediği bir iç iletişim kutusu yığını oluşturur
• İlk iletişim kutusunu başlatır ve bunu iç iletişim kutusu yığınına ekler.

Üst bağlam, bileşeni etkin iletişim kutusu olarak görür. Ancak, bileşenin içindeki bağlama göre, ilk iletişim kutusu etkin iletişim kutusu gibi görünür.

Botunuzdan iletişim kutusunu arama

Bileşen iletişim kutusunu eklediğiniz dış iletişim kutusu kümesinde, bileşen iletişim kutusunda oluşturduğunuz kimlik bulunur. Dış kümede bileşen, istemlerin olduğu gibi tek bir iletişim kutusu gibi görünür.

Bileşen iletişim kutusunu kullanmak için botun iletişim kutusu kümesine bunun bir örneğini ekleyin.

C#

Botlar\DialogBot.cs

Örnekte bu işlem bot OnMessageActivityAsync yönteminden RunAsync çağrılan yöntem kullanılarak gerçekleştirilir.

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

iletişim kutuları/userProfileDialog.js

Örnekte, kullanıcı profili iletişim kutusuna bir run yöntem ekledik.

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

botlar/dialogBot.js

run yöntemi botunun onMessage yönteminden çağrılır.

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

Örnekte bu işlem bot onMessageActivity yönteminden run çağrılan yöntem kullanılarak gerçekleştirilir.

@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

yardımcılar/dialog_helper.py

Örnekte, kullanıcı profili iletişim kutusuna bir run_dialog yöntem ekledik.

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)

run_dialog Bot on_message_activity yönteminden çağrılan yöntem.

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

Botunuzu test etme

1. Henüz yapmadıysanız Bot Framework Öykünücüsü'ni yükleyin.
2. Örneği makinenizde yerel olarak çalıştırın.
3. Emulator'ı başlatın, botunuza bağlanın ve aşağıda gösterildiği gibi ileti gönderin.

Ek bilgi

bileşen iletişim kutuları için iptal nasıl çalışır?

Bileşen iletişim kutusunun bağlamındaki tüm iletişim kutularını iptal et çağrısı yaparsanız, bileşen iletişim kutusu iç yığınındaki tüm iletişim kutularını iptal eder ve ardından denetimi dış yığındaki bir sonraki iletişim kutusuna döndürerek sonlanır.

Dış bağlamdaki tüm iletişim kutularını iptal et çağrısı yaparsanız bileşen, dış bağlamdaki iletişim kutularının geri kalanıyla birlikte iptal edilir.

Sonraki adımlar

Dallanıp döngüye alınabilen karmaşık konuşmalar oluşturmayı öğrenin.

Kullanıcı kesintilerini işleme