Tutorial: Create and deploy a basic bot

Note

This topic is for the latest release of the SDK (v4). You can find content for the older version of the SDK (v3) here.

This tutorial walks you through creating a basic bot with the Bot Framework SDK, and deploying it to Azure. If you've already created a basic bot and have it running locally, skip ahead to the Deploy your bot section.

In this tutorial, you learn how to:

  • Create a basic Echo bot
  • Run and interact with it locally
  • Publish your bot

If you don’t have an Azure subscription, create a free account before you begin.

Prerequisites

  • Visual Studio 2017
  • Bot Framework SDK v4 template for C#
  • Bot Framework Emulator
  • Knowledge of ASP.Net Core and asynchronous programming in C#

Create a bot

Install BotBuilderVSIX.vsix template that you downloaded in the prerequisites section.

In Visual Studio, create a new bot project using the Bot Framework Echo Bot V4 template.

Visual Studio project

Tip

If needed, change the project build type to .Net Core 2.1. Also if needed, update the Microsoft.Bot.Builder NuGet packages.

Thanks to the template, your project contains all of the code that's necessary to create the bot in this quickstart. You won't actually need to write any additional code.

Start your bot in Visual Studio

When you click the run button, Visual Studio will build the application, deploy it to localhost, and launch the web browser to display the application's default.htm page. At this point, your bot is running locally.

Start the emulator and connect your bot

Next, start the emulator and then connect to your bot in the emulator:

  1. Click the Open Bot link in the emulator "Welcome" tab.
  2. Select the .bot file located in the directory where you created the Visual Studio solution.

Interact with your bot

Send a message to your bot, and the bot will respond back with a message.

Emulator running

Note

If you see that the message can not be sent, you might need to restart your machine as ngrok didn't get the needed privileges on your system yet (only needs to be done one time).

Deploy your bot

Now, deploy your bot to Azure.

Prerequisites

With msbot 4.3.2 and later, you need Azure CLI version 2.0.54 or later. If you installed the botservice extension, remove it with this command.

az extension remove --name botservice

Login to Azure CLI and set your subscription

You've already created and tested a bot locally, and now you want to deploy it to Azure.

Open a command prompt to log in to the Azure portal.

az login

A browser window will open, allowing you to sign in.

Set the subscription

Set the default subscription to use.

az account set --subscription "<azure-subscription>"

If you are not sure which subscription to use for deploying the bot, you can view the list of subscriptions for your account by using az account list command.

Navigate to the bot folder.

cd <local-bot-folder>

Create a Web App Bot

If you don't already have a resource group to which to publish your bot, create one:

az group create --name <resource-group-name> --location <geographic-location> --verbose
Option Description
--name A unique name for the resource group. DO NOT include spaces or underscores in the name.
--location Geographic location used to create the resource group. For example, eastus, westus, westus2, and so on. Use az account list-locations for a list of locations.

Then, create the bot resource into which you will publish your bot. This will provision the necessary resources in Azure and create a bot web app, which you will overwrite with your local bot.

Note

This isn't the only way to achieve this, but it tends to be the easiest way to create all the parts you will need for deploying a functioning bot.

Before proceeding, read the instructions that apply to you based on the type of email account you use to log in to Azure.

MSA email account

If you are using an MSA email account, you will need to create the app ID and app password on the Application Registration Portal to use with az bot create command.

  1. Go to the Application Registration Portal.
  2. Click on Add an app to register your application, create Application Id, and Generate New Password. If you already have an application and password but don't remember the password, you will have to generate a new password in the Application secrets section.
  3. Save both application ID and the new password you just generated, so you that can use them with the az bot create command.
az bot create --kind webapp --name <bot-resource-name> --location <geographic-location> --version v4 --lang <language> --verbose --resource-group <resource-group-name> --appid "<application-id>" --password "<application-password>" --verbose
Option Description
--name A unique name that is used to deploy the bot in Azure. It could be the same name as your local bot. DO NOT include spaces or underscores in the name.
--location Geographic location used to create the bot service resources. For example, eastus, westus, westus2, and so on.
--lang The language to use to create the bot: Csharp, or Node; default is Csharp.
--resource-group Name of resource group in which to create the bot. You can configure the default group using az configure --defaults group=<name>.
--appid The Microsoft account ID (MSA ID) to be used with the bot.
--password The Microsoft account (MSA) password for the bot.

Business or school account

az bot create --kind webapp --name <bot-resource-name> --location <geographic-location> --version v4 --lang <language> --verbose --resource-group <resource-group-name>
Option Description
--name A unique name that is used to deploy the bot in Azure. It could be the same name as your local bot. DO NOT include spaces or underscores in the name.
--location Geographic location used to create the bot service resources. For example, eastus, westus, westus2, and so on.
--lang The language to use to create the bot: Csharp, or Node; default is Csharp.
--resource-group Name of resource group in which to create the bot. You can configure the default group using az configure --defaults group=<name>.

Download the bot from Azure

Next, download the bot you just created.

Use a temporary directory outside of your current project directory.

This command will create a subdirectory under the save-path; however, the specified path must already exist.

az bot download --name <bot-resource-name> --resource-group <resource-group-name> --save-path "<path>"
Option Description
--name The name of the bot in Azure.
--resource-group Name of resource group the bot is in.
--save-path An existing directory to download bot code to.

Decrypt the downloaded .bot file and use in your project

The sensitive information in the .bot file is encrypted, so let's decrypt it so we can use it easily.

First, navigate to the dowloaded bot directory.

Get the encryption key.

  1. Log into the Azure portal.
  2. Open the Web App Bot resource for your bot.
  3. Open the bot's Application Settings.
  4. In the Application Settings window, scroll down to the Application settings.
  5. Locate the botFileSecret and copy its value.

Decrypt the .bot file.

msbot secret --bot <name-of-bot-file> --secret "<bot-file-secret>" --clear
Option Description
--bot The relative path to the downloaded .bot file.
--secret The encryption key.

Copy the decrypted .bot file to the directory that contains your local bot project, update your bot to use this new .bot file, and remove your old .bot file.

In appsettings.json, update the botFilePath property to point to the new .bot file you've added to your local directory.

Once your bot has been updated, delete the temporary directory of the downloaded bot.

Test your bot locally

At this point, your bot should work the same way it did with the old .bot file. Make sure that it works as expected with the new .bot file.

You should now see a Production endpoint in the emulator. If you don't, you're probably still using the old .bot file.

Publish your bot to Azure

Publish your local bot to Azure. This step might take a while.

az bot publish --name <bot-resource-name> --proj-name "<project-file-name>" --resource-group <resource-group-name> --code-dir <directory-path> --verbose --version v4
Option Description
--name The resource name of the bot in Azure.
--proj-name For C#, use the startup project file name (without the .csproj) that needs to be published. For example: EnterpriseBot. For Node.js, use the main entry point for the bot. For example, index.js.
--resource-group Name of resource group.
--code-dir The directory to upload bot code from.

Once this completes with a "Deployment successful!" message, your bot is deployed in Azure.

Clear the encryption key setting.

  1. Log into the Azure portal.
  2. Open the Web App Bot resource for your bot.
  3. Open the bot's Application Settings.
  4. In the Application Settings window, scroll down to the Application settings.
  5. Locate the botFileSecret and delete it.
  6. Click Save at the top of this page to save your changes.

Now, you should be able to test your bot in Webchat.

Additional resources

When you deploy a bot, typically these resources are created in the Azure portal:

Resources Description
Web App Bot An Azure Bot Service bot that is deployed to an Azure App Service.
App Service Enables you to build and host web applications.
App Service plan Defines a set of compute resources for a web app to run.
Application Insights Provides tools for collecting and analyzing telemetry.
Storage account Provides cloud storage that is highly available, secure, durable, scalable, and redundant.

To see documentation on az bot commands, see the reference topic.

If you are unfamiliar with Azure resource group, see this terminology topic.

Next steps