適應性對話方塊中的輸入-參考指南

適用于: SDK v4

Bot Framework SDK 會定義適用於收集及驗證使用者輸入的各種輸入對話。

輸入類型 輸入類別 描述 傳回值
基底類別 InputDialog 這是所有輸入類別衍生自的基底類別。 其會定義所有共用屬性。 物件。
Text TextInput 用來要求您的使用者提供 單字句子 字串。
Number NumberInput 用來向使用者要求 數字 數值。
確認 ConfirmInput 用來向使用者要求 確認 布林值。
選擇題 ChoiceInput 用來從一 組選項 要求選擇。 選取項目的值或索引。
檔案或附件 AttachmentInput 用來要求/讓使用者 上傳檔案 附件物件的集合。
日期或時間 DateTimeInput 用來向使用者要求 日期和/或時間 日期時間物件的集合。
OAuth 登入 OAuthInput 用來讓使用者 登入安全網站 權杖回應。

InputDialog

由 Bot Framework SDK 所提供的輸入類別都來自基底「輸入對話」,其則衍生自 dialog 類別。 所有輸入對話都有這些通用屬性:

AllowInterruptions

布林運算式。 true 來讓父對話中斷輸入對話,反之則為 false

如需中斷的詳細資訊,請參閱在 適應性對話方塊中處理中斷的概念文章。

注意

輸入父對話也可以中斷。 這表示當 AllowInterruptionstrue 時,輸入父自適性對話中的辨識器將會執行,且系統會評估其觸發程序。

AlwaysPrompt

布林運算式。 如果是 true,則一律會提示輸入;如果是 false,則只會在繫結屬性為 Null 或空白時才會提示。

DefaultValue

代表輸入對話之預設結果的自適性運算式。 如果使用者輸入在經過回合計數上限所設定的回合數之後仍然失敗,輸入對話便會結束,並將預設值設定為此屬性。

DefaultValue = "9"

DefaultValueResponse

在使用者輸入經過 MaxTurnCount 所設定的回合數皆無法完成其 Validations,且已指定 DefaultValue 的情況下要傳送的回應。

DefaultValueResponse = new ActivityTemplate("Sorry, we have reach the maximum number of attempts of '${%MaxTurnCount}' to get your input, so for now, we will go with a default value of: '${%DefaultValue}'")

InvalidPrompt

在辨識到使用者輸入但驗證失敗時,要用來重新提示輸入的活動範本。 (如果輸入在經過回合計數上限所設定的回合數之後仍然失敗,則會使用預設值並傳送預設值回應。)

注意

InvalidPrompt 屬性只能搭配 Validations 屬性使用。

InvalidPrompt = new ActivityTemplate("Sorry, {this.value} does not work. Please enter a number between one and ten (1-10).")

MaxTurnCount

整數運算式。 系統要求輸入的次數上限。 如果超過此限制,便會使用預設值並傳送預設值回應

MaxTurnCount = 2

Prompt

用來於一開始提示使用者輸入的活動範本。

Prompt = new ActivityTemplate("Hi, What is your name?")

屬性

要繫結輸入對話之目標屬性的記憶體路徑,或是評估為記憶體路徑的運算式。 記憶體路徑將會用來取得輸入對話的初始值。 其也會用來儲存此對話的結果。 PromptValue 屬性都會通過辨識及驗證步驟,因此無效的初始值將會導致出現提示。

使用此屬性來定義輸入對話所繫結的屬性。 例如:

Property = "user.name"

UnrecognizedPrompt

在無法辨識使用者輸入時,要用來重新提示輸入的活動範本。 (如果輸入在經過回合計數上限所設定的回合數之後仍然失敗,則會使用預設值並傳送預設值回應。)

UnrecognizedPrompt = new ActivityTemplate("Sorry, '{turn.activity.text}' did not include a valid number")

驗證

布林運算式清單。 如果這些運算式有任何一個評估為 false,則已辨識的輸入將會無效。 您可以使用 this.value 來檢查驗證運算式中的使用者輸入。 驗證是使用自適性運算式來表示的

字串運算式。 要在每個回合從中取得輸入之屬性的記憶體路徑。 如果對話的 Property 評估為 Null 或空白,此屬性將會作為輸入對話的初始值使用。 如果對話的 PropertyValue 屬性都評估為 Null 或空白,則對話將會提示輸入。

關於 Value 屬性要牢記在心的事項:

  • Value 屬性是自適性運算式
  • 如果運算式傳回 Null,輸入對話可能會嘗試直接從輸入提取資料。
  • 如果運算式是值,其將會作為輸入使用。
  • Value 屬性可讓您定義資料 (例如辨識器結果) 繫結到輸入對話的方式。

範例:

  • 若要將輸入繫結到在輸入中辨識的任何 age 實體:"=@age"
  • 若要使用 @age 或 @number 作為輸入:"=coalesce(@age, @number)"

提示

您可以在下方 NumberInput 小節的程式碼範例中看見這些 InputDialog 屬性的使用範例。

TextInput

當您想要以逐字方式接受使用者輸入,以作為您的 Bot 嘗試收集之特定資訊的值時,請使用「文字輸入」。 範例包括「使用者的姓名」與「電子郵件的主旨」。

TextInput 動作會繼承在 InputDialog 中定義的所有屬性,而且會定義一個額外的屬性:

  • OutputFormat:您可以使用自適性運算式來修改字串,例如,在下面的程式碼範例中,OutputFormat 運算式會將使用者姓名之每個單字的第一個字母變成大寫。

TextInput 範例

// Create root dialog as an adaptive dialog.
var getUserNameDialog = new AdaptiveDialog("GetUserNameDialog");

// Add an intent trigger.
getUserNameDialog.Triggers.Add(new OnIntent()
{
    Intent = "GetName",
    Actions = new List<Dialog>()
    {
        // Add TextInput step. This step will capture user's input and use it to populate the 'user.name' property.
        new TextInput()
        {
            Property = "user.fullName",
            Prompt = new ActivityTemplate("Please enter your full name.")
            OutputFormat = "join(foreach(split(this.value, ' '), item, concat(toUpper(substring(item, 0, 1)), substring(item, 1))), ' ')"
        }
    }
});

NumberInput

向使用者要求數字。

NumberInput 動作會繼承在 InputDialog 中定義的所有屬性,並會定義這兩個額外的屬性:

  1. DefaultLocale:設定輸入處理的預設地區設定;除非呼叫者另外傳遞地區設定,否則將會使用此設定。 支援的地區設定包括西班牙文、荷蘭文、英文、法文、德文、日文、葡萄牙文、中文。
  2. OutputFormat:您可以使用自適性運算式來採取動作以透過某種方式操作數字。 例如,您可以撰寫運算式來將以華氏輸入的溫度轉換成對應的攝氏值、執行如將稅金與運費加入所輸入值的數學計算,或是單純地執行類型轉換來將值指定為浮點數或整數 (如下面的範例程式碼所示)。

NumberInput 範例

var rootDialog = new AdaptiveDialog(nameof(AdaptiveDialog))
{
    Generator = new TemplateEngineLanguageGenerator(),
    Triggers = new List<OnCondition> ()
    {
        new OnUnknownIntent()
        {
            Actions = new List<Dialog>()
            {
                new NumberInput() {
                    Property = "user.favoriteNumber",
                    Prompt = new ActivityTemplate("Give me your favorite number (1-10)"),
                    // You can refer to incoming user message via turn.activity.text
                    UnrecognizedPrompt = new ActivityTemplate("Sorry, '{turn.activity.text}' did not include a valid number"),
                    // You can provide a list of validation expressions. Use turn.value to refer to any value extracted by the recognizer.
                    Validations = new List<BoolExpression> () {
                        "int(this.value) >= 1",
                        "int(this.value) <= 10"
                    },
                    InvalidPrompt = new ActivityTemplate("Sorry, {this.value} does not work. Can you give me a different number that is between 1-10?"),
                    MaxTurnCount = 2,
                    DefaultValue = "9",
                    DefaultValueResponse = new ActivityTemplate("Sorry, we have tried for '${%MaxTurnCount}' number of times and I'm still not getting it. For now, I'm setting '${%property}' to '${%DefaultValue}'"),
                    AllowInterruptions = "false",
                    AlwaysPrompt = true,
                    OutputFormat = "float(this.value)"
                },
                new SendActivity("Your favorite number is ${user.favoriteNumber}")
            }
        }
    }
};

ConfirmInput

確認輸入 很適合在您已向使用者詢問問題,並想要確認其答案的情況下使用。 和會讓您的 Bot 向使用者呈現選項清單的 選擇題 動作不同,確認提示會要求使用者作出二元 (是/否) 決定。

ConfirmInput 動作會繼承在 InputDialog 中定義的所有屬性,而且會定義這些額外的屬性:

  1. ChoiceOptions:用來格式化向使用者呈現之確認選項的呈現方式,此為會評估為 ChoiceSet 物件的自適性運算式。 此 ChoiceSet 物件只有在辨識 ConfirmInput 的初始嘗試失敗時,才會作為備份使用。 當 ConfirmInput 動作執行時,其會先嘗試將輸入評估為布林值。 如果該嘗試失敗,其會進行第二次嘗試,這次會使用選項辨識器來針對 ChoiceSet 進行評估。
  2. ConfirmChoices:將會向使用者呈現的選項,或是會評估為選擇的自適性運算式
  3. DefaultLocale:設定輸入處理的預設地區設定;除非呼叫者另外傳遞地區設定,否則將會使用此設定。 支援的地區設定包括西班牙文、荷蘭文、英文、法文、德文、日文、葡萄牙文、中文
  4. OutputFormat:ConfirmInput 動作的預設輸出格式是布林值。 您可以使用 OutputFormat 屬性來加以覆寫,此屬性為您可以用來視需要修改傳回結果的自適性運算式。 例如,您可以使用此屬性來使 ConfirmInput 動作傳回數字:OutputFormat = "if(this.value == true, 1, 0)"。 如果已設定此屬性,則運算式的輸出便會是由對話所傳回的值。
  5. Style:這會定義在確認使用者的輸入時,要向使用者呈現之清單的類型。 這會使用 ListStyle 列舉,其包含:
    1. None:不針對提示包含任何選項。
    2. Auto:為目前的通道自動選取適當的樣式。
    3. Inline:將選項以內嵌清單的形式新增到提示。
    4. List:將選項以編號清單的形式新增到提示。
    5. SuggestedAction:將選項以建議動作的形式新增到提示。
    6. HeroCard:將選項以具按鈕之 HeroCard 的形式新增到提示。

ConfirmInput 範例

// Create adaptive dialog.
var ConfirmationDialog = new AdaptiveDialog("ConfirmationDialog") {
    Triggers = new List<OnCondition>()
    {
        new OnUnknownIntent()
        {
            Actions = new List<Dialog>()
            {
                // Add confirmation input.
                new ConfirmInput()
                {
                    Property = "turn.contoso.travelBot.confirmOutcome",
                    // Since this prompt is built as a generic confirmation wrapper, the actual prompt
                    // text is read from a specific memory location. The caller of this dialog needs to
                    // set the prompt string to that location before calling the "ConfirmationDialog".
                    // All prompts support rich language generation based resolution for output generation.
                    // See https://docs.microsoft.com/azure/bot-service/file-format/bot-builder-lg-file-format to learn more about the LG
                    // template format used in the ActivityTemplate object.
                    Prompt = new ActivityTemplate("${turn.contoso.travelBot.confirmPromptMessage}")
                }
            }
        }
    }
};

ChoiceInput

選擇輸入 是以 選擇題 選取項目的形式向使用者呈現的一組選項,其可讓您向使用者呈現可供選擇的選項清單。

ChoiceInput 動作會繼承在 InputDialog 中定義的所有屬性,而且會定義這些額外的屬性:

  1. ChoiceOptions:此屬性是用來格式化向使用者呈現之確認選項的呈現方式。

  2. Choices:會評估為包含供使用者選擇的 [已排序] 選項清單之 ChoiceSet 的自適性運算式。

  3. DefaultLocale:設定輸入處理的預設地區設定;除非呼叫者另外傳遞地區設定,否則將會使用此設定。 支援的地區設定包括西班牙文、荷蘭文、英文、法文、德文、日文、葡萄牙文、中文

  4. OutputFormat:會評估為其中一個 ChoiceOutputFormat 列舉值的自適性運算式:

    switch (this.OutputFormat.GetValue(dc.State))
    {
        case ChoiceOutputFormat.Value:
        default:
            dc.State.SetValue(VALUE_PROPERTY, foundChoice.Value);
            break;
        case ChoiceOutputFormat.Index:
            dc.State.SetValue(VALUE_PROPERTY, foundChoice.Index);
            break;
    }
    
  5. Style:這會定義在確認使用者的輸入時,要向使用者呈現之清單的類型。 這會使用 ListStyle 列舉,其包含:

    1. None:不針對提示包含任何選項。
    2. Auto:為目前的通道自動選取適當的樣式。
    3. Inline:將選項以內嵌清單的形式新增到提示。
    4. List:將選項以編號清單的形式新增到提示。
    5. SuggestedAction:將選項以建議動作的形式新增到提示。
    6. HeroCard:將選項以具按鈕之 HeroCard 的形式新增到提示。
  6. RecognizerOptions:評估為 FindChoicesOptionsFindChoicesOptions 或運算式。 FindChoicesOptions 具有下列屬性:

    1. NoValue:布林值。 true 表示搜尋每個選項的 value 屬性;否則為 false。 預設值為 false
    2. NoAction:布林值。 true 表示搜尋每個選項之 action 屬性的標題;否則為 false。 預設值為 false
    3. RecognizeNumbers:布林值。 true 表示允許輸入使用數字辨識器針對輸入選項進行比對以作為後援;否則為 false。 預設值為 true
    4. RecognizeOrdinals:布林值。 true 表示允許輸入使用序數辨識器針對輸入選項進行比對以作為後援;否則為 false。 預設值為 true

ChoiceInput 範例

// Create an adaptive dialog.
var getUserFavoriteColor = new AdaptiveDialog("GetUserColorDialog");
getUserFavoriteColor.Triggers.Add(new OnIntent()
{
    Intent = "GetColor",
    Actions = new List<Dialog>()
    {
        // Add choice input.
        new ChoiceInput()
        {
            // Output from the user is automatically set to this property
            Property = "user.favColor",

            // List of possible styles supported by choice prompt.
            Style = Bot.Builder.Dialogs.Choices.ListStyle.Auto,
            Prompt = new ActivityTemplate("What is your favorite color?"),
            Choices = new ChoiceSet(new List<Choice>()
            {
                new Choice("Red"),
                new Choice("Blue"),
                new Choice("Green")
            })
        }
    }
});

DateTimeInput

要求日期/時間。

DateTimeInput 動作會繼承在 InputDialog 中定義的所有屬性,而且會定義這些額外的屬性:

  1. DefaultLocale:設定輸入處理的預設地區設定;除非呼叫者另外傳遞地區設定,否則將會使用此設定。 支援的地區設定包括西班牙文、荷蘭文、英文、法文、德文、日文、葡萄牙文、中文。
  2. OutputFormat:DateTimeInput 的預設輸出是 DateTimeResolutions 的陣列,此屬性可讓您定義自適性運算式。 無論其傳回的值為何,都會變成對話 property 屬性的最終值,無論其是否會評估為日期時間。

DateTimeInput 範例

var rootDialog = new AdaptiveDialog(nameof(AdaptiveDialog))
{
    Generator = new TemplateEngineLanguageGenerator(_templateEngine),
    Triggers = new List<OnCondition>()
    {
        new OnUnknownIntent()
        {
            Actions = new List<Dialog>()
            {
                new DateTimeInput()
                {
                    Property = "$userDate",
                    Prompt = new ActivityTemplate("Give me a date"),
                },
                new SendActivity("You gave me ${$userDate}")
            }
        }
    }
};

AttachmentInput

用來向使用者要求附件作為輸入。

AttachmentInput 動作會繼承在 InputDialog 中定義的所有屬性,而且會定義這個額外的屬性:

  • OutputFormat:評估為 AttachmentOutputFormatAttachmentOutputFormat 或運算式。 有效的 AttachmentOutputFormat 值為:
    1. All:以清單形式傳回所有附件。
    2. First:僅傳回第一個附件。

AttachmentInput 範例

var rootDialog = new AdaptiveDialog(nameof(AdaptiveDialog))
{
    Generator = new TemplateEngineLanguageGenerator(_templateEngine),
    Triggers = new List<OnCondition>()
    {
        new OnUnknownIntent()
        {
            Actions = new List<Dialog>()
            {
                new AttachmentInput()
                {
                    Property = "$userAttachmentCarImage",
                    Prompt = new ActivityTemplate("Please give me an image of your car. Drag drop the image to the chat canvas."),
                    OutputFormat = AttachmentOutputFormat.All
                },
                new SendActivity("You gave me ${$userAttachmentCarImage}")
            }
        }
    }
};

OAuthInput

用來要求使用者登入。

OAuthInput 動作會繼承在 InputDialog 中定義的所有屬性,並會定義這些額外的屬性:

  1. ConnectionName:在 Azure Bot Service 設定頁面針對 Bot 所設定之 OAuth 連線的名稱。
  2. Text:要顯示在登入卡片中的額外文字。
  3. Title:要顯示在登入卡片中的標題文字。
  4. Timeout:此為 OAuthInput 會等候使用者驗證完成的毫秒數。 預設值為 900,000 毫秒,即 15 分鐘。

OAuthInput 動作也會定義兩個新方法:

  1. GetUserTokenAsync:此方法會嘗試擷取使用者的權杖。
  2. SignOutUserAsync:此方法會將使用者登出。

動作會傳回 OAuthInput TokenResponse 物件,其中包含 ChannelIdConnectionName 、、的 TokenExpiration 。 在下列範例中,傳回值會放入 turn 記憶體範圍: turn.oauth 。 您可以從這個方法存取值,如下所示 LoginSteps()new SendActivity("Here is your token '${turn.oauth.token}'.")

OAuthInput 範例

在此範例中, TokenResponse 動作所傳回的物件 OAuthInput 會儲存在 MyOAuthInput 變數中。 這可讓您:

  • 在 bot 將需要權杖的任何回合上呼叫 OAuthInput 對話方塊。
  • 設定 OAuthInput,以將權杖回應寫入回合記憶體範圍。
  • 從回合記憶體範圍讀取權杖回應,並適當地使用它搭配所用的 API。 例如,您會將它新增為圖形 API 的持有人權杖。
public class RootDialog : AdaptiveDialog
{
    this.configuration = configuration;
    _templates = Templates.ParseFile(Path.Combine(".", "Dialogs", "RootDialog", "RootDialog.lg"));
    private OAuthInput MyOAuthInput { get; }

    public RootDialog(IConfiguration configuration) : base(nameof(RootDialog))
    {
        Recognizer = CreateLuisRecognizer(this.configuration),
        Generator = new TemplateEngineLanguageGenerator(_Templates);

        MyOAuthInput = new OAuthInput
        {
            // The name of the connection configured on Azure Bot Service for the OAuth connection.
            ConnectionName = configuration["ConnectionName"],

            // The title of the sign in card.
            Title = "Please log in",

            // The text displayed in sign in card.
            Text = "This will give you access!",

            // Title of the sign in card.
            InvalidPrompt = new ActivityTemplate("Login was not successful please try again."),

            // The number of milliseconds the prompt waits for the user to authenticate.
            // Tip: For an easy way to set the timeout to a specific number of minutes,
            // you can multiple the number of minutes by 60,000.  5 * 60000 = 5 minutes.
            Timeout = 5 * 60000,

            // The maximum number of times to ask the user for this value before the dialog gives up.
            MaxTurnCount = 3,

            // Property path to store the value (a TokenResponse object) that is returned by the OAuthInput action.
            // Since the token can be short-lived, you should call the OAuthInput on any turn in which your bot
            // needs to access associated resources on behalf of the user. If the token is still valid, the sign-in
            // card will not be displayed, if it is not still active the user will be prompted to sign in again.
            Property = "turn.oauth",
        };
        // Save the MyOAuthInput dialog instance in the adaptive dialog's dialog set.
        // This will enable consultation, logging telemetry data etc.
        Dialogs.Add(MyOAuthInput);

        // These steps are executed when this Adaptive Dialog begins
        Triggers = new List<OnCondition>
            {
                // Add a rule to welcome user
                new OnConversationUpdateActivity
                {
                    Actions = WelcomeUserSteps(),
                },

                // Respond to user on message activity
                new OnUnknownIntent
                {
                    Actions = LoginSteps(),
                },

                // Allow the use to sign out.
                new OnIntent("logout")
                {
                    Actions =
                    {
                        new CodeAction(async (dc, opt) =>
                        {
                            await MyOAuthInput.SignOutUserAsync(dc);
                            return new DialogTurnResult(DialogTurnStatus.Complete);
                        }),
                    }
                },
            };
    }

    private static List<Dialog> WelcomeUserSteps()
    {
        return new List<Dialog>
        {
            // Iterate through membersAdded list and greet user added to the conversation.
            new Foreach()
            {
                ItemsProperty = "turn.activity.membersAdded",
                Actions =
                {
                    // Note: Some channels send two conversation update events - one for the Bot added to the conversation and another for user.
                    // Filter cases where the bot itself is the recipient of the message. 
                    new IfCondition()
                    {
                        Condition = "$foreach.value.name != turn.activity.recipient.name",
                        Actions =
                        {
                            new SendActivity("Hello, I'm the multi-turn prompt bot. Please send a message to get started!")
                        }
                    }
                }
            }
        };
    }

    private List<Dialog> LoginSteps()
    {
        return new List<Dialog>
        {
            MyOAuthInput,
            new IfCondition
            {
                Condition = "turn.oauth.token && length(turn.oauth.token)",
                Actions = LoginSuccessSteps(),
                ElseActions =
                {
                    new SendActivity("Sorry, we were unable to log you in."),
                },
            },
            new EndDialog(),
        };
    }

    private List<Dialog> LoginSuccessSteps()
    {
        return new List<Dialog>
        {
            new SendActivity("You are now logged in."),
            new ConfirmInput
            {
                Prompt = new ActivityTemplate("Would you like to view your token?"),
                InvalidPrompt = new ActivityTemplate("Oops, I didn't understand. Would you like to view your token?"),
                MaxTurnCount = 3,
            },
            new IfCondition
            {
                Condition = "turn.lastResult == true",
                ElseActions =
                {
                    new SendActivity("Great. Type anything to continue."),
                },
                Actions =
                {
                    MyOAuthInput,
                    new SendActivity("Here is your token `${turn.oauth.token}`."),
                },
            },
        };
    }
}

下列連結會提供關於 Microsoft Bot Framework SDK 中驗證主題的一般資訊。 此資訊並非自適性對話特定,或是為其量身打造。