[Spec] Samples for Bot Builder V4 SDK

[vishwacsena]

Goals

• Make it easy for developers to learn basic bot concepts
• Provide a numbering scheme for samples so developers can start simple and layer in sophistication
• Samples targeted at scenarios rather than technology involved
• Consistent set of samples across supported languages
• Samples are also consistently used in the docs topics for continuity and are developed by the documentation team, reviewed by the feature team.
• Each sample MUST include
  • README with steps to run the sample, concepts involved and links to additional reading (docs)
  • deep link to V4 Emulator, include a .bot file as well as point to relevant tools (UI based or CLI) as appropriate
  • .chat files as appropriate that provide scenario overview and demonstrates how to construct mock conversations for the specific scenario
  • .lu files as appropriate
  • Include source JSON model files for LUIS, QnA, Dispatch where applicable
  • Include LUISGen strong typed LUIS class for LUIS samples
  • Any required build scripts for sample to work locally
  • Well defined naming convention for setting, service endpoint, and secrets in setting files (.bot, app.json, etc.)
  • Deploy to Azure button including all resources (similar to V3 samples)
• Each sample SHOULD include
  • Welcome message (conversation update activity)
  • Flow control and interruptions (help, cancel, detecting and handling interruptions)
• All samples are built and deployable on local dev env (Emulator) and Azure (WebChat)
  • Samples (and docs) should add channel specific notes (if applicable). e.g. document list of supported channels for Adaptive cards sample etc.
• JS and TS samples should be in separate folders

Samples structure - C#

| - <sampleName>.bot                        // bot file for this sample
| - README.md                               // Markdown readme file that includes steps to run this sample 
                                            (including steps to create and configure required services), 
                                            overview of concepts covered in this sample + links to 
                                            additional topics to read
| - Program.cs                              // Default program.cs
| - Startup.cs                              // Default startup.cs – configuration builder + middlewares
| - appsettings.json                        // Has bot configuration information

| - Dialogs    
    | - MainDialog
        | - MainDialog.cs                   // Main router/ dispatcher for the bot
        | - <botName_state>.cs              // state definitions that are shared across dialogs/ components are here
        | - Resources
            | - <scenario>.lu               // LU file that has intents that apply globally - e.g. help/ cancel etc.
            | - <scenario_card>.cshtml      // Cards that are shared across dialogs.                 
  | - <scenario name>           
        | - <scenario>.cs                   // Dialog definition for this scenario
        | - <scenario_state>.cs             // State object definitions for this scenario
        | - Resources
              | - <scenario>.lu             // LU file with intents + entities/ QnA pairs for this scenario
              | - <scenario_card>.cshtml    // cards for this particular scenario – template file for cards
              | - <scenario>.chat           // Chat file for this specific scenario; shows happy path or variations.
| - CognitiveModels
    | - <bot_name>.luis                     // LUIS model file for this sample
    | - <bot_name>.qna                      // QnA Maker JSON model file
    | - <bot_name>.dispatch                 // Dispatch JSON model file
| - DeploymentScripts
    | - DEPLOYMENT.md                       // Readme for deployment scripts.   
    | - azuredeploy.json                    // Azure deployment ARM template

Samples structure - JS

| - <sample-name>.bot                       // bot file for this sample
| - README.md                               // Markdown readme file that includes steps to run this sample 
                                            (including steps to create and configure required services), 
                                            overview of concepts covered in this sample + links to 
                                            additional topics to read
| - index.js                                // Default app.js - startup, middlewares
| - .env                                    // Has bot configuration information
| - dialogs 
    | - mainDialog
        | - index.js                        // Main router/ dispatcher for the bot
        | - <bot-name-state>.js             // state definitions that are shared across dialogs/ components are here
        | - resources
            | - <scenario>.lu               // LU file that has intents that apply globally - e.g. help/ cancel etc.                    
  | - <scenario-name>           
        | - index.js                        // Dialog definition for this scenario
        | - <scenario-state>.js             // State object definitions for this scenario
        | - resources
              | - <scenario>.lu             // LU file with intents + entities/ QnA pairs for this scenario
              | - <scenario-card>.json      // cards for this particular scenario – template file for cards
              | - <scenario>.chat           // Chat file for this specific scenario; shows happy path or variations.
| - cognitiveModels
    | - <bot-name>.luis                     // LUIS model file for this sample
    | - <bot-name>.qna                      // QnA Maker JSON model file
    | - <bot-name>.dispatch                 // Dispatch JSON model file
| - deploymentScripts
    | - DEPLOYMENT.md                       // Readme for deployment scripts.   
    | - azuredeploy.json                    // Azure deployment ARM template

README.md template

<INSERT AT MOST ONE PARAGRAPH DESCRIPTION OF WHAT THIS SAMPLE DOES> 

# Concepts introduced in this sample
<DESCRIPTION OF THE CONCEPTS>


# To try this sample
-	<STEPS TO CLONE REPO AND GET SETUP>
## Prerequisites
-	<REQUIRED TOOLS, VERSIONS>
-	<STEPS TO GET SET UP WITH THE SAMPLE. E.g. RUN AN INCLUDED SCRIPT OR MANUALLY DO SOMETHING ETC>

NOTE: <ANY NOTES ABOUT THE PREREQUISITES OR ALTERNATE THINGS TO CONSIDER TO GET SET UP>

## Visual studio
-	<STEPS TO RUN THIS SAMPLE FROM VISUAL STUDIO>

## Visual studio code
-	<STEPS TO RUN THIS SAMPLE FROM VISUAL STUDIO CODE>

## Testing the bot using Bot Framework Emulator
[Microsoft Bot Framework Emulator](https://github.com/microsoft/botframework-emulator) is a desktop application that allows bot developers to test and debug their bots on localhost or running remotely through a tunnel.

- Install the Bot Framework emulator from [here](https://github.com/Microsoft/BotFramework-Emulator/releases)

## Connect to bot using Bot Framework Emulator **V4**
- Launch Bot Framework Emulator
- File -> Open bot and navigate to samples\8.AspNetCore-LUIS-Bot folder
- Select AspNetCore-LUIS-Bot.bot file

# Further reading
-	<LINKS TO ADDITIONAL READING>

Samples repo structure, naming conventions

• All samples will live under the BotBuilder-Samples repository, master branch.
• Language/ platform specific samples go under respective folders – ‘dotnet’/ ‘JS’/ ‘Java’/ ‘Python’
• Samples should use published packages, available on NuGet or npmjs
• Each sample sits in its own folder
• Each sample folder is named as “<#>. <KEY SCENARIO INTRODUCED BY THE SAMPLE>”
• Each solution/ project is named as “<KEY SCENARIO INTRODUCED BY THE SAMPLE>”
• C# - each sample has its own solution file

Samples list

Sample Name	Description	.NET CORE	.NET Web API	JS (es6)	TS
1.Console-EchoBot	Introduces the concept of adapter and demonstrates a simple echo bot on console adapter and how to send a reply and access the incoming the incoming message. Doc topic from readme lists other adapter types	✔️		✔️
1.a. Browser-EchoBot	Introduces browser adapter			✔️
2.EchoBot-With-Counter	Demonstrates how to use state. Shows commented out code for all natively supported storage providers. Storage providers should include InMemory, CosmosDB and Blob storage. Default bot template for ABS, VSIX, Generators and dotnet new template	✔️	✔️	✔️	✔️
3.Welcome-User	Introduces activity types and providing a welcome message on conversation update activity. This should be the “who to” sample and tie back to a Concept doc.	✔️		✔️
4.Simple-Prompt-Bot	Demonstrates prompt pattern by prompting user for a property. Introduces user state .vs. conversation state. Ask for name and prints back those information. Uses sequence dialogs if available or default option is to use waterfall dialogs	✔️		✔️
5.MultiTurn-Prompts-Bot	Demonstrates more complex pattern by prompting user for multiple properties. Ask for name, age and prints back that information. Uses sequence dialogs if available or default option is to use waterfall dialogs.	✔️		✔️
6.Using-Cards	Introduces all card types including thumbnail, audio, media etc. Builds on Welcoming user + multi-prompt bot by presenting a card with buttons in welcome message that route to appropriate dialog.	✔️		✔️
7.Using-Adaptive-Cards	Introduces adaptive cards - demonstrates how the multi-turn dialog can be augmented to also use a card to get user input for name and age.	✔️		✔️
8.Suggested-Actions	Demonstrates how to use suggested actions	✔️		✔️
9.Message-Routing	Demonstrates the main dialog or root dispatcher paradigm. Needs to show how to handle interruptions like cancel, help, start over. Tie to conceptual documentation and best practice/ patterns recommendations.	✔️		✔️
10.Prompt-Validations	Demonstrates how to take advantage of different prompt types and prompt validators. In this example, we will expand the multi-turn prompt sample to accept name, age, date of birth, favorite color.Name uses text prompt with 1min character and 50 max character limitation; Age uses number prompt with valid age between 1 - 99; Date of birth uses date time prompt with valid date of birth between 8/24/1918 through 8/24/2018; Favorite color uses choice prompt with red, blue, green, .. as choices	✔️		✔️
11.QnAMaker	Demonstrates how to use QnA Maker to have simple single-turn conversations	✔️	✔️	✔️	✔️
12.NLP-With-LUIS	Demonstrates how to use LUIS to understand natural language	✔️	✔️	✔️	✔️
13.Basic-Bot-Template	Basic bot template that puts together cards, NLP (LUIS)	✔️	✔️	✔️	✔️
14.NLP-With-Dispatch	Demonstrates how dispatch should be used E2E	✔️		✔️
15.Handling-No-Match	Provides guidance on how to handle no-match. Its appropriate to have this covered after LUIS and QnA maker to show post NLP step as well.	✔️		✔️
16.Handling-Atachments	Demonstrates how to listen for/handle user provided attachments	✔️		✔️
17.Proactive-Messages	Demonstrates how to send proactive messages	✔️		✔️
18.Multi-Lingual-Bot	Using translate middleware to support a multi-lingual bot	✔️		✔️
19.Bot-uthentication	Bot that demonstrates how to integration with auth providers	✔️		✔️
20.Handling-End-Of-Conversation	Bot that demonstrates how to handle end of conversation events	✔️		✔️
21.Custom-Dialogs	Demonstrates different ways to model conversations. Waterfall .vs. using your own dialog management	✔️		✔️
50.Contoso-Café-Bot	A complete E2E Cafe bot that has all capabilities and includes best practices	✔️		✔️
51.Enterprise-Bot-Template	Bot that includes scaffolding and references to commonly used services for an enterprise scale bot. Also used as the enterprise bot template	✔️		✔️

Advanced topics

Additional advanced topics to consider based on feedback

• Create your own custom
  • adapter
  • context object
  • middleware
  • state provider
  • clients
  • events that clients can listen for

Feedback welcome.

[yochay]

@vishwacsena , there are minor copy & paste error in the sample structure js folder/files description. update the .CS ref to JavaScript

| - Program.js // Default program.cs
| - Startup.js // Default startup.cs – configuration builder + middlewares

[jamesemann]

These look great! I missed these initially because I was looking at botbuilder-dotnet/master, mostly because I can't follow instructions but just an FYI as other people may do the same

[ksivamuthu]

Looks great !!! Some of the suggestions I've is:

1. File names of JS/TS. (kebab case, lowercase letters)
2. index.js as the start script (instead of program.js)
3. Use transcripts directory to save the transcripts of example in the repo. .chat file can also be in this directory where the mock conversation is designed.

Question: Can we integrate Adaptivecard.io Visualizer into Bot Framework Emulator or VSCode to design cards and test it how it looks in different channels?

[vishwacsena]

@yochay - Fixed.
@ksivamuthu - fixed 1 & 2. For suggestion 3, I believe the .chat files should live under the individual scenario. Transcripts make sense to live at the root level.

[ksivamuthu]

@vishwacsena Transcripts at root level makes sense. 👍

[christopheranderson]

VS Code should be the preferred editor for JS bots. Most folks don't use NTVS, as cool as it is.

For both .NET (core at least) and Node.js, you should have a sample on how to run from CLI. Ideally, for node.js, it would work with just npm i & npm start - as little other config as possible.

I'd encourage having at least 1 or 2 TypeScript samples for Node.js as well. It's really helpful to have a sample with .tsconfig/etc. already set up to be able to go quickly. You can just ts-node in the package.json for the npm run (aka: "start": "ts-node app.ts")

This assumes standalone servers for hosting the samples, but have you considered showing samples for FaaS? (Azure Functions, AWS Lambda, etc.) (I don't think this is a requirement, but worth thinking about, especially if you're doing deploy to azure samples) (FWIW, I think you can make the Node.js samples work in Azure Functions and standalone server with no code changes. I can help if needed...)

[yochay]

@christopheranderson we document steps required for developers success using popular tools like VS Code as well as common Microsoft tools like VS.

Most current JS samples, for example Echo-Bot work with npm install + npm start. We will take a not to make sure JS samples continue to have that functionality (they have to...) Good point regarding TS, which should be part of the deliverables to make sure anyone can run the samples using the existing scripts.

The primary goal of these samples is to enable developers to experiment and learn how to build bots successfully. We want the developer to get a bot running locally as quickly as possible. Therefore we aim for a local run and test scenarios using the emulator. All samples include provisioning of resources in Azure and deployment of the bot.

@christopheranderson - We will surely take you on your word to help run JS bots on Azure Functions :)

[yochay]

@vishwacsena do we need to add a 'deployment' folder for resource generation and deployment scripts?

[vishwacsena]

@yochay - fixed. Also updated samples structure based on feedback.

[yochay]

@vishwacsena as I read through these, should we identify which samples build on top of previous.

For example, sample #3 should use sample #2 as the baseline, sample 4 should use 3 and so on... not all samples make sense to combine, but for those we believe do compose, let's identify that in advance (if we all agree to the above)

[sgellock]

@vishwachsena I changed the casing on the the README.MD markdown files to be lowercase. This aligns with standard norms.

[johnataylor]

Referring to #855

Added a branch https://github.com/Microsoft/botbuilder-dotnet/tree/johtaylo/translation-sample
that contains the code from the main solution. This is not yet a working sample, just a copy of the code.

[vishwacsena]

Updated to move main dialog under dialogs. renamed app.js to index.js

[chintan3100]

Please help me to find code for 19.Bot-Authentication

[sgellock]

samples are in BotBuilder-Samples v4 branch until merged into master and are following the guidelines outlined above