Release 'live' 11-08-2018 (#1077)

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,24 @@
+---
+name: Bug report
+about: Create a report to help us improve
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Additional context**
+Add any other context about the problem here.

articles/TOC.md

@@ -13,11 +13,10 @@
 ## [Samples repo on GitHub](https://github.com/Microsoft/BotBuilder-Samples/blob/master/readme.md)
 # Concepts
 ## [How bots work](v4sdk/bot-builder-basics.md)
-## [Dialogs library](v4sdk/bot-builder-concept-dialog.md)
-## [Dialogs state](v4sdk/bot-builder-dialog-state.md)
 ## [Middleware](v4sdk/bot-builder-concept-middleware.md)
-## [Welcoming the user](v4sdk/bot-builder-welcome-user.md)
-## [Language understanding](v4sdk/bot-builder-concept-luis.md)
+## [About Dialogs library](v4sdk/bot-builder-concept-dialog.md)
+## [Understanding Dialogs state](v4sdk/bot-builder-dialog-state.md)
+<!-- [Language understanding](v4sdk/bot-builder-concept-luis.md) -->
 ## [Bot Service templates](bot-service-concept-templates.md)
 ## [Cognitive Services](bot-service-concept-intelligence.md)
 ## [Key scenarios for bots](bot-service-scenario-overview.md)
@@ -26,22 +25,23 @@
 ### [Enterprise Productivity bot](bot-service-scenario-enterprise-productivity.md)
 ### [Information bot](bot-service-scenario-informational.md)
 ### [Internet of Things bot](bot-service-scenario-internet-things.md)
-# How-To
+# How-To 
 ## [Design](design/TOC.md)
 ## Develop
+<!-- ## [Best practice for welcoming the user](v4sdk/bot-builder-welcome-user.md) -->
+### [Send text message to users](v4sdk/bot-builder-howto-send-messages.md)
+### [Add media to messages](v4sdk/bot-builder-howto-add-media-attachments.md)
+### [Use button for input](v4sdk/bot-builder-howto-add-suggested-actions.md)
 ### [Send welcome message to users](v4sdk/bot-builder-send-welcome-message.md)
-### [Send text and spoken messages](v4sdk/bot-builder-howto-send-messages.md)
-### [Include media attachments in messages](v4sdk/bot-builder-howto-add-media-attachments.md)
-### [Add input hints to messages](v4sdk/bot-builder-howto-add-input-hints.md)
-### [Suggest actions to users](v4sdk/bot-builder-howto-add-suggested-actions.md)
-<!-- ### [Save user input](v4sdk/bot-builder-primitive-prompts.md) -->
-### [Manage state](v4sdk/bot-builder-howto-v4-state.md) 
-### [Proactively send messages to user](v4sdk/bot-builder-howto-proactive-message.md)
-### [Add language understanding capability](v4sdk/bot-builder-howto-v4-luis.md)
+<!-- ## [Add input hints to messages](v4sdk/bot-builder-howto-add-input-hints.md) -->
+### [Get notification from bot](v4sdk/bot-builder-howto-proactive-message.md)
+<!-- ## [Save user input](v4sdk/bot-builder-primitive-prompts.md) -->
+### [Save user and conversation data](v4sdk/bot-builder-howto-v4-state.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)
 ### Manage conversations using the Dialogs library 
 #### [Gather user input](v4sdk/bot-builder-prompts.md)
-#### [Implement basic sequential conversation flow](v4sdk/bot-builder-dialog-manage-conversation-flow.md)
+#### [Implement sequential conversation flow](v4sdk/bot-builder-dialog-manage-conversation-flow.md)
 #### [Create advance conversation flow using branches and loops](v4sdk/bot-builder-dialog-manage-complex-conversation-flow.md)
 #### [Handle user interruptions](v4sdk/bot-builder-howto-handle-user-interrupt.md)
 #### [Persist data in dialogs](v4sdk/bot-builder-tutorial-persist-user-inputs.md)
@@ -50,7 +50,6 @@
 ### [Add authentication to your bot](v4sdk/bot-builder-authentication.md)
 ### [Implement custom storage for your bot](v4sdk/bot-builder-custom-storage.md)
 ### [Manage bots using CLI tools](bot-builder-tools.md)
-### [Implement channel-specific functionality](v4sdk/bot-builder-channeldata.md)
 ### [.NET](dotnet/TOC.md)
 ### [Node.js](nodejs/TOC.md)
 ## [Debug](debug/TOC.md)
@@ -66,9 +65,4 @@
 ## [.NET SDK v3](/dotnet/api/?view=botbuilder-3.12.2.4)
 ## [Node.js SDK v3](https://docs.botframework.com/en-us/node/builder/chat-reference/modules/_botbuilder_d_.html)
 ## [Entities and activity types](bot-service-activities-entities.md)
-# Related
-## [Web Apps](https://docs.microsoft.com/azure/app-service/)
-## [Functions](https://docs.microsoft.com/azure/azure-functions/)
-## [Cognitive Services](https://docs.microsoft.com/azure/cognitive-services/)
-## [Application Insights](https://docs.microsoft.com/azure/azure-monitor/)
 # [Resources](resources/TOC.md)

articles/bot-service-activities-entities.md

@@ -176,15 +176,21 @@ Activities can be of several different types past the most common **message**. T
 ## message
 
 <!-- Only the last link is different. -->
+
 ::: moniker range="azure-bot-service-3.0"
+
 Your bot will send message activities to communicate information to and receive message activities from users.
-Some messages may simply consist of plain text, while others may contain richer content such as [text to be spoken](v4sdk/bot-builder-howto-send-messages.md#send-a-spoken-message), [suggested actions](v4sdk/bot-builder-howto-add-suggested-actions.md), [media attachments](v4sdk/bot-builder-howto-add-media-attachments.md), [rich cards](v4sdk/bot-builder-howto-add-media-attachments.md#send-a-hero-card),
+Some messages may simply consist of plain text, while others may contain richer content such as text to be spoken, [suggested actions](v4sdk/bot-builder-howto-add-suggested-actions.md), [media attachments](v4sdk/bot-builder-howto-add-media-attachments.md), [rich cards](v4sdk/bot-builder-howto-add-media-attachments.md#send-a-hero-card),
 and [channel-specific data](~/dotnet/bot-builder-dotnet-channeldata.md).
+
 ::: moniker-end
+
 ::: moniker range="azure-bot-service-4.0"
+
 Your bot will send message activities to communicate information to and receive message activities from users.
-Some messages may simply consist of plain text, while others may contain richer content such as [text to be spoken](v4sdk/bot-builder-howto-send-messages.md#send-a-spoken-message), [suggested actions](v4sdk/bot-builder-howto-add-suggested-actions.md), [media attachments](v4sdk/bot-builder-howto-add-media-attachments.md), [rich cards](v4sdk/bot-builder-howto-add-media-attachments.md#send-a-hero-card),
+Some messages may simply consist of plain text, while others may contain richer content such as text to be spoken, [suggested actions](v4sdk/bot-builder-howto-add-suggested-actions.md), [media attachments](v4sdk/bot-builder-howto-add-media-attachments.md), [rich cards](v4sdk/bot-builder-howto-add-media-attachments.md#send-a-hero-card),
 and [channel-specific data](~/v4sdk/bot-builder-channeldata.md).
+
 ::: moniker-end
 
 ## contactRelationUpdate
@@ -245,6 +251,7 @@ A bot receives a typing activity to indicate that the user is typing a response.
 A bot may send a typing activity to indicate to the user that it is working to fulfill a request or compile a response.
 
 ::: moniker range="azure-bot-service-3.0"
+
 ## Additional resources
 
 - <a href="https://docs.botframework.com/en-us/csharp/builder/sdkreference/dc/d2f/class_microsoft_1_1_bot_1_1_connector_1_1_activity.html" target="_blank">Activity class</a>

articles/bot-service-build-download-source-code.md

@@ -33,15 +33,15 @@ If you have a C# bot, update the `appsettings.json` file to include .bot file in
   "botFileSecret": "ukxxxxxxxxxxxs="
 }
 ```
-The `botFilePath` references the name of your bot, simply replace "yourbasicBot.bot" with your own bot name. To obtain the `botFileSecret` key, refer to [Bot File Encryption](https://aka.ms/bot-file-encryption) article on generating a key for your bot.
-
 
 If you have a node.js bot, add a `.env` file with the following entries:
 ```
 botFilePath=yourbasicBot.bot
 botFileSecret=ukxxxxxxxxxxxxs=
 ```
 
+The `botFilePath` references the name of your bot, simply replace "yourbasicBot.bot" with your own bot name. To obtain the `botFileSecret` key, refer to [Bot File Encryption](https://aka.ms/bot-file-encryption) article on generating a key for your bot.
+
 Next, make changes to your sources by either editing existing source files or adding new ones to your project. Test your code using the Emulator. When you are ready to redeploy modified code to the Azure portal, follow the instructions below.
 
 ### Publish code using Visual Studio

articles/manage/TOC.md

@@ -16,7 +16,8 @@
 ## [Slack](../bot-service-channel-connect-slack.md) 
 ## [Telegram](../bot-service-channel-connect-telegram.md) 
 ## [Twilio](../bot-service-channel-connect-twilio.md)
-# [Configure settings](../bot-service-manage-settings.md)
+## [Implement channel-specific functionality](../v4sdk/bot-builder-channeldata.md)
+# [Configure bot settings](../bot-service-manage-settings.md)
 # [Configure speech priming](../bot-service-manage-speech-priming.md)
 # [Register a bot with Azure Bot Service](../bot-service-quickstart-registration.md)
 # [Migrate your bot](../bot-service-migrate-bot.md)

articles/v4sdk/bot-builder-basics.md

@@ -1,5 +1,5 @@
 ---
-title: Bot Activity in the Bot Builder SDK | Microsoft Docs
+title: How bots work | Microsoft Docs
 description: Describes how activity and http work within the Bot Builder SDK.
 keywords: conversation flow, turn, bot conversation, dialogs, prompts, waterfalls, dialog set
 author: johnataylor
@@ -8,11 +8,11 @@ manager: kamrani
 ms.topic: article
 ms.service: bot-service
 ms.subservice: sdk
-ms.date: 11/02/2018
+ms.date: 11/08/2018
 monikerRange: 'azure-bot-service-4.0'
 ---
 
-# Understanding how bots work
+# How bots work
 
 [!INCLUDE [pre-release-label](../includes/pre-release-label.md)]
 
@@ -50,38 +50,13 @@ Let's drill into the previous diagram with a focus on the arrival of a message a
 
 In the example above, the bot replied to the message activity with another message activity containing the same text message. Processing starts with the HTTP POST request, with the activity information carried as a JSON payload, arriving at the web server. In C# this will typically be an ASP.NET project, in a JavaScript Node.js project this is likely to be one of the popular frameworks such as Express or Restify.
 
-The *adapter*, an integrated component of the SDK, serves as the conductor of the framework. The service uses the activity information to create an activity object, and then calls the adapter's *process activity* method while passing in the activity object and authentication information (this call is wrapped inside the libraries for C#, but you will see it in JavaScript). Upon receiving the activity, the adapter creates a turn context object and calls the [middleware](#middleware). Processing continues to the bot logic after middleware, the pipeline completes, and the adapter disposes of the turn context object.
-
-The bot's *turn handler*, which makes up most of the application logic, takes a turn context as its argument. The turn handler will typically process the inbound activity’s content and generate one or more activities in response, sending these out using the turn context's *send activity* method. Calling the send activity method will send an activity to the user's channel, unless processing otherwise gets interrupted. The activity will pass through any registered [event handlers](#response-event-handlers) before being sent to the channel.
-
-## Middleware
-
-Middleware is a linear set of components that are each added and executed in order, giving each a chance to operate on the activity both before and after the bot's turn handler and have access to the turn context for that activity. Unless middleware [short circuited](~/v4sdk/bot-builder-concept-middleware.md#short-circuiting), the final stage of the middleware pipeline is a callback to invoke the turn handler of the bot, before returning up the stack. For more in depth information about middleware, see the [middleware topic](~/v4sdk/bot-builder-concept-middleware.md).
-
-## Generating responses
-
-The turn context provides activity response methods to allow code to respond to an activity:
-
-* The _send activity_ and _send activities_ methods send one or more activities to the conversation.
-* If supported by the channel, the _update activity_ method updates an activity within the conversation.
-* If supported by the channel, the _delete activity_ method removes an activity from the conversation.
-
-Each response method runs in an asynchronous process. When it is called, the activity response method clones the associated [event handler](#response-event-handlers) list before starting to call the handlers, which means it will contain every handler added up to this point but will not contain anything added after the process starts.
-
-This also means the order of your responses for independent activity calls is not guaranteed, particularly when one task is more complex than another. If your bot can generate multiple responses to an incoming activity, make sure that they make sense in whatever order they are received by the user. The only exception to this is the *send activities* method, which allows you to send an ordered set of activities.
+The *adapter*, an integrated component of the SDK, is the core of the SDK runtime. The activity is carried as JSON in the HTTP POST body. This JSON is deserialized to create the Activity object that is then handed to the adapter with a call to *process activity* method. On receiving the activity, the adapter creates a *turn context* and calls the middleware. The name *turn context* follows from the use of the word “turn” to describe all the processing associated with the arrival of an activity. The turn context is one of the most important abstractions in the SDK, not only does it carry the inbound activity to all the middleware components and the application logic, but it also provides the mechanism for the middleware components and the application logic to send outbound activities. The turn context provides _send, update, and delete activity_ response methods to respond to an activity. Each response method runs in an asynchronous process. 
 
 [!INCLUDE [alert-await-send-activity](../includes/alert-await-send-activity.md)]
 
-## Response event handlers
-
-In addition to the application and middleware logic, response handlers (also sometimes referred to as event handlers, or activity event handlers) can be added to the context object. These handlers are called when the associated [response](#generating-responses) happens on the current context object, before executing the actual response. These handlers are useful when you know you'll want to do something, either before or after the actual event, for every activity of that type for the rest of the current response.
 
-> [!WARNING]
-> Be careful to not call an activity response method from within it's respective response event handler, for example, calling the send activity method from within an _on send activity_ handler. Doing so can generate an infinite loop.
-
-Remember, each new activity gets a new thread to execute on. When the thread to process the activity is created, the list of handlers for that activity is copied to that new thread. No handlers added after that point will be executed for that specific activity event.
-
-The handlers registered on a context object are handled very similarly to how the adapter manages the manages the [middleware pipeline](~/v4sdk/bot-builder-concept-middleware.md#the-bot-middleware-pipeline). Namely, handlers get called in the order they're added, and calling the _next_ delegate passes control to the next registered event handler. If a handler doesn’t call the next delegate, none of the subsequent event handlers are called, the event [short circuits](~/v4sdk/bot-builder-concept-middleware.md#short-circuiting), and the adapter does not send the response to the channel.
+## Middleware
+Middleware is much like any other messaging middleware, comprising a linear set of components that are each executed in order, giving each a chance to operate on the activity. The final stage of the middleware pipeline is a callback to invoke the turn handler (`OnTurnAsync` in C# and `onTurn` in JS) function on the bot class the application has registered with the adapter. The turn handler takes a turn context as its argument, typically the application logic running inside the turn handler function will process the inbound activity’s content and generate one or more activities in response, sending these out using the *send activity* function on the turn context. Calling *send activity* on the turn context will cause the middleware components to be invoked on the outbound activities. Middleware components execute before and after the bot’s turn handler function. The execution is inherently nested and, as such, sometimes referred to being like a Russian Doll. For more in depth information about middleware, see the [middleware topic](~/v4sdk/bot-builder-concept-middleware.md).
 
 ## Bot structure
 

articles/v4sdk/bot-builder-concept-dialog.md

@@ -20,6 +20,8 @@ Managing conversations through the concept of a Dialog is central to the SDK. Di
 
 At runtime, Dialog instances are arranged in a stack. The Dialog on the top of the stack is referred to as the ActiveDialog. The current active Dialog processes the inbound Activity. Between each turn of the conversation (which is not time-bound and may span over several days), the stack is persisted. 
 
+## Dialog Lifecycle
+
 A Dialog implements three main functions:
 - BeginDialog
 - ContinueDialog