Bot Framework Code-First Options

Overview

Bot Framework v4 has a number of options to get a bot up and running quickly.  This article will walk through these options, provide a bit of background into why we’ve done the things we’ve done, and show how to get a bot up and running on your machine.  Said another way, this article intends to give the “what”, “why”, and “how” of the team’s efforts around code-first / local-machine bot development.

Using Core Tenants to Guide Us

One of the core tenants we talk about in our team is that a good SDK should always “meet the developer where they are“.  What we mean by this is the design and implementation of our  SDK (and supporting tools) should:

  • Embrace the developer’s programming language of choice
  • Embrace the developer’s programming editor of choice
  • Embrace the developer’s operating system of choice

As we in the Bot Framework SDK Team think about these dimensions, we’ve made programming language investments in C#, JavaScript/TypeScript, with some work (though we need to do much more) in Java and Python.  For programming editors, thus far we’ve focused on the Microsoft IDE experience using Visual Studio and the command-line/minimal editor experiences such as VSCode and its lineage (Atom, Textmate, your favorite editor from college).  And lastly, we want our stuff to work equally well on Windows, macOS, and the major Linux distro’s.

Using the “meet the developer where they are” tenant as a guide, we’ve made investments in three specific technology options to aid developers in getting a bot  up and running quickly.  The technology options we currently support are meant to meet the developer where they are and to fit naturally into the development workflows one would expect when using these toolchains.  With that in mind, let’s take a look at the options and why we chose each of them.

How We Segment Our “Getting Started” Deliverables

As we look at toolchain usage, we currently see three distinct profiles.  They are:

  • JavaScript/TypeScript, VSCode,  developed on macOS, Windows, or Linux
  • C#, Visual Studio, developed on Windows
  • C#, VSCode, using .NET Core, developed on macOS, Windows, or Linux

Each of our toolchain options can generate 3 different bot templates.  The bot template options are:

  1. Echo Bot – A good template if you want a little more than “Hello World!”, but not much more. This template handles the very basics of sending messages to a bot, and having the bot process the messages by repeating them back to the user. This template produces a bot that simply “echos” back to the user anything the user says to the bot.
  2. Core Bot – Our most advanced template, the Core Bot template provides 6 core features every bot is likely to have. This template covers the core features of a Conversational-AI bot using LUIS.
  3. Empty Bot – A good template if you are familiar with Bot Framework v4, and simple want a basic skeleton project. Also a good option if you want to take sample code from the documentation and paste it into a minimal bot in order to learn.

If the above summary doesn’t provide enough information to help you decide which bot template is the right one for you to get started, a more in-depth explanation of the features found in each bot templates can be found here.

Let’s move on and take a look at the different toolchain profiles we support, how to install generators for a given toolchain, and how to generate a new bot template.

Toolchain Profiles

JavaScript/TypeScript Developer Using VSCode

For the JavaScript/TypeScript developer we predominantly see a VSCode, macOS, command line augmented toolchain.  We’ve modeled our getting started approach after prior art such as create-react-app or create-react-native-app.  You start on the command line, run some kind of code generator that produces a runnable application, open that generated code in VSCode, and away you go.  To support the developer who uses this toolchain we opted to use Yeoman to build our code generator.  Yeoman is purpose-built for this problem and has strong community support.  It’s powerful enough that we were able to deliver the flexibility we wanted.  It was easy to use, and because it’s npm module based, distribution and cross-platform support are built in.  So let’s take a look at our Yeoman code generator and what it can do to help you the JavaScript/TypeScript developer get started quickly .

Installing Yeoman and Bot Framework Generator
# install Yeoman
npm install -g yeoman
# install bot framework generator
npm install -g generator-botbuilder
Generating a New Bot

With Yeoman and the Bot Framework generator installed, we can now generate a new bot.  Launch the generator and it will prompt you for what it needs to generate a new bot.  Here is how to launch the Yeoman generator:

# generate a new EchoBot interactively
yo botbuilder

For more information on the Bot Framework Yeoman generator and its capabilities, refer to additional documentation found here.

Running Your New Bot

Now that a new bot has been generated, here are the steps required to run the new bot.

 
# change into the generated folder (same name you gave your bot)
cd <_name_you_gave_to_your_bot_>

# install modules
npm install

# run the bot
npm start
Testing Your New Bot

The easiest way to test your new bot is to use the Bot Framework Emulator.  Our Yeoman generated bots create a README.md file in the bot’s root folder.  This file will provide detailed instructions on how to:

  • Run your bot locally (we’ve shown how to above)
  • Test your bot using Bot Framework Emulator
  • Optionally, deploy your bot to Azure

 

C#, VSCode, using .NET Core

Increasingly we are seeing multi-platform adoption of C# and .NET Core.  Some of this adoption is driven by a desire to have a strongly typed language with multi-platform support, but the desire to use traditional typed-language offerings isn’t there.  This toolchain is very similar to the JavaScript/VSCode toolchain discussed above.  Developers expect to use command line tools to get started, VSCode or similar to edit their code.  To support this developer profile we’ve implemented a set of .NET Templates.  In order to use these templates to generate a new bot, you need to have the .NET Core SDK installed.  Once the .NET Core SDK is installed, you’ll then use the dotnet CLI to install one or more of the Bot Framework templates, and then use one of the templates to generate a new bot.  I’ll cover the details of this next.

To use the .NET Core Templates, the following steps assume you have .NET Core SDK 2.2 installed.  Refer to the .NET Core SDK for instructions to install and setup .NET Core.  Assuming .NET Core is installed, here is how to install the Bot Framework templates.  The example that follows installs all three templates.  You don’t have to install all three templates if you don’t want to.  You can opt to install only those templates you intend to use.

Installing .NET Templates
# install .NET Template for Echo Bot
dotnet new -i Microsoft.Bot.Framework.CSharp.EchoBot

# install .NET Template for Core Bot
dotnet new -i Microsoft.Bot.Framework.CSharp.CoreBot

# install .NET Template for Empty Bot
dotnet new -i Microsoft.Bot.Framework.CSharp.EmptyBot
Generating a New Bot

With one or more of the .NET Core Templates installed, we can now generate a new bot.  Here is an example of how to generate a new .NET Core bot using the EchoBot template:

# generate a new bot using the EchoBot template
dotnet new echobot -n MyEchoBot

For more information on the .NET Template capabilities, refer to additional documentation found here.

Running Your New Bot
 
# change into the generated folder (same name you gave your bot)
cd MyEchoBot

# run the bot
dotnet run
Testing Your New Bot

The easiest way to test your new bot is to use the Bot Framework Emulator.  Our .NET Core generated bots create a README.md file that will provide details instructions on how to:

  • Run your bot locally (we’ve done that above)
  • Test your bot using Bot Framework Emulator
  • Optionally, deploy your bot to Azure

 

C# Developer Using Visual Studio On Windows

For the C# developer the dominate toolchain is Visual Studio running on Windows.  As such, we provide a Visual Studio Extension (VSIX) that will provide new bot generation functionality from within the IDE.  To generate a new bot, you first need to install the Bot Builder V4 SDK Template for Visual Studio. To do this:

  1. Navigate to the Visual Studio Marketplace.
  2. Search for botbuilder.
  3. Click on the Bot Builder V4 SDK Template for Visual Studio to install the extension.

Bot Framework Extension for Visual Studio

    1. Bot Framework Extension for Visual Studio

With the extension installed, you can now launch the extension and create a new bot.  This flow differs depending on whether you are using Visual Studio 2017 or Visual Studio 2019.  Here are screen shots from each version.

Visual Studio 2017

Bot Framework Extension - Visual Studio 2017
Visual Studio 2017
Bot Framework Extension - Visual Studio 2017
Visual Studio 2019
Testing Your New Bot

The easiest way to test your new bot is to use the Bot Framework Emulator.  Our Visual Studio generated bots create a README.md file that will provide details about your new bot.

 

What About Visual Studio On macOS

The three profiles I’ve covered in this article are the dominate surface area for the developer toolchains we are seeing at this time.  So what if you like running Visual Studio on your Mac?  Well, for now, we don’t have work scheduled to build a Visual Studio for Mac extension.  Though the product names are the same, the extension mechanisms are different between VS on Windows and VS on Mac.  That said, Yeoman and .NET Core Templates are a solution that you can use if you are a macOS fan.  Though not integrated directly into the IDE experience, you can get up and running by leveraging the command line options we’re providing for other profiles.  Once you’ve used one of our command line tooling option to generate a new bot, you can return to Visual Studio for Mac and work as you normally would.  If support grows for a VS on Mac extension, we’ll consider adding this as an additional option.

Summary

This concludes a walkthrough of the different choices you have to get a bot up and running quickly with Bot Framework.  Our intent is to provide options that compliment your toolchain and provide bot templates of varying degrees of sophistication.   Regardless of whether your language of choice is C#, JavaScript, or TypeScript, whether your editor of choice is Visual Studio, VSCode or similar minimal editor option, or whether you like developing on Windows, macOS, or Linux, we want to make getting up and running as quickly and easily as possible.  It’s our goal to make bot development an easy and approachable process.