Merge branch 'develop'

Author: msft-shahins

CSharp/Documentation/Forms.cs

@@ -350,7 +350,7 @@
     /// 
     /// Attribute | Purpose
     /// ----------| -------
-    /// [Describe] | Change how a field or a value is shown in text.
+    /// [Describe] | Change how a field or a value is shown in a template as a choice or in a card.
     /// [Numeric] | Provide limits on the values accepted in a numeric field.
     /// [Optional]| Mark a field as optional which means that one choice is not to supply a value.
     /// [Pattern] | Define a regular expression to validate a string field.
@@ -550,9 +550,12 @@
     /// 
     /// \subsection logic Adding Business Logic
     /// Sometimes there are complex interdependencies between fields or you need to 
-    /// add logic to setting or getting a value. Here we want to add support
-    /// for including all toppings except some of them. To do this, we add a validation function which complements
-    /// the list if the Everything enum value is included:
+    /// add logic to setting or getting a value.  A validation function allows manipulating the state and also returns a ValidateResult which can:
+    /// * Return a feedback string describing why a value is not valid.
+    /// * Return a transformed value.
+    /// * Return a set of choices for clarifying a value.  
+    /// 
+    /// Here we want to add support for including all toppings except some of them.  To do this we complement the list if the Everything enum value is included:
     /// \dontinclude AnnotatedSandwichBot/AnnotatedSandwich.cs
     /// \skip nameof(Toppings)
     /// \until Message
@@ -793,13 +796,14 @@
     /// 
     /// %Extensions that are found in a property description as peers to the "type" property of a JSON Schema.
     /// * `DateTime:bool` -- Marks a field as being a DateTime field.
-    /// * `Describe:string` -- Description of a field as described in <see cref="DescribeAttribute"/>.
+    /// * `Describe:string|object` -- Description of a field as described in <see cref="DescribeAttribute"/>.
     /// * `Terms:[string,...]` -- Regular expressions for matching a field value as described in <see cref="TermsAttribute"/>.
     /// * `MaxPhrase:int` -- This will run your terms through <see cref="Language.GenerateTerms(string, int)"/> to expand them.
-    /// * `Values:{ string: {Describe:string, Terms:[string, ...], MaxPhrase}, ...}` -- The string must be found in the types "enum" and this allows you to override the automatically generated descriptions and terms. If MaxPhrase is specified the terms are passed through <see cref="Language.GenerateTerms(string, int)"/>.
+    /// * `Values:{ string: {Describe:string|object, Terms:[string, ...], MaxPhrase}, ...}` -- The string must be found in the types "enum" and this allows you to override the automatically generated descriptions and terms. If MaxPhrase is specified the terms are passed through <see cref="Language.GenerateTerms(string, int)"/>.
     /// * `Active:script` -- C# script with arguments (JObject state)->bool to test to see if field/message/confirm is active.
     /// * `Validate:script` -- C# script with arguments (JObject state, object value)->ValidateResult for validating a field value.
     /// * `Define:script` -- C# script with arguments (JObject state, Field&lt;JObject&gt; field) for dynamically defining a field.  
+    /// * `Next:script` -- C# script with arguments (object value, JObject state) for determining the next step after filling in a field.
     /// * `Before:[confirm|message, ...]` -- Messages or confirmations before the containing field.
     /// * `After:[confirm|message, ...]` -- Messages or confirmations after the containing field.
     /// * `{Confirm:script|[string, ...], ...templateArgs}` -- With Before/After define a confirmation through either C# script with argument (JObject state) or through a set of patterns that will be randomly selected with optional template arguments.

CSharp/Documentation/Routing.cs

@@ -108,7 +108,7 @@ When your %bot receives a message Activity it will want to respond.
 newMessage.Conversation = conversation;
 newMessage.Recipient = userAccount;
 newMessage.Text = "Yo yo yo!";
-await connector.Conversations.SendToConversation((Activity)newMessage); 
+await connector.Conversations.SendToConversationAsync((Activity)newMessage); 
 ~~~
 
 \subsection multiplereplies Multiple replies
@@ -145,8 +145,7 @@ To initialize a **ConnectorClient** you use ServiceUrl persisted from previous m
 message.Conversation = new ConversationAccount(id: conversationId.Id);
 message.Text = "Hello";
 message.Locale = "en-Us";
-
-await connector.Conversations.SendToConversation((Activity)message); 
+await connector.Conversations.SendToConversationAsync((Activity)message); 
 ~~~
 
 
@@ -171,8 +170,8 @@ To initialize a **ConnectorClient** you use ServiceUrl persisted from previous m
 message.ChannelId = incomingMessage.ChannelId;
 message.Text = "Hey, what's up everyone?";
 message.Locale = "en-Us";
-await connector.Conversations.SendToConversation((Activity)message); 
+await connector.Conversations.SendToConversationAsync((Activity)message); 
 ~~~
 
     **/
-}
+}

CSharp/Library/Dialogs/BotToUser.cs

@@ -113,24 +113,28 @@ private static string ButtonsToText(IList<Attachment> attachments)
             var builder = new StringBuilder();
             if (cardAttachments != null && cardAttachments.Any())
             {
-                builder.AppendLine(); 
+                builder.AppendLine();
                 foreach (var attachment in cardAttachments)
                 {
                     string type = attachment.ContentType.Split('.').Last();
-                    if (type == "hero"  || type == "thumbnail")
+                    if (type == "hero" || type == "thumbnail")
                     {
                         var card = (HeroCard)attachment.Content;
+                        if (!string.IsNullOrEmpty(card.Title))
+                        {
+                            builder.AppendLine(card.Title);
+                        }
+                        if (!string.IsNullOrEmpty(card.Subtitle))
+                        {
+                            builder.AppendLine(card.Subtitle);
+                        }
                         if (!string.IsNullOrEmpty(card.Text))
                         {
                             builder.AppendLine(card.Text);
                         }
-                        foreach(var button in card.Buttons)
+                        if (card.Buttons != null)
                         {
-                            if (!string.IsNullOrEmpty(button.Value))
-                            {
-                                builder.AppendLine($"{ button.Value}. { button.Title}");
-                            }
-                            else
+                            foreach (var button in card.Buttons)
                             {
                                 builder.AppendLine($"* {button.Title}");
                             }

CSharp/Library/Dialogs/DialogModule.cs

@@ -81,6 +81,13 @@ protected override void Load(ContainerBuilder builder)
                 .AsSelf()
                 .InstancePerMatchingLifetimeScope(LifetimeScopeTag);
 
+            // make the resumption cookie available for the lifetime scope
+
+            builder
+                .RegisterType<ResumptionCookie>()
+                .AsSelf()
+                .InstancePerMatchingLifetimeScope(LifetimeScopeTag);
+
             // components not marked as [Serializable]
             builder
                 .RegisterType<MicrosoftAppCredentials>()
@@ -92,6 +99,11 @@ protected override void Load(ContainerBuilder builder)
                 .As<IBotIdResolver>()
                 .SingleInstance();
 
+            builder
+                .RegisterType<LocalMutualExclusion<ResumptionCookie>>()
+                .As<IScope<ResumptionCookie>>()
+                .SingleInstance();
+
             builder
                 .Register(c => new ConnectorClientFactory(c.Resolve<IMessageActivity>(), c.Resolve<MicrosoftAppCredentials>()))
                 .As<IConnectorClientFactory>()
@@ -174,6 +186,7 @@ protected override void Load(ContainerBuilder builder)
                     };
 
                     IPostToBot outer = new PersistentDialogTask(makeInner, cc.Resolve<IMessageActivity>(), cc.Resolve<IConnectorClient>(), cc.Resolve<IBotToUser>(), cc.Resolve<IBotData>());
+                    outer = new SerializingDialogTask(outer, cc.Resolve<ResumptionCookie>(), c.Resolve<IScope<ResumptionCookie>>());
                     outer = new PostUnhandledExceptionToUserTask(outer, cc.Resolve<IBotToUser>(), cc.Resolve<ResourceManager>(), cc.Resolve<TraceListener>());
                     return outer;
                 })

CSharp/Library/Dialogs/DialogTask.cs

@@ -212,7 +212,8 @@ async Task IDialogStack.Forward<R, T>(IDialog<R> child, ResumeAfter<R> resume, T
             IDialogStack stack = this;
             stack.Call(child, resume);
             await stack.PollAsync(token);
-            await (this as IPostToBot).PostAsync(item, token);
+            IPostToBot postToBot = this;
+            await postToBot.PostAsync(item, token);
         }
 
         void IDialogStack.Done<R>(R value)
@@ -231,27 +232,14 @@ void IDialogStack.Wait<R>(ResumeAfter<R> resume)
         }
 
         async Task IDialogStack.PollAsync(CancellationToken token)
-        {
-            await this.fiber.PollAsync(this);
-
-            // this line will throw an error if the code does not schedule the next callback
-            // to wait for the next message sent from the user to the bot.
-            this.fiber.Wait.ValidateNeed(Need.Wait);
-        }
-
-        void IDialogStack.Reset()
-        {
-            this.store.Reset();
-            this.store.Flush();
-            this.fiber.Reset();
-        }
-
-        async Task IPostToBot.PostAsync<T>(T item, CancellationToken token)
         {
             try
             {
-                this.fiber.Post(item);
                 await this.fiber.PollAsync(this);
+
+                // this line will throw an error if the code does not schedule the next callback
+                // to wait for the next message sent from the user to the bot.
+                this.fiber.Wait.ValidateNeed(Need.Wait);
             }
             catch
             {
@@ -261,9 +249,23 @@ async Task IPostToBot.PostAsync<T>(T item, CancellationToken token)
             finally
             {
                 this.store.Save(this.fiber);
-                this.store.Flush(); 
+                this.store.Flush();
             }
         }
+
+        void IDialogStack.Reset()
+        {
+            this.store.Reset();
+            this.store.Flush();
+            this.fiber.Reset();
+        }
+
+        async Task IPostToBot.PostAsync<T>(T item, CancellationToken token)
+        {
+            this.fiber.Post(item);
+            IDialogStack stack = this;
+            await stack.PollAsync(token);
+        }
     }
 
     public sealed class ReactiveDialogTask : IPostToBot
@@ -415,6 +417,28 @@ async Task IPostToBot.PostAsync<T>(T item, CancellationToken token)
         }
     }
 
+    public sealed class SerializingDialogTask : IPostToBot
+    {
+        private readonly IPostToBot inner;
+        private readonly ResumptionCookie cookie;
+        private readonly IScope<ResumptionCookie> scopeForCookie;
+
+        public SerializingDialogTask(IPostToBot inner, ResumptionCookie cookie, IScope<ResumptionCookie> scopeForCookie)
+        {
+            SetField.NotNull(out this.inner, nameof(inner), inner);
+            SetField.NotNull(out this.cookie, nameof(cookie), cookie);
+            SetField.NotNull(out this.scopeForCookie, nameof(scopeForCookie), scopeForCookie);
+        }
+
+        async Task IPostToBot.PostAsync<T>(T item, CancellationToken token)
+        {
+            using (await this.scopeForCookie.WithScopeAsync(this.cookie, token))
+            {
+                await this.inner.PostAsync(item, token);
+            }
+        }
+    }
+
     public sealed class PostUnhandledExceptionToUserTask : IPostToBot
     {
         private readonly IPostToBot inner;

CSharp/Library/Dialogs/LuisDialog.cs

@@ -75,6 +75,15 @@ public LuisIntentAttribute(string intentName)
     /// <returns>A task representing the completion of the intent processing.</returns>
     public delegate Task IntentHandler(IDialogContext context, LuisResult luisResult);
 
+    /// <summary>
+    /// The handler for a LUIS intent.
+    /// </summary>
+    /// <param name="context">The dialog context.</param>
+    /// <param name="message">The dialog message.</param>
+    /// <param name="luisResult">The LUIS result.</param>
+    /// <returns>A task representing the completion of the intent processing.</returns>
+    public delegate Task IntentActivityHandler(IDialogContext context, IAwaitable<IMessageActivity> message, LuisResult luisResult);
+
     /// <summary>
     /// An exception for invalid intent handlers.
     /// </summary>
@@ -121,7 +130,7 @@ public class LuisDialog<R> : IDialog<R>
 
         /// <summary>   Mapping from intent string to the appropriate handler. </summary>
         [NonSerialized]
-        protected Dictionary<string, IntentHandler> handlerByIntent;
+        protected Dictionary<string, IntentActivityHandler> handlerByIntent;
 
         public ILuisService[] MakeServicesFromAttributes()
         {
@@ -178,23 +187,23 @@ protected virtual async Task MessageReceived(IDialogContext context, IAwaitable<
         {
             if (this.handlerByIntent == null)
             {
-                this.handlerByIntent = new Dictionary<string, IntentHandler>(GetHandlersByIntent());
+                this.handlerByIntent = new Dictionary<string, IntentActivityHandler>(GetHandlersByIntent());
             }
 
             var message = await item;
             var messageText = await GetLuisQueryTextAsync(context, message);
             var tasks = this.services.Select(s => s.QueryAsync(messageText)).ToArray();
             var winner = this.BestResultFrom(await Task.WhenAll(tasks));
 
-            IntentHandler handler = null;
+            IntentActivityHandler handler = null;
             if (winner == null || !this.handlerByIntent.TryGetValue(winner.BestIntent.Intent, out handler))
             {
                 handler = this.handlerByIntent[string.Empty];
             }
 
             if (handler != null)
             {
-                await handler(context, winner?.Result);
+                await handler(context, item, winner?.Result);
             }
             else
             {
@@ -208,7 +217,7 @@ protected virtual Task<string> GetLuisQueryTextAsync(IDialogContext context, IMe
             return Task.FromResult(message.Text);
         }
 
-        protected virtual IDictionary<string, IntentHandler> GetHandlersByIntent()
+        protected virtual IDictionary<string, IntentActivityHandler> GetHandlersByIntent()
         {
             return LuisDialog.EnumerateHandlers(this).ToDictionary(kv => kv.Key, kv => kv.Value);
         }
@@ -221,17 +230,18 @@ internal static class LuisDialog
         /// </summary>
         /// <param name="dialog">The dialog.</param>
         /// <returns>An enumeration of handlers.</returns>
-        public static IEnumerable<KeyValuePair<string, IntentHandler>> EnumerateHandlers(object dialog)
+        public static IEnumerable<KeyValuePair<string, IntentActivityHandler>> EnumerateHandlers(object dialog)
         {
             var type = dialog.GetType();
             var methods = type.GetMethods(BindingFlags.Instance | BindingFlags.NonPublic | BindingFlags.Public);
             foreach (var method in methods)
             {
                 var intents = method.GetCustomAttributes<LuisIntentAttribute>(inherit: true).ToArray();
-                Delegate created = null;
+                IntentActivityHandler intentHandler = null;
+
                 try
                 {
-                    created = Delegate.CreateDelegate(typeof(IntentHandler), dialog, method, throwOnBindFailure: false);
+                    intentHandler = (IntentActivityHandler)Delegate.CreateDelegate(typeof(IntentActivityHandler), dialog, method, throwOnBindFailure: false);
                 }
                 catch (ArgumentException)
                 {
@@ -240,15 +250,35 @@ public static IEnumerable<KeyValuePair<string, IntentHandler>> EnumerateHandlers
                     // https://github.com/Microsoft/BotBuilder/issues/435
                 }
 
-                var intentHandler = (IntentHandler)created;
+                // fall back for compatibility
+                if (intentHandler == null)
+                {
+                    try
+                    {
+                        var handler = (IntentHandler)Delegate.CreateDelegate(typeof(IntentHandler), dialog, method, throwOnBindFailure: false);
+
+                        if (handler != null)
+                        {
+                            // thunk from new to old delegate type
+                            intentHandler = (context, message, result) => handler(context, result);
+                        }
+                    }
+                    catch (ArgumentException)
+                    {
+                        // "Cannot bind to the target method because its signature or security transparency is not compatible with that of the delegate type."
+                        // https://github.com/Microsoft/BotBuilder/issues/634
+                        // https://github.com/Microsoft/BotBuilder/issues/435
+                    }
+                }
+
                 if (intentHandler != null)
                 {
                     var intentNames = intents.Select(i => i.IntentName).DefaultIfEmpty(method.Name);
 
                     foreach (var intentName in intentNames)
                     {
                         var key = string.IsNullOrWhiteSpace(intentName) ? string.Empty : intentName;
-                        yield return new KeyValuePair<string, IntentHandler>(intentName, intentHandler);
+                        yield return new KeyValuePair<string, IntentActivityHandler>(intentName, intentHandler);
                     }
                 }
                 else