Merging changes synced from https://github.com/MicrosoftDocs/bot-docs-pr (branch live)

openpublishbuild · openpublishbuild · commit 425741b585ef · 2019-03-01T22:23:46.000Z
diff --git a/.openpublishing.publish.config.json b/.openpublishing.publish.config.json
@@ -78,20 +78,26 @@
 	"skip_source_output_uploading": false,
 	"need_preview_pull_request": true,
 	"contribution_branch_mappings": {},
-	"dependent_repositories": [
-		{
-			"path_to_root": "_themes",
-			"url": "https://github.com/Microsoft/templates.docs.msft",
-			"branch": "master",
-			"branch_mapping": {}
-		},
-		{
-			"path_to_root": "_themes.pdf",
-			"url": "https://github.com/Microsoft/templates.docs.msft.pdf",
-			"branch": "master",
-			"branch_mapping": {}
-		}
-	],
+    "dependent_repositories": [
+        {
+            "path_to_root": "_themes",
+            "url": "https://github.com/Microsoft/templates.docs.msft",
+            "branch": "master",
+            "branch_mapping": {}
+        },
+        {
+            "path_to_root": "_themes.pdf",
+            "url": "https://github.com/Microsoft/templates.docs.msft.pdf",
+            "branch": "master",
+            "branch_mapping": {}
+        },
+        {
+            "path_to_root": "botbuilder-samples",
+            "url": "https://github.com/Microsoft/BotBuilder-Samples",
+            "branch": "samples-work-in-progress",
+            "branch_mapping": {}
+        }
+    ],
 	"branch_target_mapping": {
 		"live": [
 		   "Publish",
diff --git a/articles/TOC.md b/articles/TOC.md
@@ -39,7 +39,7 @@
 ### [Prompt users for input](v4sdk/bot-builder-primitive-prompts.md) 
 ### [Send welcome message to users](v4sdk/bot-builder-send-welcome-message.md)
 <!-- ## [Add input hints to messages](v4sdk/bot-builder-howto-add-input-hints.md) -->
-### [Get notification from bots](v4sdk/bot-builder-howto-proactive-message.md)
+### [Send proactive notifications to users](v4sdk/bot-builder-howto-proactive-message.md)
 ### [Add natural language understanding to your bot](v4sdk/bot-builder-howto-v4-luis.md)
 ### [Answer user's questions using QnA Maker](v4sdk/bot-builder-howto-qna.md)
 ### [Use multiple LUIS and QnA models](v4sdk/bot-builder-tutorial-dispatch.md)
diff --git a/articles/bot-builder-deploy-az-cli.md b/articles/bot-builder-deploy-az-cli.md
@@ -59,12 +59,11 @@ The source code you downloaded from the Azure portal includes an encrypted .bot
 1. Open the bot's **Application Settings**.
 1. In the **Application Settings** window, scroll down to **Application settings**.
 1. Locate the **botFileSecret** and copy its value.
+1. Use `msbot cli` to decrypt the file.
 
-Use `msbot cli` to decrypt the file.
-
-```cmd
-msbot secret --bot <name-of-bot-file> --secret "<bot-file-secret>" --clear
-```
+    ```cmd
+    msbot secret --bot <name-of-bot-file> --secret "<bot-file-secret>" --clear
+    ```
 
 ### Update your local .bot file
 
@@ -123,18 +122,24 @@ Open the .bot file you decrypted. Copy **all** entries listed under the `service
 
 Save the file.
 
+You can use the msbot tool to generate a new secret and encrypt the .bot file before you publish. If you re-encrypt your .bot file, update the bot's **botFileSecret** in the Azure portal to contain the new secret.
+
+```cmd
+msbot secret --bot <name-of-bot-file> --new
+```
+
 ### Setup a repository
 
-To support continuous deployment, create a git repository using your favorite git source control provider. Commit your code into the repository. 
+To support continuous deployment, create a git repository using your favorite git source control provider. Commit your code into the repository.
 
 Make sure that your repository root has the correct files, as described under [prepare your repository](https://docs.microsoft.com/azure/app-service/deploy-continuous-deployment#prepare-your-repository).
 
 ### Update App Settings in Azure
-The local bot does not use an encrypted .bot file, but the Azure portal has an that you are deploying doesn't 
+The local bot does not use an encrypted .bot file, but the Azure portal is configured to use an encrypted .bot file. You can resolve this by removing the **botFileSecret** stored in the Azure bot settings.
 1. In the Azure portal, open the **Web App Bot** resource for your bot.
 1. Open the bot's **Application Settings**.
 1. In the **Application Settings** window, scroll down to **Application settings**.
-1. Locate the **botFileSecret** and delete it.
+1. Locate the **botFileSecret** and delete it. (If you re-encrypted your .bot file, make sure the **botFileSecret** contains the new secret and **do not** delete the setting.)
 1. Update the name of the bot file to match the file you checked into the repo.
 1. Save changes.
 
diff --git a/articles/bot-service-channels-reference.md b/articles/bot-service-channels-reference.md
diff --git a/articles/bot-service-debug-bot.md b/articles/bot-service-debug-bot.md
@@ -8,7 +8,7 @@ manager: kamrani
 ms.topic: article
 ms.service: bot-service
 ms.subservice: sdk
-ms.date: 2/09/2019
+ms.date: 2/26/2019
 ---
 
 # Debug a bot
@@ -133,8 +133,10 @@ Additionally, you can view log details in the console window.
 
 ## Additional resources
 
-To learn about debugging bots in production, refer to [Debug any channel locally using ngrok](https://blog.botframework.com/2017/10/19/debug-channel-locally-using-ngrok/) blogpost.
+- See [troubleshoot general problems](bot-service-troubleshoot-bot-configuration.md) and the other troubleshooting articles in that section.
+- See the how to [debug any channel locally using ngrok](https://blog.botframework.com/2017/10/19/debug-channel-locally-using-ngrok/) blog post.
 
 ## Next steps
+
 > [!div class="nextstepaction"]
-> [Debug your bot using transcript files](~/v4sdk/bot-builder-debug-transcript.md).
+> [Debug your bot using transcript files](v4sdk/bot-builder-debug-transcript.md).
diff --git a/articles/bot-service-debug-emulator.md b/articles/bot-service-debug-emulator.md
@@ -7,7 +7,7 @@ ms.author: v-demak
 manager: kamrani
 ms.topic: article
 ms.service: bot-service
-ms.date: 11/13/2018
+ms.date: 2/26/2019
 ---
 
 # Debug with the emulator
@@ -76,7 +76,9 @@ Open the **Emulator Settings**, enter the path to ngrok, select whether or not t
 
 The Bot Framework Emulator is open source. You can [contribute][EmulatorGithubContribute] to the development and [submit bugs and suggestions][EmulatorGithubBugs].
 
+For troubleshooting, see [troubleshoot general problems](bot-service-troubleshoot-bot-configuration.md) and the other troubleshooting articles in that section.
 
+<!-- Footnote-style URLs -->
 
 [EmulatorGithubContribute]: https://github.com/Microsoft/BotFramework-Emulator/wiki/How-to-Contribute
 [EmulatorGithubBugs]: https://github.com/Microsoft/BotFramework-Emulator/wiki/Submitting-Bugs-%26-Suggestions
diff --git a/articles/bot-service-troubleshoot-authentication-problems.md b/articles/bot-service-troubleshoot-authentication-problems.md
@@ -6,7 +6,7 @@ ms.author: v-demak
 manager: kamrani
 ms.topic: article
 ms.service: bot-service
-ms.date: 12/13/17
+ms.date: 02/26/2019
 ---
 
 # Troubleshooting Bot Framework authentication
@@ -222,6 +222,7 @@ If the bot responds appropriately to the input, you have verified that your bot
 
 If you are still experiencing issues after completing the steps above, you can:
 
+* Review how-to [debug a bot](bot-service-debug-bot.md) and the other debugging articles in that section.
 * [Debug your bot in the cloud](~/bot-service-debug-emulator.md) using the Bot Framework Emulator and <a href="https://ngrok.com/" target="_blank">ngrok</a>.
 * Use a proxying tool like [Fiddler](https://www.telerik.com/fiddler) to inspect HTTPS traffic to and from your bot. *Fiddler is not a Microsoft product.*
 * Review the [Bot Connector authentication guide][BotConnectorAuthGuide] to learn about the authentication technologies that the Bot Framework uses.
diff --git a/articles/bot-service-troubleshoot-bot-configuration.md b/articles/bot-service-troubleshoot-bot-configuration.md
@@ -8,7 +8,7 @@ manager: kamrani
 ms.topic: article
 ms.service: bot-service
 ms.subservice: sdk
-ms.date: 12/20/2018
+ms.date: 2/26/2019
 ---
 
 # Troubleshoot bot configuration issues
@@ -82,3 +82,7 @@ Below are some additional links that can help with individual channels:
 Occasionally, some channels might have an interruption of service. Usually, such outages don't last long. However, if you suspect an outage, consult a channel web site or social media.
 
 Another way to determine if a channel has an outage is to create a test bot (such as a simple Echo Bot) and add a channel. If the test bot works with some channels but not others, that would indicate that the problem is not in your production bot.
+
+## Additional resources
+
+See how-to [debug a bot](bot-service-debug-bot.md) and the other debugging articles in that section.
diff --git a/articles/bot-service-troubleshoot-general-problems.md b/articles/bot-service-troubleshoot-general-problems.md
@@ -6,7 +6,7 @@ ms.author: v-demak
 manager: kamrani
 ms.topic: article
 ms.service: bot-service
-ms.date: 09/26/2018
+ms.date: 02/26/2019
 ---
 
 # Troubleshooting general problems
@@ -15,11 +15,12 @@ These frequently asked questions can help you to troubleshoot common bot develop
 ## How can I troubleshoot issues with my bot?
 
 1. Debug your bot's source code with [Visual Studio Code](debug-bots-locally-vscode.md) or [Visual Studio](https://docs.microsoft.com/en-us/visualstudio/debugger/navigating-through-code-with-the-debugger?view=vs-2017).
-2. Test your bot using the [emulator](bot-service-debug-emulator.md) before you deploy it to the cloud.
-3. Deploy your bot to a cloud hosting platform such as Azure and then test connectivity to your bot by using the built-in web chat control on your bot's dashboard in the <a href="https://dev.botframework.com" target="_blank">Bot Framework Portal</a>. If you encounter issues with your bot after you deploy it to Azure, you might consider using this blog article: [Understanding Azure troubleshooting and support](https://azure.microsoft.com/en-us/blog/understanding-azure-troubleshooting-and-support/).
-4. Rule out [authentication][TroubleshootingAuth] as a possible issue.
-5. Test your bot on Skype. This will help you to validate the end-to-end user experience.
-6. Consider testing your bot on channels that have additional authentication requirements such as Direct Line or Web Chat.
+1. Test your bot using the [emulator](bot-service-debug-emulator.md) before you deploy it to the cloud.
+1. Deploy your bot to a cloud hosting platform such as Azure and then test connectivity to your bot by using the built-in web chat control on your bot's dashboard in the <a href="https://dev.botframework.com" target="_blank">Bot Framework Portal</a>. If you encounter issues with your bot after you deploy it to Azure, you might consider using this blog article: [Understanding Azure troubleshooting and support](https://azure.microsoft.com/en-us/blog/understanding-azure-troubleshooting-and-support/).
+1. Rule out [authentication][TroubleshootingAuth] as a possible issue.
+1. Test your bot on Skype. This will help you to validate the end-to-end user experience.
+1. Consider testing your bot on channels that have additional authentication requirements such as Direct Line or Web Chat.
+1. Review the how-to [debug a bot](bot-service-debug-bot.md) and the other debugging articles in that section.
 
 ## How can I troubleshoot authentication issues?
 
diff --git a/articles/docfx.json b/articles/docfx.json
@@ -91,14 +91,13 @@
     "globalMetadata": {
       "uhfHeaderId": "MSDocsHeader-BotFramework",
       "breadcrumb_path": "/bot-framework/breadcrumb/TOC.json",
-      "author": "RobStand",
-      "ms.prod": "bot-framework",
+      "author": "kaiqb",
       "brand": "azure",
       "searchScope": [
         "Azure",
         "BotService"
       ],
-      "ms.date": "12/13/2017",
+      "ms.date": "12/13/2018",
       "titleSuffix": "Bot Service",
       "feedback_system": "GitHub",
       "feedback_github_repo": "MicrosoftDocs/bot-docs"
@@ -110,11 +109,8 @@
       "manager": {
         "**/**.md": "kaiqb"
       },
-      "ms.technology": {
-        "**/**.md": "bf-bot-builder"
-      },
       "ms.date": {
-        "**/**.md": "12/13/2017"
+        "**/**.md": "12/13/2018"
       },
       "monikerRange": {
         "v4sdk/**.md": "azure-bot-service-4.0"
diff --git a/articles/media/azure-bot-quickstarts/bot-builder-dotnet-project.png b/articles/media/azure-bot-quickstarts/bot-builder-dotnet-project.png
diff --git a/articles/nodejs/bot-builder-nodejs-search-azure.md b/articles/nodejs/bot-builder-nodejs-search-azure.md
@@ -148,7 +148,7 @@ function searchHitAsCard(showSave, searchHit) {
 ## Sample code
 
 For two complete samples that show how to support Azure Search with bots using the Bot Framework SDK for Node.js, see the 
-[Real Estate Bot sample](https://github.com/Microsoft/BotBuilder-Samples/tree/master/Node/demo-Search/RealEstateBot) or [Job Listing Bot sample](https://github.com/Microsoft/BotBuilder-Samples/tree/master/Node/demo-Search/JobListingBot) in GitHub. 
+[Real Estate Bot sample](https://github.com/Microsoft/BotBuilder-Samples/tree/v3-sdk-samples/Node/demo-Search/RealEstateBot) or [Job Listing Bot sample](https://github.com/Microsoft/BotBuilder-Samples/tree/v3-sdk-samples/Node/demo-Search/JobListingBot) in GitHub. 
 
 ## Additional resources
 
diff --git a/articles/resources/TOC.md b/articles/resources/TOC.md
@@ -9,6 +9,7 @@
 ## [Overview](../v4sdk/bot-builder-virtual-assistant-introduction.md)
 # [FAQ](../bot-service-resources-bot-framework-faq.md)
 # [Get support](../bot-service-resources-links-help.md)
+# [Channel reference](../bot-service-channels-reference.md)
 # [Guide to identifiers](../bot-service-resources-identifiers-guide.md)
 # [App Insights keys](../bot-service-resources-app-insights-keys.md)
 # [User-agent requests](../bot-service-resources-user-agent.md)
diff --git a/articles/v4sdk/bot-builder-concept-state.md b/articles/v4sdk/bot-builder-concept-state.md
@@ -8,7 +8,7 @@ manager: kamrani
 ms.topic: article
 ms.service: bot-service
 ms.subservice: sdk
-ms.date: 11/15/2018
+ms.date: 02/25/2019
 monikerRange: 'azure-bot-service-4.0'
 ---
 
@@ -114,7 +114,7 @@ The accessor methods are the primary way for your bot to interact with state. Ho
   - Accessor requests property from the state cache.
   - If the property is in the cache, return it. Otherwise, get it from the state management object.
     (If it is not yet in state, use the factory method provided in the accessors *get* call.)
--The accessor's *set* method:
+- The accessor's *set* method:
   - Update the state cache with the new property value.
 - The state management object's *save changes* method:
   - Check the changes to the property in the state cache.
diff --git a/articles/v4sdk/bot-builder-debug-transcript.md b/articles/v4sdk/bot-builder-debug-transcript.md
@@ -8,7 +8,7 @@ manager: kamrani
 ms.topic: article
 ms.service: bot-service
 ms.subservices: sdk
-ms.date: 10/18/2018
+ms.date: 2/26/2019
 monikerRange: 'azure-bot-service-4.0'
 ---
 
@@ -60,9 +60,10 @@ This detailed level of information allows you to follow the step-by-step interac
 Using transcript files together with the Bot Framework Emulator is just one of the many tools you can use to help you test and debug your bot's code and user interactions. To find more ways to test and debug your bot, see the additional resources listed below.
 
 ## Additional resources
+
 For additional testing and debugging information see:
+
 * [Bot testing and debugging guidelines](./bot-builder-testing-debugging.md)
 * [Debug with the bot framework emulator](../bot-service-debug-emulator.md)
+* [Troubleshoot general problems](../bot-service-troubleshoot-bot-configuration.md) and the other troubleshooting articles in that section.
 * [Debugging in Visual Studio](https://docs.microsoft.com/en-us/visualstudio/debugger/index)
-
-
diff --git a/articles/v4sdk/bot-builder-howto-add-media-attachments.md b/articles/v4sdk/bot-builder-howto-add-media-attachments.md
@@ -8,28 +8,31 @@ manager: kamrani
 ms.topic: article
 ms.service: bot-service
 ms.subservice: sdk
-ms.date: 01/16/2019
+ms.date: 02/27/2019
 monikerRange: 'azure-bot-service-4.0' 
 ---
 
 # Add media to messages
 
 [!INCLUDE [pre-release-label](../includes/pre-release-label.md)]
 
-Messages exchanged between user and bot can contain media attachments, such as images, video, audio, and files. The Bot Framework SDK supports the task of sending rich messages to the user. To determine the type of rich messages a channel (Facebook, Skype, Slack, etc.) supports, consult the channel's documentation for information about limitations. Refer to [design user experience](../bot-service-design-user-experience.md) for a list of available cards.
+Messages exchanged between user and bot can contain media attachments, such as images, video, audio, and files. The Bot Framework SDK supports the task of sending rich messages to the user. To determine the type of rich messages a channel (Facebook, Skype, Slack, etc.) supports, consult the channel's documentation for information about limitations.
+
+See [design user experience](../bot-service-design-user-experience.md) for examples of available cards.
 
 ## Send attachments
 
 To send the user content like an image or a video, you can add an attachment or list of attachments to a message.
 
+See [design user experience](../bot-service-design-user-experience.md) for examples of available cards.
+
 # [C#](#tab/csharp)
 
 The `Attachments` property of the `Activity` object contains an array of `Attachment` objects that represent the media attachments and rich cards attached to the message. To add a media attachment to a message, create an `Attachment` object for the `message` activity and set the `ContentType`, `ContentUrl`, and `Name` properties.
 The source code shown here is based on the [Handling Attachments](https://aka.ms/bot-attachments-sample-code) sample. 
 
 ```csharp
 using Microsoft.Bot.Builder;
-using Microsoft.Bot.Builder.Core.Extensions;
 using Microsoft.Bot.Schema;
 
 var reply = turnContext.Activity.CreateReply();
@@ -46,7 +49,7 @@ var attachment = new Attachment
 reply.Attachments = new List<Attachment>() { attachment };
 
 // Send the activity to the user.
-await turnContext.SendActivityAsync(reply, cancellationToken);
+await turnContext.SendActivityAsync(reply, cancellationToken: cancellationToken);
 ```
 
 # [JavaScript](#tab/javascript)
@@ -87,7 +90,6 @@ To compose a message with a hero card and button, you can attach a `HeroCard` to
 
 ```csharp
 using Microsoft.Bot.Builder;
-using Microsoft.Bot.Builder.Core.Extensions;
 using Microsoft.Bot.Schema;
 
 var reply = turnContext.Activity.CreateReply();
@@ -107,7 +109,7 @@ var card = new HeroCard
 // Add the card to our reply.
 reply.Attachments = new List<Attachment>() { card.ToAttachment() };
 
-await turnContext.SendActivityAsync(reply, cancellationToken);
+await turnContext.SendActivityAsync(reply, cancellationToken: cancellationToken);
 ```
 
 # [JavaScript](#tab/javascript)
@@ -163,7 +165,6 @@ The following code shows examples using various rich card events.
 
 ```csharp
 using Microsoft.Bot.Builder;
-using Microsoft.Bot.Builder.Core.Extensions;
 using Microsoft.Bot.Schema;
 
 var reply = turnContext.Activity.CreateReply();
@@ -234,7 +235,6 @@ The source code shown here is based on the [Using Adaptive Cards](https://aka.ms
 ```csharp
 using AdaptiveCards;
 using Microsoft.Bot.Builder;
-using Microsoft.Bot.Builder.Core.Extensions;
 using Microsoft.Bot.Schema;
 using Newtonsoft.Json;
 
@@ -256,7 +256,7 @@ var cardAttachment = CreateAdaptiveCardAttachment(adaptiveCardJsonFilePath);
 var reply = turnContext.Activity.CreateReply();
 reply.Attachments = new List<Attachment>() { cardAttachment };
 
-await turnContext.SendActivityAsync(reply, cancellationToken);
+await turnContext.SendActivityAsync(reply, cancellationToken: cancellationToken);
 ```
 
 # [JavaScript](#tab/javascript)
@@ -300,7 +300,6 @@ Messages can also include multiple attachments in a carousel layout, which place
 
 ```csharp
 using Microsoft.Bot.Builder;
-using Microsoft.Bot.Builder.Core.Extensions;
 using Microsoft.Bot.Schema;
 
 // Create the activity and attach a set of Hero cards.
@@ -334,7 +333,7 @@ var activity = MessageFactory.Carousel(
     });
 
 // Send the activity as a reply to the user.
-await context.SendActivity(activity);
+await turnContext.SendActivityAsync(reply, cancellationToken: cancellationToken);
 ```
 
 # [JavaScript](#tab/javascript)
@@ -359,6 +358,8 @@ await context.sendActivity(messageWithCarouselOfCards);
 
 ## Additional resources
 
+See [design user experience](../bot-service-design-user-experience.md) for examples of available cards.
+
 For detailed information on the schema, see the [Bot Framework card schema](https://aka.ms/botSpecs-cardSchema) and the [message activity section](https://aka.ms/botSpecs-activitySchema#message-activity) of the Bot Framework Activity schema.
 
 Sample code can be found here for
diff --git a/articles/v4sdk/bot-builder-howto-add-suggested-actions.md b/articles/v4sdk/bot-builder-howto-add-suggested-actions.md
diff --git a/articles/v4sdk/bot-builder-howto-proactive-message.md b/articles/v4sdk/bot-builder-howto-proactive-message.md
diff --git a/articles/v4sdk/bot-builder-howto-qna.md b/articles/v4sdk/bot-builder-howto-qna.md
diff --git a/articles/v4sdk/bot-builder-testing-debugging.md b/articles/v4sdk/bot-builder-testing-debugging.md
