Merge branch 'develop'

Author: msft-shahins

.gitignore

@@ -117,7 +117,7 @@
     /// 
     /// \section IDialogContext
     /// All of the dialogs take in an IDialogContext, an interface that provides the services
-    /// needed to save state and comunicate.  
+    /// needed to save state and communicate.  
     /// The interface is composed of three interfaces: Internals.IBotData, Internals.IDialogStack, and Internals.IBotToUser.
     ///
     /// Internals.IBotData represents access to the per user, conversation, and user in conversation state maintained
@@ -136,6 +136,84 @@
     /// - Wait for a message from the user and suspend the conversation until the message arrives.
     /// The stack is usually automatically managed for you.
     /// 
+    /// \section Serialization
+    /// 
+    /// The dialog stack and the state of all active dialog are serialized to the per-user, per-conversation IBotDataBag.  This serialized blob is persisted through
+    /// the Messages sent to and received from the %Bot Connector.  Dialog classes must be marked with the serializable attribute so that Dialog object instances
+    /// can participate in the runtime serialization.  For example, all of the IDialog implementations in the builder library are marked as serializable.
+    /// When custom serialization was desired, there is an ISerialization implementation and serialization constructor as well.
+    /// 
+    /// The Chain methods provide a fluent interface to dialogs that is usable in linq query syntax.  The compiled form of linq query syntax often leverages anonymous methods.
+    /// If these anonymous methods do not reference the environment of local variables, then these anonymous methods have no state and are trivially serializable.  However, if
+    /// the anonymous method captures any local variable in the environment, the resulting closure object (generated by the compiler) is not marked as serializable.  The %Bot Builder
+    /// will detect this situation and throw a ClosureCaptureException to help diagnose the issue.
+    /// 
+    /// If you wish to try to leverage reflection to serialize classes that are not marked as serializable, the library has a reflection-based serialization surrogate that
+    /// can be registered with Autofac as follows:
+    /// 
+    /// \dontinclude Microsoft.Bot.Builder.Tests\ChainTests.cs
+    /// \skip includeReflection
+    /// \until }
+    /// 
+    /// \section Fluent Dialog Chains
+    /// 
+    /// Explicit management of the stack of active dialogs is possible through IDialogStack.Call<R> and IDialogStack.Done<R>, explicitly composing dialogs into a larger
+    /// conversation.  It is also possible to implicitly manage the stack of active dialogs through the fluent Chain methods.
+    ///
+    /// Here is an overview of the chain methods, followed by some examples.
+    /// 
+    /// Name                      | Type    | Notes
+    /// -----                     | ----    | -----
+    /// Chain.Select<T, R>        | Linq    | Supports "select" and "let" in linq query syntax.
+    /// Chain.SelectMany<T, C, R> | Linq    | Supports successive "from" in linq query syntax.
+    /// Chain.Where<T>            | Linq    | Supports "where" in linq query syntax.
+    /// Chain.From<T>             | Chains  | Instantiates a new instance of a dialog.
+    /// Chain.Return<T>           | Chains  | Return a constant value into the chain.
+    /// Chain.Do<T>               | Chains  | Allow for side-effects within the chain.
+    /// Chain.ContinueWith<T, R>  | Chains  | Simple chaining of dialogs.
+    /// Chain.Unwrap<T>           | Chains  | Unwrap a dialog nested in a dialog.
+    /// Chain.Loop<T>             | Branch  | Loop the entire chain of dialogs.
+    /// Chain.Switch<T, R>        | Branch  | Support branching into different dialog chains.
+    /// Chain.PostToUser<T>       | Message | Post a message to the user.
+    /// Chain.WaitToBot<T>        | Message | Wait for a message to the bot.
+    /// Chain.PostToChain<T>      | Message | Start a chain with a message from the user.
+    /// 
+    /// These Chain methods fall into a few buckets.
+    /// 
+    /// Linq query syntax starts off with the basic Chain.Select<T, R>:
+    /// 
+    /// \dontinclude Microsoft.Bot.Builder.Tests\ChainTests.cs
+    /// \skip MakeSelectQuery
+    /// \skip query
+    /// \until select
+    /// 
+    /// and linq query syntax is enhanced with support for Chain.SelectMany<T, C, R>:
+    /// 
+    /// \dontinclude Microsoft.Bot.Builder.Tests\ChainTests.cs
+    /// \skip LinqQuerySyntax_Without_Reflection_Surrogate
+    /// \skip query
+    /// \until select
+    /// 
+    /// Posting messages from the bot to the user and vice versa are supported by a Chain.PostToUser<T> and Chain.WaitToBot<T>:
+    /// 
+    /// \dontinclude Microsoft.Bot.Builder.Tests\ChainTests.cs
+    /// \skip PostToUser
+    /// \until PostToUser
+    /// 
+    /// Branching conversation dialog flow is supported by Chain.Switch<T, R>:
+    /// 
+    /// \dontinclude Microsoft.Bot.Builder.Tests\ChainTests.cs
+    /// \skip logic
+    /// \until );
+    /// 
+    /// If Chain.Switch<T, R> returns a nested IDialog<IDialog<T>>, then the inner IDialog<T> can be unwrapped with Chain.Unwrap<T>.  This allows for branching
+    /// in conversations to different paths of chained dialogs, possibly of unequal length.  Here is a more complete example of branching dialogs written
+    /// in the fluent chain style with implicit stack management:
+    /// 
+    /// \dontinclude Microsoft.Bot.Builder.Tests\ChainTests.cs
+    /// \skip joke
+    /// \until Loop
+    /// 
     /// \section Conclusion
     /// Through this description we have seen how you can easily create stateless bots that can reuse dialog building blocks
     /// ranging from simple prompts to advanced natural language.  As a next step, you should explore \ref forms which 

CSharp/Documentation/Dialogs.cs

@@ -13,9 +13,9 @@
     /// [EntityRecommendation.Entity]: @ref Microsoft.Bot.Builder.Luis.EntityRecommendation.Entity 
     /// [LuisDialog]: @ref Microsoft.Bot.Builder.Dialogs.LuisDialog 
     /// [AllowDefault]: @ref Advanced.TemplateBaseAttribute.AllowDefault 
-    /// [ChoiceCase]: @ref Advanvced.TemplateBaseAttribute.ChoiceCase
+    /// [ChoiceCase]: @ref Advanced.TemplateBaseAttribute.ChoiceCase
     /// [ChoiceLastSeparator]: @ref Advanced.TemplateBaseAttribute.ChoiceLastSeparator
-    /// [ChoiceSeparator]: @ref Advanced.TemplateBaseAttribtue.ChoiceSeparator
+    /// [ChoiceSeparator]: @ref Advanced.TemplateBaseAttribute.ChoiceSeparator
     /// [ChoiceFormat]: @ref Advanced.TemplateBaseAttribute.ChoiceFormat 
     /// [ChoiceParens]: @ref Advanced.TemplateBaseAttribute.ChoiceParens
     /// [ChoiceStyle]: @ref Advanced.TemplateBaseAttribute.ChoiceStyle 
@@ -112,7 +112,7 @@
     /// * Back: Go back to the previous question.
     /// * Help: Show the kinds of responses you can enter.
     /// * Quit: Quit the form without completing it.
-    /// * Reset: Start over filling in the form. (With defaults of your previous entries.)
+    /// * Reset: Start over filling in the form. (With defaults from your previous entries.)
     /// * Status: Show your progress in filling in the form so far.
     /// * You can switch to another field by entering its name. (Sandwich, Length, Bread, Cheese, Toppings, and Sauce).
     /// ~~~  
@@ -423,7 +423,7 @@
     /// * Back: Go back to the previous question.
     /// * Help: Show the kinds of responses you can enter.
     /// * Quit: Quit the form without completing it.
-    /// * Reset: Start over filling in the form. (With defaults of your previous entries.)
+    /// * Reset: Start over filling in the form. (With defaults from your previous entries.)
     /// * Status: Show your progress in filling in the form so far.
     /// * You can switch to another field by entering its name. (Sandwich, Length, Bread, Cheese, Sauces, and Toppings).
     /// ~~~
@@ -564,7 +564,7 @@
     /// For sandwich toppings you have selected Avocado, Banana Peppers, Cucumbers, Green Bell Peppers, Lettuce, Olives, Pickles, Red Onion, Spinach, and Tomatoes.
     /// ~~~
     /// 
-    /// \subsection ControlFlow Using the Form Builder
+    /// \subsection controlFlow Using the Form Builder
     /// So far we have improved your dialog via attributes and business logic.  There is 
     /// another way to improve your dialog and that is through the FormBuilder.  The FormBuilder
     /// allows more fine-grained control over the steps in your conversation and lets you put in messages
@@ -573,31 +573,82 @@
     /// is explicit navigation.)  Here is a more complex usage of FormBuilder:
     /// \dontinclude AnnotatedSandwichBot/AnnotatedSandwich.cs
     /// \skip static
-    /// \until return
+    /// \until .Build
     /// \until }
     /// 
-    /// The steps this defines are:
-    /// * Show the welcome message  
-    /// * Fill in SandwichOrder.Sandwich  
+    /// This looks complex, but that is because of the addition of advanced features like validation and dynamically defined fields.
+    /// (See \ref dynamicFields for more information.)
+    /// The main structure is all about defining the default step order.  Here are the steps: 
+    /// * Show the welcome message.
+    /// * Fill in SandwichOrder.Sandwich
     /// * Fill in SandwichOrder.Length    
     /// * Fill in SandwichOrder.Bread  
     /// * Fill in SandwichOrder.Cheese
     /// * Fill in SandwichOrder.Toppings  
-    /// * Show a message confirming the selected toppings.    
+    /// * Show a message confirming the selected toppings.      
+    /// * Fill in SandwichOrder.Sauces  
+    /// * Dynamically defined field for SandwichOrder.Specials.  (See \ref dynamicFields for more information.)
+    /// * Dynamically defined confirmation for the cost
     /// * Fill in SandwichOrder.DeliveryAddress and verify the resulting string.  If it does not start with a number we return a message.
     /// * Fill in SandwichOrder.DeliveryTime with a custom prompt.  
     /// * Confirm the order.    
     /// * Add any remaining fields in the order they are defined in your class.  (If this was left out, those steps to fill in those fields would not be included.)
-    /// * Show a final message thanking them.
+    /// * Show a final thank you message.  
+    /// * Define an OnCompletionAsync handler to process the order.
     /// 
     /// In the SandwichOrder.DeliveryTime prompt and the confirmation message you can see an instance of
     /// the \ref patterns where pattern elements like {Length} are filled in from your C# class
     /// before the string is shown to the user.
     /// 
+    /// \subsection dynamicFields Dynamically Defined Fields, Confirmations and Messages
     /// FormBuilder also allows you to do other more advanced things like dynamically switch on
     /// and off parts of your form based on the state of your object or dynamically define fields
     /// rather than drive them off a C# class.  
     /// 
+    /// In order to define a dynamic field, you can implement Advanced.IField yourself, 
+    /// but it is easier to make use of the Advanced.FieldReflector class.  Imagine we would like to 
+    /// create some specials for free drinks and cookies but only for foot-long sandwiches.  
+    /// The first step for using Advanced.FieldReflector is to define
+    /// the underlying field that will contain your dynamic value, like this:
+    /// \dontinclude AnnotatedSandwichBot/AnnotatedSandwich.cs
+    /// \skip Sauces
+    /// \skip Optional
+    /// \until Specials
+    /// 
+    /// We can apply normal attributes to this field like [Optional] to mark the field as allowing a no preference choice and by changing the template 
+    /// value for TemplateUsage.NoPreference. 
+    /// 
+    /// Now we need to add the dynamic part to the FormBuilder like this:
+    /// \dontinclude AnnotatedSandwichBot/AnnotatedSandwich.cs
+    /// \skip nameof(Specials)
+    /// \until }))
+    /// 
+    /// There are a couple of pieces here:
+    /// * Advanced.Field.SetType sets the type of the field--in this case null which means enumeration.
+    /// * Advanced.Field.SetActive provides a delegate that enables the field only when the length is a foot long.  
+    /// * Advanced.Field.SetDefine provides an async delegate for defining the field.  The delegate is passed the current state object and also the Advanced.Field that is being dynamically defined.  
+    /// The delegate uses the fluent methods found on the field to dynamically define values. In this case we define values as strings and supply the descriptions and terms for the value.    
+    /// 
+    /// Messages and confirmations can also be defined dynamically.  Messages and confirmations only run when the prior steps are inactive
+    /// or are completed.  This is a confirmation that computes the cost of the sandwich:
+    /// \dontinclude AnnotatedSandwichBot/AnnotatedSandwich.cs
+    /// \skip Confirm
+    /// \until })
+    /// 
+    /// \subsection quitExceptions Handling Quit and Exceptions
+    /// When the user types 'quit' or there is an exception while filling in a form using FormDialog it is useful to be able
+    /// to know what step the 'quit' or exception happened, the state of the form and and what steps were successfully completed.
+    /// All of these are passed back through the FormCanceledException<T> class.  Here is an example of how to catch the exception and send
+    /// a message after either:
+    /// * Successfully processing the order.  
+    /// * When the user quit.  
+    /// * When there is an exception.
+    /// \dontinclude AnnotatedSandwichBot/Controllers/MessagesController.cs
+    /// \skip MakeRootDialog
+    /// \until });
+    /// \until }
+    /// 
+    /// \subsection finalBot Final Sandwich Bot
     /// Here is the final SandwichOrder with attributes, business logic and a more complex form.
     /// \include AnnotatedSandwichBot/AnnotatedSandwich.cs
     /// 
@@ -623,15 +674,15 @@
     ///  15. Veggie
     /// > 2
     /// What size of sandwich do you want? (1. Six Inch, 2. Foot Long)
-    /// > 1
+    /// > 2
     /// What kind of bread would you like on your sandwich?
     ///  1. Nine Grain Wheat
     ///  2. Nine Grain Honey Oat
     ///  3. Italian
     ///  4. Italian Herbs And Cheese
     ///  5. Flatbread
     /// > nine grain
-    /// By "nine grain" bread did you mean(1. Nine Grain Honey Oat, 2. Nine Grain Wheat)
+    /// By "nine grain" bread did you mean (1. Nine Grain Honey Oat, 2. Nine Grain Wheat)
     /// > 1
     /// What kind of cheese would you like on your sandwich? (current choice: No Preference)
     ///  1. American
@@ -654,7 +705,7 @@
     /// > everything but jalapenos
     /// For sandwich toppings you have selected Avocado, Banana Peppers, Cucumbers, Green Bell Peppers, Lettuce, Olives, Pickles, Red Onion, Spinach, and Tomatoes.
     ///
-    /// Please select one or more sauces(current choice: No Preference)
+    /// Please select one or more sauces (current choice: No Preference)
     ///  1. Honey Mustard
     ///  2. Light Mayonnaise
     ///  3. Regular Mayonnaise
@@ -665,15 +716,22 @@
     ///  8. Sweet Onion
     ///  9. Vinegar
     /// >
+    /// What kind of specials would you like on your sandwich? (current choice: None)
+    ///  1. Free cookie
+    ///  2. Free large drink
+    /// > 1
+    /// Total for your sandwich is $6.50 is that ok?
+    /// >  y
     /// Please enter delivery address
     /// > 123 State Street
     /// What time do you want your sandwich delivered? (current choice: No Preference)
-    /// > 4:30
-    /// Do you want to order your Six Inch Black Forest Ham on Nine Grain Honey Oat bread with Pepperjack, Avocado, Banana Peppers, Cucumbers, Green Bell Peppers, Lettuce, Olives, Pickles, Red Onion, Spinach, and Tomatoes to be sent to 123 State Street at 4:30 PM?
+    /// > 4:30pm
+    /// Do you want to order your Foot Long Black Forest Ham on Nine Grain Honey Oat bread with Pepperjack, Avocado, Banana Peppers, Cucumbers, Green Bell Peppers, Lettuce, Olives, Pickles, Red Onion, Spinach, and Tomatoes to be sent to 123 State Street at 4:30 PM?
     /// > y
     /// Please enter a number between 1.0 and 5.0 for your experience today(current choice: No Preference)
     /// > 5
     /// Thanks for ordering a sandwich!
+    /// Processed your order!
     /// ~~~
     /// 
     /// \section initialState Passing in Initial Form State and Entities

CSharp/Documentation/Forms.cs

@@ -40,10 +40,11 @@ namespace Microsoft.Bot.Builder.Dialogs
     /// \skip Interactive
     /// \until while
     /// \until }
+    /// \until }
     /// 
     /// To use it your would do something like this:
     /// ~~~
-    ///             Interactive(FormDialog.FromForm<AnnotatedSandwichOrder>(() => AnnotatedSandwichOrder.BuildForm()));
+    ///             Interactive(FormDialog.FromForm<AnnotatedSandwichOrder>(() => AnnotatedSandwichOrder.BuildForm())).GetAwaiter().GetResult();
     /// ~~~
     /// 
     /// \section troubleshooting_q_and_a Troubleshooting Q & A

CSharp/Documentation/Overview.cs

@@ -141,6 +141,11 @@ bool IBotDataBag.TryGetValue<T>(string key, out T value)
                 value = default(T);
                 return false;
             }
+
+            bool IBotDataBag.RemoveValue(string key)
+            {
+                return this.bag.Remove(key);
+            }
         }
 
         protected override IBotDataBag WrapData(Dictionary<string, object> data)
@@ -192,6 +197,11 @@ bool IBotDataBag.TryGetValue<T>(string key, out T value)
                 value = default(T);
                 return false;
             }
+
+            bool IBotDataBag.RemoveValue(string key)
+            {
+                return this.bag.Remove(key);
+            }
         }
 
         protected override IBotDataBag WrapData(JObject data)

CSharp/Library/Dialogs/BotData.cs

@@ -31,12 +31,8 @@
 // WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 //
 
-using System;
-using System.Collections;
 using System.Collections.Generic;
 using System.IO;
-using System.Linq;
-using System.Text;
 using System.Threading;
 using System.Threading.Tasks;