Aracılığıyla paylaş

Dalları ve döngüleri kullanarak gelişmiş konuşma akışı oluşturma

  • Makale

ŞUNLAR IÇIN GEÇERLIDIR: SDK v4

İletişim kutusu kitaplığını kullanarak karmaşık konuşma akışları oluşturabilirsiniz. Bu makalede dallanıp döngü yapılan karmaşık konuşmaların nasıl yönetileceğini ve iletişim kutusunun farklı bölümleri arasında bağımsız değişkenlerin nasıl geçirileceğini açıklar.

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

Bu örnek hakkında

Bu örnek, bir listeden en fazla iki şirketi gözden geçirmek için kullanıcılara kaydolabilen bir botu temsil eder. Bot, konuşma akışını yönetmek için üç bileşen iletişim kutusu kullanır. Her bileşen iletişim kutusunda bir şelale iletişim kutusu ve kullanıcı girişini toplamak için gereken tüm istemler bulunur. Bu iletişim kutuları aşağıdaki bölümlerde daha ayrıntılı olarak açıklanmıştır. İletişim kutularını yönetmek için konuşma durumunu kullanır ve kullanıcı ve gözden geçirmek istediği şirketler hakkındaki bilgileri kaydetmek için kullanıcı durumunu kullanır.

Bot, etkinlik işleyicisinden türetilir. Örnek botların birçoğu gibi, kullanıcıyı da kabul eder, kullanıcıdan gelen iletileri işlemek için iletişim kutularını kullanır ve dönüş bitmeden önce kullanıcı ve konuşma durumunu kaydeder.

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

C# örneği için sınıf diyagramı.

Kullanıcı profilini tanımlama

Kullanıcı profili iletişim kutuları tarafından toplanan bilgileri, kullanıcının adını, yaşını ve gözden geçirmek üzere seçilen şirketleri içerir.

UserProfile.cs

/// <summary>Contains information about a user.</summary>
public class UserProfile
{
    public string Name { get; set; }

    public int Age { get; set; }

    // The list of companies the user wants to review.
    public List<string> CompaniesToReview { get; set; } = new List<string>();

İletişim kutularını oluşturma

Bu bot üç iletişim kutusu içerir:

  • Ana iletişim kutusu genel işlemi başlatır ve toplanan bilgileri özetler.
  • Üst düzey iletişim kutusu kullanıcı bilgilerini toplar ve kullanıcının yaşına göre dallanma mantığını içerir.
  • Gözden geçirme seçimi iletişim kutusu, kullanıcının gözden geçirmek istediğiniz şirketleri yinelemeli olarak seçmesine olanak tanır. Bunu yapmak için döngü mantığını kullanır.

Ana iletişim kutusu

Ana iletişim kutusunun iki adımı vardır:

  1. Üst düzey iletişim kutusunu başlatın.
  2. Üst düzey iletişim kutusunun topladığı kullanıcı profilini alın ve özetleyin, bu bilgileri kullanıcı durumuna kaydedin ve ardından ana iletişim kutusunun sonuna işaret edin.

İletişim Kutuları\MainDialog.cs

private async Task<DialogTurnResult> InitialStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
{
    return await stepContext.BeginDialogAsync(nameof(TopLevelDialog), null, cancellationToken);
}

private async Task<DialogTurnResult> FinalStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
{
    var userInfo = (UserProfile)stepContext.Result;

    string status = "You are signed up to review "
        + (userInfo.CompaniesToReview.Count is 0 ? "no companies" : string.Join(" and ", userInfo.CompaniesToReview))
        + ".";

    await stepContext.Context.SendActivityAsync(status);

    var accessor = _userState.CreateProperty<UserProfile>(nameof(UserProfile));
    await accessor.SetAsync(stepContext.Context, userInfo, cancellationToken);

    return await stepContext.EndDialogAsync(null, cancellationToken);
}

Üst düzey iletişim kutusu

Üst düzey iletişim kutusunda dört adım vardır:

  1. Kullanıcının adını isteyin.
  2. Kullanıcının yaşını sorun.
  3. Gözden geçirme seçimi iletişim kutusunu başlatın veya kullanıcının yaşına göre sonraki adıma ilerleyin.
  4. Son olarak, kullanıcıya katıldığı için teşekkür edin ve toplanan bilgileri iade edin.

İlk adım, iletişim kutusu durumunun bir parçası olarak boş bir kullanıcı profili oluşturur. İletişim kutusu boş bir profille başlar ve ilerledikçe profile bilgi ekler. Sona erdiğinde, son adım toplanan bilgileri döndürür.

Üçüncü (seçimi başlat) adımında, konuşma akışı kullanıcının yaşına göre dalır.

İletişim Kutuları\TopLevelDialog.cs

            stepContext.Values[UserInfo] = new UserProfile();

            var promptOptions = new PromptOptions { Prompt = MessageFactory.Text("Please enter your name.") };

            // Ask the user to enter their name.
            return await stepContext.PromptAsync(nameof(TextPrompt), promptOptions, cancellationToken);
        }

        private async Task<DialogTurnResult> AgeStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
        {
            // Set the user's name to what they entered in response to the name prompt.
            var userProfile = (UserProfile)stepContext.Values[UserInfo];
            userProfile.Name = (string)stepContext.Result;

            var promptOptions = new PromptOptions { Prompt = MessageFactory.Text("Please enter your age.") };

            // Ask the user to enter their age.
            return await stepContext.PromptAsync(nameof(NumberPrompt<int>), promptOptions, cancellationToken);
        }

        private async Task<DialogTurnResult> StartSelectionStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
        {
            // Set the user's age to what they entered in response to the age prompt.
            var userProfile = (UserProfile)stepContext.Values[UserInfo];
            userProfile.Age = (int)stepContext.Result;

            if (userProfile.Age < 25)
            {
                // If they are too young, skip the review selection dialog, and pass an empty list to the next step.
                await stepContext.Context.SendActivityAsync(
                    MessageFactory.Text("You must be 25 or older to participate."),
                    cancellationToken);
                return await stepContext.NextAsync(new List<string>(), cancellationToken);
            }
            else
            {
                // Otherwise, start the review selection dialog.
                return await stepContext.BeginDialogAsync(nameof(ReviewSelectionDialog), null, cancellationToken);
            }
        }

        private async Task<DialogTurnResult> AcknowledgementStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
        {
            // Set the user's company selection to what they entered in the review-selection dialog.
            var userProfile = (UserProfile)stepContext.Values[UserInfo];
            userProfile.CompaniesToReview = stepContext.Result as List<string> ?? new List<string>();

            // Thank them for participating.
            await stepContext.Context.SendActivityAsync(
                MessageFactory.Text($"Thanks for participating, {((UserProfile)stepContext.Values[UserInfo]).Name}."),
                cancellationToken);

            // Exit the dialog, returning the collected user information.
            return await stepContext.EndDialogAsync(stepContext.Values[UserInfo], cancellationToken);
        }
    }
}

Seçimi gözden geçirme iletişim kutusu

Gözden geçirme seçimi iletişim kutusunda iki adım vardır:

  1. Kullanıcıdan gözden geçireceği veya done bitirileceği bir şirket seçmesini isteyin.
    • İletişim kutusu herhangi bir ilk bilgiyle başlatıldıysa, bilgiler şelale adımı bağlamının options özelliği aracılığıyla sağlanır. Gözden geçirme seçimi iletişim kutusu kendisini yeniden başlatabilir ve kullanıcının gözden geçirmek üzere birden fazla şirket seçmesine izin vermek için bunu kullanır.
    • Kullanıcı gözden geçirmek üzere zaten bir şirket seçtiyse, bu şirket kullanılabilir seçeneklerden kaldırılır.
    • done Kullanıcının döngüden erken çıkmasını sağlamak için bir seçenek eklenir.
  2. Bu iletişim kutusunu yineleyin veya uygun şekilde çıkın.
    • Kullanıcı gözden geçirmek için bir şirket seçtiyse, bu şirketi kendi listesine ekleyin.
    • Kullanıcı iki şirket seçtiyse veya çıkmayı seçtiyse, iletişim kutusunu sonlandırın ve toplanan listeyi geri gönderin.
    • Aksi takdirde, iletişim kutusunu yeniden başlatarak listelerinin içeriğiyle başlatın.

İletişim Kutuları\ReviewSelectionDialog.cs

private async Task<DialogTurnResult> SelectionStepAsync(
    WaterfallStepContext stepContext,
    CancellationToken cancellationToken)
{
    // Continue using the same selection list, if any, from the previous iteration of this dialog.
    var list = stepContext.Options as List<string> ?? new List<string>();
    stepContext.Values[CompaniesSelected] = list;

    // Create a prompt message.
    string message;
    if (list.Count is 0)
    {
        message = $"Please choose a company to review, or `{DoneOption}` to finish.";
    }
    else
    {
        message = $"You have selected **{list[0]}**. You can review an additional company, " +
            $"or choose `{DoneOption}` to finish.";
    }

    // Create the list of options to choose from.
    var options = _companyOptions.ToList();
    options.Add(DoneOption);
    if (list.Count > 0)
    {
        options.Remove(list[0]);
    }

    var promptOptions = new PromptOptions
    {
        Prompt = MessageFactory.Text(message),
        RetryPrompt = MessageFactory.Text("Please choose an option from the list."),
        Choices = ChoiceFactory.ToChoices(options),
    };

    // Prompt the user for a choice.
    return await stepContext.PromptAsync(nameof(ChoicePrompt), promptOptions, cancellationToken);
}

private async Task<DialogTurnResult> LoopStepAsync(
    WaterfallStepContext stepContext,
    CancellationToken cancellationToken)
{
    // Retrieve their selection list, the choice they made, and whether they chose to finish.
    var list = stepContext.Values[CompaniesSelected] as List<string>;
    var choice = (FoundChoice)stepContext.Result;
    var done = choice.Value == DoneOption;

    if (!done)
    {
        // If they chose a company, add it to the list.
        list.Add(choice.Value);
    }

    if (done || list.Count >= 2)
    {
        // If they're done, exit and return their list.
        return await stepContext.EndDialogAsync(list, cancellationToken);
    }
    else
    {
        // Otherwise, repeat this dialog, passing in the list from this iteration.
        return await stepContext.ReplaceDialogAsync(InitialDialogId, list, cancellationToken);
    }
}

İletişim kutularını çalıştırma

İletişim kutusu bot sınıfı etkinlik işleyicisini genişletir ve iletişim kutularını çalıştırma mantığını içerir. İletişim kutusu ve hoş geldiniz botu sınıfı, iletişim kutusu botunu, konuşmaya katılan bir kullanıcıyı da karşılayacak şekilde genişletir.

Bot'un dönüş işleyicisi, üç iletişim kutusu tarafından tanımlanan konuşma akışını yineler. Kullanıcıdan bir ileti aldığında:

  1. Ana iletişim kutusunu çalıştırır.
    • İletişim kutusu yığını boşsa, bu işlem ana iletişim kutusunu başlatır.
    • Aksi takdirde, iletişim kutuları hala işlemin ortasındadır ve bu işlem etkin iletişim kutusuna devam eder.
  2. Kullanıcı, konuşma ve iletişim durumu güncelleştirmelerinin kalıcı olması için durumu kaydeder.

Botlar\DialogBot.cs

public override async Task OnTurnAsync(ITurnContext turnContext, CancellationToken cancellationToken = default(CancellationToken))
{
    await base.OnTurnAsync(turnContext, cancellationToken);

    // Save any state changes that might have occurred during the turn.
    await ConversationState.SaveChangesAsync(turnContext, false, cancellationToken);
    await UserState.SaveChangesAsync(turnContext, false, cancellationToken);
}

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

Bot için hizmetleri kaydetme

Gerektiğinde hizmetleri oluşturun ve kaydedin:

  • Bot için temel hizmetler: bağdaştırıcı ve bot uygulaması.
  • Durumu yönetmeye yönelik hizmetler: depolama, kullanıcı durumu ve konuşma durumu.
  • Botunun kullanacağı kök iletişim kutusu.

Startup.cs

// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
    services.AddHttpClient().AddControllers().AddNewtonsoftJson(options =>
    {
        options.SerializerSettings.MaxDepth = HttpHelper.BotMessageSerializerSettings.MaxDepth;
    });

    // Create the Bot Framework Authentication to be used with the Bot Adapter.
    services.AddSingleton<BotFrameworkAuthentication, ConfigurationBotFrameworkAuthentication>();

    // Create the Bot Adapter with error handling enabled.
    services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>();

    // Create the storage we'll be using for User and Conversation state. (Memory is great for testing purposes.)
    services.AddSingleton<IStorage, MemoryStorage>();

    // Create the User state. (Used in this bot's Dialog implementation.)
    services.AddSingleton<UserState>();

Not

Bellek depolama yalnızca test amacıyla kullanılır ve üretim kullanımı için tasarlanmamıştır. Üretim botu için kalıcı bir depolama türü kullandığınızdan emin olun.

Botu test edin

  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.

    Karmaşık iletişim kutusu botuyla yapılan konuşmadan örnek transkript.

Ek kaynaklar

İletişim kutusunun nasıl uygulandığı hakkında giriş için bkz . Tek bir şelale iletişim kutusu kullanan sıralı konuşma akışını uygulama ve kullanıcıya bir dizi soru sormak için birkaç istem.

İletişim Kutuları kitaplığı, istemler için temel doğrulamayı içerir. Özel doğrulama da ekleyebilirsiniz. Daha fazla bilgi için bkz . İletişim kutusu istemini kullanarak kullanıcı girişi toplama.

İletişim kutusu kodunuzu basitleştirmek ve birden çok botu yeniden kullanmak için, iletişim kutusu kümesinin bölümlerini ayrı bir sınıf olarak tanımlayabilirsiniz. Daha fazla bilgi için bkz . İletişim kutularını yeniden kullanma.

Sonraki adımlar

İletişim kutularını yeniden kullan