Merge pull request microsoft#129 from southworkscom/rollerskill-readmes

[READMEs] Readme updates for RollerSkill Samples

CSharp/demo-RollerSkill/README.md

@@ -0,0 +1,96 @@
+# Roller Skill Bot Sample
+
+A sample bot optimized for speech-enabled channels such as Cortana.
+
+### Prerequisites
+
+The minimum prerequisites to run this sample are:
+* The latest update of Visual Studio 2015. You can download the community version [here](http://www.visualstudio.com) for free.
+* The Bot Framework Emulator. To install the Bot Framework Emulator, download it from [here](https://emulator.botframework.com/). Please refer to [this documentation article](https://github.com/microsoft/botframework-emulator/wiki/Getting-Started) to know more about the Bot Framework Emulator.
+* To fully test this sample you must:
+    * Register you bot in [Microsoft Bot Framework Portal](https://dev.botframework.com/bots). Please refer to [this](https://docs.microsoft.com/en-us/bot-framework/portal-register-bot) for the instructions. Once you complete the registration, update the [Bot's Web.config](Web.config#L9-L11) file with the registered config values (Bot Id, MicrosoftAppId and MicrosoftAppPassword). 
+    * Enable the Cortana Channel and register your bot as a Cortana skill. Refer to [this](https://docs.microsoft.com/en-us/bot-framework/portal-configure-channels) for more information on how to configure channels and to [this](https://docs.microsoft.com/en-us/bot-framework/channels/channel-cortana) and [this](https://docs.microsoft.com/en-us/cortana/tutorials/bot-skills/add-bot-to-cortana-channel) for specific information on how to add the Cortana channel to your bot.
+    *  [Publish your bot, for example to Azure](https://docs.microsoft.com/en-us/bot-framework/deploy-bot-overview) or use [Ngrok to interact with your local bot in the cloud](https://blogs.msdn.microsoft.com/jamiedalton/2016/07/29/ms-bot-framework-ngrok/).
+
+
+### Code Highlights
+Many channels provides an audio component besides the usual visual component, allowing your bot to have a voice. The BotBuilder SDK has set of features designed specifically to support speech based channels such as Cortana. 
+
+The [`IMessageActivity`](https://github.com/Microsoft/BotBuilder/blob/master/CSharp/Library/Microsoft.Bot.Connector.Shared/IMessageActivity.cs) interface contains two properties (`Speak` and `InputHint`) to support speech responses allowing you to define what the bot will say and the speech based client should manage the microphone.
+
+The `Speak` property should contain text or Speech Synthesis Markup Language (SSML). 
+
+The `InputHint` property expects one of the following values from the [`InputHints`](https://github.com/Microsoft/BotBuilder/blob/master/CSharp/Library/Microsoft.Bot.Connector.Shared/InputHints.cs) enumeration:
+
+|Name|Description|
+|---|---|
+|AcceptingInput|Your bot is passively ready for input but is not waiting on a response (the mic should be closed)|
+|ExpectingInput|Your bot is actively expecting a response from the user (the mic should be left open)|
+|IgnoringInput|Your bot is ignoring input. Bots may send this hint if they are actively processing a request and will ignore input from users until the request is complete|
+
+In general the BotBuilder SDK will send these hints for you automatically, so you don't have to worry too much about them. Checkout the use of the `Speak` and `InputHint` properties in the [`StartAsync`](Dialogs/HelpDialog.cs#L20-L21) method from the [`HelpDialog`](Dialogs/HelpDialog.cs) class.
+
+```
+public async Task StartAsync(IDialogContext context)
+{
+    var message = context.MakeMessage();
+    message.Speak = SSMLHelper.Speak(Resources.HelpSSML);
+    message.InputHint = InputHints.AcceptingInput;
+
+    message.Attachments = new List<Attachment>
+    {
+        new HeroCard(Resources.HelpTitle)
+        {
+            Buttons = new List<CardAction>
+            {
+                new CardAction(ActionTypes.ImBack, "Roll Dice", value: RollDiceOptionValue),
+                new CardAction(ActionTypes.ImBack, "Play Craps", value: PlayCrapsOptionValue)
+            }
+        }.ToAttachment()
+    };
+
+    await context.PostAsync(message);
+
+    context.Done<object>(null);
+}
+```
+
+Built-in prompts also have speech support and they can send plain text as well as SSML thanks to the `Speak` and `RetrySpeak` properties from the [`PromptOptions<T>`](https://github.com/Microsoft/BotBuilder/blob/master/CSharp/Library/Microsoft.Bot.Builder/Dialogs/PromptDialog.cs#L90) class. Checkout the use of the `Speak` property in a PromptChoice dialog in the [`StartAsync`](Dialogs/CreateGameDialog.cs#L31) method from the [`CreateGameDialog`](Dialogs/CreateGameDialog.cs) class.
+
+```
+public async Task StartAsync(IDialogContext context)
+{
+    context.UserData.SetValue<GameData>(Utils.GameDataKey, new GameData());
+
+    var descriptions = new List<string>() { "4 Sides", "6 Sides", "8 Sides", "10 Sides", "12 Sides", "20 Sides" };
+    var choices = new Dictionary<string, IReadOnlyList<string>>()
+        {
+        { "4", new List<string> { "four", "for", "4 sided", "4 sides" } },
+        { "6", new List<string> { "six", "sex", "6 sided", "6 sides" } },
+        { "8", new List<string> { "eight", "8 sided", "8 sides" } },
+        { "10", new List<string> { "ten", "10 sided", "10 sides" } },
+        { "12", new List<string> { "twelve", "12 sided", "12 sides" } },
+        { "20", new List<string> { "twenty", "20 sided", "20 sides" } }
+    };
+
+    var promptOptions = new PromptOptions<string>(
+        Resources.ChooseSides,
+        choices: choices,
+        descriptions: descriptions,
+        speak: SSMLHelper.Speak(Utils.RandomPick(Resources.ChooseSidesSSML)));
+
+    PromptDialog.Choice(context, this.DiceChoiceReceivedAsync, promptOptions);
+}
+```
+### Outcome
+You will see the following when talking to the Bot via Cortana.
+
+![Sample Outcome](images/outcome-cortana.png)
+
+
+### More Information
+To get more information about how to get started in Bot Builder for .NET and Attachments please review the following resources:
+* [Bot Builder for .NET](https://docs.microsoft.com/en-us/bot-framework/dotnet/)
+* [Build a speech-enabled bot with Cortana Skills](https://docs.microsoft.com/en-us/bot-framework/dotnet/bot-builder-dotnet-cortana-skill)
+* [The Cortana Skills Kit](https://docs.microsoft.com/en-us/cortana/getstarted)
+* [Creating a Skill from Scratch using Bot Framework](https://docs.microsoft.com/en-us/cortana/tutorials/bot-skills/add-bot-to-cortana-channel)

Node/demo-RollerSkill/README.md

@@ -1,6 +1,6 @@
-# Roller Sample Skill
+# Roller Skill Bot Sample
 
-A simple dice rolling skill/bot that's been optimized for speech enabled channels. 
+A simple dice rolling skill/bot that's been optimized for speech-enabled channels such as Cortana.
 
 [![Deploy to Azure][Deploy Button]][Deploy Node/RollerSkill]
 
@@ -13,20 +13,90 @@ The minimum prerequisites to run this sample are:
 * Latest Node.js with NPM. Download it from [here](https://nodejs.org/en/download/).
 * The Bot Framework Emulator. To install the Bot Framework Emulator, download it from [here](https://emulator.botframework.com/). Please refer to [this documentation article](https://github.com/microsoft/botframework-emulator/wiki/Getting-Started) to know more about the Bot Framework Emulator.
 * **[Recommended]** Visual Studio Code for IntelliSense and debugging, download it from [here](https://code.visualstudio.com/) for free.
+* To fully test this sample you must:
+    * Register you bot in [Microsoft Bot Framework Portal](https://dev.botframework.com/bots). Please refer to [this](https://docs.microsoft.com/en-us/bot-framework/portal-register-bot) for the instructions. Once you complete the registration, update the [.env](.env) file with the registered config values. 
+    * Enable the Cortana Channel and register your bot as a Cortana skill. Refer to [this](https://docs.microsoft.com/en-us/bot-framework/portal-configure-channels) for more information on how to configure channels and to [this](https://docs.microsoft.com/en-us/bot-framework/channels/channel-cortana) and [this](https://docs.microsoft.com/en-us/cortana/tutorials/bot-skills/add-bot-to-cortana-channel) for specific information on how to add the Cortana channel to your bot.
+    *  [Publish your bot, for example to Azure](https://docs.microsoft.com/en-us/bot-framework/deploy-bot-overview) or [Debug an Azure Bot Service bot](https://docs.microsoft.com/en-us/bot-framework/azure/azure-bot-service-debug-bot).
 
 ### Code Highlights
 
-The sample showcases the use of new features designed specifically for speech:
+Many channels provides an audio component besides the usual visual component, allowing your bot to have a voice. This sample showcases the use of new features designed specifically for speech:
 
 * **IMessage.speak**: Lets include Speech Synthesis Markup Language (SSML) in your bots responses to control what the bot says, in addition to what it shows. A small [utility module](ssml.js) is included to simplify building up your bots SSML based responses.
-* **IMessage.inputHint**: Used to provide a speech based client with hints as to how they should manage the microphone. A hint of `InputHints.ignoringInput` can be sent to tell the client that the bot will be sending more messages and should wait to open the mic. The `InputHints.acceptingInput` hint means that the bot is finished speaking and ready to receive additional requests from the user but the mic should be closed. And the `InputHints.expectingInput` hint indicates that the bot is expecting an answer to a prompt and the mic should be left open. In general, the SDK will send these hints for you automatically so you don't have to worry too much about them.
+* **IMessage.inputHint**: Used to provide a speech based client with hints as to how they should manage the microphone, expects one of the following values from the [`builder.InputHint`](https://docs.botframework.com/en-us/node/builder/chat-reference/modules/_botbuilder_d_.html#inputhint):
+
+|Name|Description|
+|---|---|
+|InputHint.acceptingInput|Your bot is passively ready for input but is not waiting on a response (the mic should be closed)|
+|InputHint.expectingInput|Your bot is actively expecting a response from the user (the mic should be left open)|
+|InputHint.ignoringInput|Your bot is ignoring input. Bots may send this hint if they are actively processing a request and will ignore input from users until the request is complete|
+
 * **Session.say()**: A new method that can be called in place of `Session.send()` and includes additional parameters for sending SSML output, as well as attachments like cards. 
 * **IPromptOptions.speak & retrySpeak**: The built-in prompts have all been updated to support sending SSML as part of the prompts output.
 * **Prompts.choice() synonyms**: The built-in choice() prompt has been updated to support passing in synonyms which allows for more flexibility recognition wise.
 * **Other Prompt Improvements**: A number of other improvements have been made to the built-in prompts to add with building bots that work better with speech recognition.
 
+In general the BotBuilder SDK will send these hints for you automatically, so you don't have to worry too much about them. Checkout the use of the [`speak` method helper](app.js#L267-L271) and `InputHint` properties in the [`HelpDialog`](app.js#L253-L265) dialog.
+
+````JavaScript
+bot.dialog('HelpDialog', function (session) {
+    var card = new builder.HeroCard(session)
+        .title('help_title')
+        .buttons([
+            builder.CardAction.imBack(session, 'roll some dice', 'Roll Dice'),
+            builder.CardAction.imBack(session, 'play craps', 'Play Craps')
+        ]);
+    var msg = new builder.Message(session)
+        .speak(speak(session, 'help_ssml'))
+        .addAttachment(card)
+        .inputHint(builder.InputHint.acceptingInput);
+    session.send(msg).endDialog();
+}).triggerAction({ matches: /help/i });
+
+/** Helper function to wrap SSML stored in the prompts file with <speak/> tag. */
+function speak(session, prompt) {
+    var localized = session.gettext(prompt);
+    return ssml.speak(localized);
+}
+````
+
+Built-in prompts also have speech support and they can send plain text as well as SSML thanks to the `speak` property from the [`IPromptChoiceOptions`](https://docs.botframework.com/en-us/node/builder/chat-reference/interfaces/_botbuilder_d_.ipromptchoiceoptions.html#speak). Checkout the use of the `speak` property in a PromptChoice dialog in the [`CreateGameDialog`](apps.js#L58-L79) dialog.
+
+````JavaScript
+/**
+    * Ask for the number of sides.
+    * 
+    * You can pass an array of choices to be matched. These will be shown as a
+    * numbered list by default.  This list will be shown as a numbered list which
+    * is what we want since we have so many options.
+    * 
+    * - value is what you want returned via 'results.response.entity' when selected.
+    * - action lets you customize the displayed label and for buttons what get sent when clicked.
+    * - synonyms let you specify alternate things to recognize for a choice.
+    */
+var choices = [
+    { value: '4', action: { title: '4 Sides' }, synonyms: 'four|for|4 sided|4 sides' },
+    { value: '6', action: { title: '6 Sides' }, synonyms: 'six|sex|6 sided|6 sides' },
+    { value: '8', action: { title: '8 Sides' }, synonyms: 'eight|8 sided|8 sides' },
+    { value: '10', action: { title: '10 Sides' }, synonyms: 'ten|10 sided|10 sides' },
+    { value: '12', action: { title: '12 Sides' }, synonyms: 'twelve|12 sided|12 sides' },
+    { value: '20', action: { title: '20 Sides' }, synonyms: 'twenty|20 sided|20 sides' }
+];
+builder.Prompts.choice(session, 'choose_sides', choices, { 
+    speak: speak(session, 'choose_sides_ssml') 
+});
+````
+
+### Outcome
+You will see the following when talking to the Bot via Cortana.
+
+![Sample Outcome](images/outcome-cortana.png)
+
 ### More Information
 
 To get more information about how to get started in Bot Builder for Node please review the following resources:
 * [Bot Builder for Node.js Reference](https://docs.microsoft.com/en-us/bot-framework/nodejs/)
 * [SSML Language Reference](https://msdn.microsoft.com/en-us/library/hh378377(v=office.14).aspx)
+* [Build a speech-enabled bot with Cortana Skills](https://docs.microsoft.com/en-us/bot-framework/nodejs/bot-builder-nodejs-cortana-skill)
+* [The Cortana Skills Kit](https://docs.microsoft.com/en-us/cortana/getstarted)
+* [Creating a Skill from Scratch using Bot Framework](https://docs.microsoft.com/en-us/cortana/tutorials/bot-skills/add-bot-to-cortana-channel)