Update code samples to include prompt option validations (#64)

Author: JonathanFingold

SDKV4-Samples/dotnet_core/DialogPromptBot/DialogPromptBot.cs

@@ -2,7 +2,6 @@
 // Licensed under the MIT License.
 
 using System;
-using System.Collections;
 using System.Collections.Generic;
 using System.Linq;
 using System.Threading;
@@ -17,31 +16,36 @@ namespace Microsoft.BotBuilderSamples
 {
     /// <summary>
     /// Represents a bot that processes incoming activities.
-    /// For each user interaction, an instance of this class is created and the OnTurnAsync method is called.
-    /// This is a Transient lifetime service.  Transient lifetime services are created
-    /// each time they're requested. For each Activity received, a new instance of this
-    /// class is created. Objects that are expensive to construct, or have a lifetime
-    /// beyond the single turn, should be carefully managed.
-    /// For example, the <see cref="MemoryStorage"/> object and associated
-    /// <see cref="IStatePropertyAccessor{T}"/> object are created with a singleton lifetime.
+    /// For each user interaction, an instance of this class is created and the OnTurnAsync method
+    /// is called. This is a Transient lifetime service.  Transient lifetime services are created
+    /// each time they're requested. For each Activity received, a new instance of this class is
+    /// created. Objects that are expensive to construct, or have a lifetime beyond the single
+    /// turn, should be carefully managed. For example, the <see cref="MemoryStorage"/> object and
+    /// associated <see cref="IStatePropertyAccessor{T}"/> object are created with a singleton lifetime.
     /// </summary>
     public class DialogPromptBot : IBot
     {
         // Define identifiers for our dialogs and prompts.
         private const string ReservationDialog = "reservationDialog";
-        private const string PartySizePrompt = "partyPrompt";
+        private const string SizeRangePrompt = "sizeRangePrompt";
         private const string LocationPrompt = "locationPrompt";
         private const string ReservationDatePrompt = "reservationDatePrompt";
 
+        // Define keys for tracked values within the dialog.
+        private const string LocationKey = "location";
+        private const string PartySizeKey = "partySize";
+
         private readonly DialogSet _dialogSet;
         private readonly DialogPromptBotAccessors _accessors;
         private readonly ILogger _logger;
 
         /// <summary>
         /// Initializes a new instance of the <see cref="DialogPromptBot"/> class.
         /// </summary>
-        /// <param name="accessors">A class containing <see cref="IStatePropertyAccessor{T}"/> used to manage state.</param>
-        /// <param name="loggerFactory">A <see cref="ILoggerFactory"/> that is hooked to the Azure App Service provider.</param>
+        /// <param name="accessors">A class containing <see cref="IStatePropertyAccessor{T}"/> used
+        /// to manage state.</param>
+        /// <param name="loggerFactory">A <see cref="ILoggerFactory"/> that is hooked to the Azure
+        /// App Service provider.</param>
         public DialogPromptBot(DialogPromptBotAccessors accessors, ILoggerFactory loggerFactory)
         {
             if (loggerFactory == null)
@@ -55,18 +59,20 @@ public DialogPromptBot(DialogPromptBotAccessors accessors, ILoggerFactory logger
 
             // Create the dialog set and add the prompts, including custom validation.
             _dialogSet = new DialogSet(_accessors.DialogStateAccessor);
-            _dialogSet.Add(new NumberPrompt<int>(PartySizePrompt, PartySizeValidatorAsync));
+
+            _dialogSet.Add(new NumberPrompt<int>(SizeRangePrompt, RangeValidatorAsync));
             _dialogSet.Add(new ChoicePrompt(LocationPrompt));
             _dialogSet.Add(new DateTimePrompt(ReservationDatePrompt, DateValidatorAsync));
 
             // Define the steps of the waterfall dialog and add it to the set.
-            WaterfallStep[] steps = new WaterfallStep[]
+            var steps = new WaterfallStep[]
             {
                 PromptForPartySizeAsync,
                 PromptForLocationAsync,
                 PromptForReservationDateAsync,
                 AcknowledgeReservationAsync,
             };
+
             _dialogSet.Add(new WaterfallDialog(ReservationDialog, steps));
         }
 
@@ -77,25 +83,29 @@ public DialogPromptBot(DialogPromptBotAccessors accessors, ILoggerFactory logger
         /// </summary>
         /// <param name="turnContext">A <see cref="ITurnContext"/> containing all the data needed
         /// for processing this conversation turn. </param>
-        /// <param name="cancellationToken">(Optional) A <see cref="CancellationToken"/> that can be used by other objects
-        /// or threads to receive notice of cancellation.</param>
+        /// <param name="cancellationToken">(Optional) A <see cref="CancellationToken"/> that can
+        /// be used by other objects or threads to receive notice of cancellation.</param>
         /// <returns>A <see cref="Task"/> that represents the work queued to execute.</returns>
         /// <seealso cref="BotStateSet"/>
         /// <seealso cref="ConversationState"/>
         /// <seealso cref="IMiddleware"/>
-        public async Task OnTurnAsync(ITurnContext turnContext, CancellationToken cancellationToken = default(CancellationToken))
+        public async Task OnTurnAsync(
+            ITurnContext turnContext,
+            CancellationToken cancellationToken = default(CancellationToken))
         {
             switch (turnContext.Activity.Type)
             {
                 // On a message from the user:
                 case ActivityTypes.Message:
 
                     // Get the current reservation info from state.
-                    Reservation reservation = await _accessors.ReservationAccessor.GetAsync(
-                        turnContext, () => null, cancellationToken);
+                    var reservation = await _accessors.ReservationAccessor.GetAsync(
+                        turnContext,
+                        () => null,
+                        cancellationToken);
 
                     // Generate a dialog context for our dialog set.
-                    DialogContext dc = await _dialogSet.CreateContextAsync(turnContext, cancellationToken);
+                    var dc = await _dialogSet.CreateContextAsync(turnContext, cancellationToken);
 
                     if (dc.ActiveDialog is null)
                     {
@@ -116,7 +126,7 @@ await turnContext.SendActivityAsync(
                     else
                     {
                         // Continue the dialog.
-                        DialogTurnResult dialogTurnResult = await dc.ContinueDialogAsync(cancellationToken);
+                        var dialogTurnResult = await dc.ContinueDialogAsync(cancellationToken);
 
                         // If the dialog completed this turn, record the reservation info.
                         if (dialogTurnResult.Status is DialogTurnStatus.Complete)
@@ -129,13 +139,15 @@ await _accessors.ReservationAccessor.SetAsync(
 
                             // Send a confirmation message to the user.
                             await turnContext.SendActivityAsync(
-                                $"Your party of {reservation.Size} is confirmed for {reservation.Date}.",
+                                $"Your party of {reservation.Size} is confirmed for " +
+                                $"{reservation.Date} in {reservation.Location}.",
                                 cancellationToken: cancellationToken);
                         }
                     }
 
                     // Save the updated dialog state into the conversation state.
-                    await _accessors.ConversationState.SaveChangesAsync(turnContext, false, cancellationToken);
+                    await _accessors.ConversationState.SaveChangesAsync(
+                        turnContext, false, cancellationToken);
                     break;
             }
         }
@@ -152,23 +164,33 @@ private async Task<DialogTurnResult> PromptForPartySizeAsync(
         {
             // Prompt for the party size. The result of the prompt is returned to the next step of the waterfall.
             return await stepContext.PromptAsync(
-                PartySizePrompt,
+                SizeRangePrompt,
                 new PromptOptions
                 {
                     Prompt = MessageFactory.Text("How many people is the reservation for?"),
                     RetryPrompt = MessageFactory.Text("How large is your party?"),
+                    Validations = new Range { Min = 3, Max = 8 },
                 },
                 cancellationToken);
         }
 
-        private async Task<DialogTurnResult> PromptForLocationAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
+        /// <summary>Second step of the main dialog: prompt for location.</summary>
+        /// <param name="stepContext">The context for the waterfall step.</param>
+        /// <param name="cancellationToken">A cancellation token that can be used by other objects
+        /// or threads to receive notice of cancellation.</param>
+        /// <returns>A task that represents the work queued to execute.</returns>
+        /// <remarks>If the task is successful, the result contains information from this step.</remarks>
+        private async Task<DialogTurnResult> PromptForLocationAsync(
+            WaterfallStepContext stepContext,
+            CancellationToken cancellationToken)
         {
             // Record the party size information in the current dialog state.
-            int size = (int)stepContext.Result;
-            stepContext.Values["size"] = size;
+            var size = (int)stepContext.Result;
+            stepContext.Values[PartySizeKey] = size;
 
+            // Prompt for the location.
             return await stepContext.PromptAsync(
-                "locationPrompt",
+                LocationPrompt,
                 new PromptOptions
                 {
                     Prompt = MessageFactory.Text("Please choose a location."),
@@ -178,8 +200,7 @@ private async Task<DialogTurnResult> PromptForLocationAsync(WaterfallStepContext
                 cancellationToken);
         }
 
-        /// <summary>Second step of the main dialog: record the party size and prompt for the
-        /// reservation date.</summary>
+        /// <summary>Third step of the main dialog: prompt for the reservation date.</summary>
         /// <param name="stepContext">The context for the waterfall step.</param>
         /// <param name="cancellationToken">A cancellation token that can be used by other objects
         /// or threads to receive notice of cancellation.</param>
@@ -190,10 +211,10 @@ private async Task<DialogTurnResult> PromptForReservationDateAsync(
             CancellationToken cancellationToken = default(CancellationToken))
         {
             // Record the party size information in the current dialog state.
-            var location = stepContext.Result;
-            stepContext.Values["location"] = location;
+            var location = (stepContext.Result as FoundChoice).Value;
+            stepContext.Values[LocationKey] = location;
 
-            // Prompt for the party size. The result of the prompt is returned to the next step of the waterfall.
+            // Prompt for the reservation date.
             return await stepContext.PromptAsync(
                 ReservationDatePrompt,
                 new PromptOptions
@@ -204,7 +225,7 @@ private async Task<DialogTurnResult> PromptForReservationDateAsync(
                 cancellationToken);
         }
 
-        /// <summary>Third step of the main dialog: return the collected party size and reservation date.</summary>
+        /// <summary>Last step of the main dialog: return the collected reservation information.</summary>
         /// <param name="stepContext">The context for the waterfall step.</param>
         /// <param name="cancellationToken">A cancellation token that can be used by other objects
         /// or threads to receive notice of cancellation.</param>
@@ -215,19 +236,20 @@ private async Task<DialogTurnResult> AcknowledgeReservationAsync(
             CancellationToken cancellationToken = default(CancellationToken))
         {
             // Retrieve the reservation date.
-            DateTimeResolution resolution = (stepContext.Result as IList<DateTimeResolution>).First();
-            string time = resolution.Value ?? resolution.Start;
+            var resolution = (stepContext.Result as IList<DateTimeResolution>).First();
+            var time = resolution.Value ?? resolution.Start;
 
             // Send an acknowledgement to the user.
             await stepContext.Context.SendActivityAsync(
                 "Thank you. We will confirm your reservation shortly.",
                 cancellationToken: cancellationToken);
 
             // Return the collected information to the parent context.
-            Reservation reservation = new Reservation
+            var reservation = new Reservation
             {
                 Date = time,
-                Size = (int)stepContext.Values["size"],
+                Size = (int)stepContext.Values[PartySizeKey],
+                Location = (string)stepContext.Values[LocationKey],
             };
             return await stepContext.EndDialogAsync(reservation, cancellationToken);
         }
@@ -239,7 +261,7 @@ await stepContext.Context.SendActivityAsync(
         /// <returns>A task that represents the work queued to execute.</returns>
         /// <remarks>Reservations can be made for groups of 6 to 20 people.
         /// If the task is successful, the result indicates whether the input was valid.</remarks>
-        private async Task<bool> PartySizeValidatorAsync(
+        private async Task<bool> RangeValidatorAsync(
             PromptValidatorContext<int> promptContext,
             CancellationToken cancellationToken)
         {
@@ -253,11 +275,17 @@ await promptContext.Context.SendActivityAsync(
             }
 
             // Check whether the party size is appropriate.
-            int size = promptContext.Recognized.Value;
-            if (size < 6 || size > 20)
+            var size = promptContext.Recognized.Value;
+            var validRange = promptContext.Options.Validations as Range;
+            if (size < validRange.Min || size > validRange.Max)
             {
-                await promptContext.Context.SendActivityAsync(
-                    "Sorry, we can only take reservations for parties of 6 to 20.",
+                await promptContext.Context.SendActivitiesAsync(
+                    new Activity[]
+                    {
+                        MessageFactory.Text($"Sorry, we can only take reservations for parties " +
+                            $"of {validRange.Min} to {validRange.Max}."),
+                        promptContext.Options.RetryPrompt,
+                    },
                     cancellationToken: cancellationToken);
                 return false;
             }
@@ -287,9 +315,9 @@ await promptContext.Context.SendActivityAsync(
 
             // Check whether any of the recognized date-times are appropriate,
             // and if so, return the first appropriate date-time.
-            DateTime earliest = DateTime.Now.AddHours(1.0);
-            DateTimeResolution value = promptContext.Recognized.Value.FirstOrDefault(v =>
-                DateTime.TryParse(v.Value ?? v.Start, out DateTime time) && DateTime.Compare(earliest, time) <= 0);
+            var earliest = DateTime.Now.AddHours(1.0);
+            var value = promptContext.Recognized.Value.FirstOrDefault(v =>
+                DateTime.TryParse(v.Value ?? v.Start, out var time) && DateTime.Compare(earliest, time) <= 0);
             if (value != null)
             {
                 promptContext.Recognized.Value.Clear();
@@ -303,10 +331,21 @@ await promptContext.Context.SendActivityAsync(
             return false;
         }
 
+        /// <summary>Describes an acceptable range of values.</summary>
+        public class Range
+        {
+            public int Min { get; set; }
+
+            public int Max { get; set; }
+        }
+
+        /// <summary>Holds a user's reservation information.</summary>
         public class Reservation
         {
             public int Size { get; set; }
 
+            public string Location { get; set; }
+
             public string Date { get; set; }
         }
     }

SDKV4-Samples/dotnet_core/DialogPromptBot/DialogPromptBot.csproj

@@ -19,12 +19,12 @@
     <PackageReference Include="Microsoft.AspNetCore" Version="2.1.3" />
     <PackageReference Include="Microsoft.AspNetCore.All" Version="2.0.7" />
     <PackageReference Include="AsyncUsageAnalyzers" Version="1.0.0-alpha003" PrivateAssets="all" />
-    <PackageReference Include="Microsoft.Bot.Builder" Version="4.1.1" />
-    <PackageReference Include="Microsoft.Bot.Builder.Dialogs" Version="4.1.1" />
-    <PackageReference Include="Microsoft.Bot.Builder.Integration.AspNet.Core" Version="4.1.1" />
-    <PackageReference Include="Microsoft.Bot.Configuration" Version="4.1.1" />
-    <PackageReference Include="Microsoft.Bot.Connector" Version="4.1.1" />
-    <PackageReference Include="Microsoft.Bot.Schema" Version="4.1.1" />
+    <PackageReference Include="Microsoft.Bot.Builder" Version="4.2.2" />
+    <PackageReference Include="Microsoft.Bot.Builder.Dialogs" Version="4.2.2" />
+    <PackageReference Include="Microsoft.Bot.Builder.Integration.AspNet.Core" Version="4.2.2" />
+    <PackageReference Include="Microsoft.Bot.Configuration" Version="4.2.2" />
+    <PackageReference Include="Microsoft.Bot.Connector" Version="4.2.2" />
+    <PackageReference Include="Microsoft.Bot.Schema" Version="4.2.2" />
     <PackageReference Include="Microsoft.Extensions.Logging.AzureAppServices" Version="2.1.1" />
     <PackageReference Include="StyleCop.Analyzers" Version="1.1.0-beta008" PrivateAssets="all" />
   </ItemGroup>