Tutorial: Create and deploy a basic bot

APPLIES TO: SDK v4

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

Templates

Visual Studio templates

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

Note

Both .NET Core 2.1 and .NET Core 3.1 versions of the C# VSIX templates are available in Visual Studio. When creating new bots in Visual Studio 2019, you should use the .NET Core 3.1 templates. The current bot samples use .NET Core 3.1 templates. You can find the samples that use .NET Core 2.1 templates in the 4.7-archive branch of the BotBuilder-Samples repository. For information about deploying .NET Core 3.1 bots to Azure, see Deploy your bot.

Build and run the bot

Build and run the bot in Visual Studio

In Visual Studio, create a new bot project using the Echo Bot (Bot Framework v4 - .NET Core 3.1) template. Choose AI Bots from the project types to show only bot templates.

Visual Studio create a new project dialog

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

Start the project. This 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 on port 3978.

Note

If you create a Core bot, you'll need a LUIS language model. (You can create a language model at luis.ai). After creating the model, update the configuration file.

Start the Emulator and connect to your bot

  1. Start the Bot Framework Emulator.

  2. Click Open Bot on the Emulator's Welcome tab.

  3. Enter your bot's URL, which is the URL of the local port, with /api/messages added to the path, typically http://localhost:3978/api/messages.

    open a bot screen

  4. Then click Connect.

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

    Emulator running

Deploy your bot

In this article we will show you how to deploy a basic bot to Azure. We will explain how to prepare your bot for deployment, deploy your bot to Azure, and test your bot in Web Chat. It would be useful to read this article before following the steps, so that you fully understand what is involved in deploying a bot.

Important

Make sure you are using the latest version of the Azure CLI. If you are using an Azure CLI version older than 2.2.0, you will encounter errors of CLI commands deprecation. Also, do not mix Azure CLI deployment shown in this article with Azure portal deployment.

Prerequisites

Prepare for deployment

Tip

This procedure uses a ZIP file to deploy your bot. In C#, this may fail if the solution configuration at build is set to Debug. In Visual Studio, make sure that the solution configuration is set to Release and perform a clean rebuild of the solution before continuing.

When you create a bot using a Visual Studio template, Yeoman template, or Cookiecutter template the source code generated includes a deploymentTemplates folder that contains ARM templates. The deployment process documented here uses one of the ARM templates to provision required resources for the bot in Azure by using the Azure CLI.

Note

With the release of Bot Framework SDK 4.3, we have deprecated the use of a .bot file. Instead, we use a configuration file, such as an appsettings.json or .env file, to manage bot resources. For information on migrating settings from the .bot file to a configuration file, see managing bot resources.
Both .NET Core 2.1 and .NET Core 3.1 versions of the C# templates are available. When creating new bots in Visual Studio 2019, you should use the .NET Core 3.1 templates.
The current bot samples use .NET Core 3.1 templates. You can find the samples that use .NET Core 2.1 templates in the 4.7-archive branch of the BotBuilder-Samples repository. For information about deploying .NET Core 3.1 bots to Azure, see Deploy your bot.

Bot ready to deploy

This article assumes that you have a bot ready to be deployed. If you are deploying a C# bot make sure that it has been built in Release mode.

For information on how to create a simple echo bot, see the quick start C# sample, JavaScript sample or Python sample. You can also use one of the samples provided in the Bot Framework Samples repository.

1. Login to Azure

Once you've created and tested a bot locally, you can 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.

Note

If you deploy your bot to a non-Azure cloud such as US Gov, you need to run az cloud set --name <name-of-cloud> before az login, where <name-of-cloud> is the name of a registered cloud, such as AzureUSGovernment. If you want to go back to public cloud, you can run az cloud set --name AzureCloud.

2. 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.

3. Create an App registration

In this step you will create an Azure application registration, which will allow:

  • The user to interact with the bot via a set of channels such as Web Chat.
  • The definition of OAuth Connection Settings to authenticate a user and to create a token used by the bot to access protected resources on behalf of the user.

3.1 Create the Azure application registration

To create an Azure application registration, execute the following command:

az ad app create --display-name "displayName" --password "AtLeastSixteenCharacters_0" --available-to-other-tenants
Option Description
display-name The display name of the application. It is listed in the Azure portal in the general resources list and in the resource group it belongs.
password The password, also known as client secret, for the application. This is a password you create for this resource. It must be at least 16 characters long, contain at least 1 upper or lower case alphabetical character, and contain at least 1 special character.
available-to-other-tenants Indicates that the application can be used from any Azure AD tenant. Set this to enable your bot to work with the Azure Bot Service channels.

3.2 Record the appId and appSecret values

You will need to record two values after executing the command in the previous step (step 3.1):

  • The password you create in the previous step.
  • The appId which you can find in the output JSON.

Copy and save the appId and password values. You will need to use them in the ARM deployment step, to assign values to the appId and the appSecret parameters, respectively.

4. Deploy via ARM template

When creating the bot application service, you can deploy your bot in a new or in an existing resource group, both via the Azure Resource Manager (ARM) template. An ARM template is a JSON file that declaratively defines one or more Azure resources and that defines dependencies between the deployed resources. Make sure that you have the correct path to your bot project ARM deployment templates directory DeploymentTemplates, you need it to assign the value to the template file. Choose the option that works best for you:

Note

Python bots cannot be deployed to a resource group that contains Windows services/bots. Multiple Python bots can be deployed to the same resource group, but create other services (LUIS, QnA, etc.) in another resource group.

Deploy via ARM template with new Resource Group

In this step, you create a bot application service which sets the deployment stage for the bot. You use an ARM template, a new service plan and a new resource group. Run the following Azure cli command to start a deployment at subscription scope from a local template file.

az deployment sub create --template-file "<path-to-template-with-new-rg.json" --location <region-location-name> --parameters appId="<app-id-from-previous-step>" appSecret="<password-from-previous-step>" botId="<id or bot-app-service-name>" botSku=F0 newAppServicePlanName="<new-service-plan-name>" newWebAppName="<bot-app-service-name>" groupName="<new-group-name>" groupLocation="<region-location-name>" newAppServicePlanLocation="<region-location-name>" --name "<bot-app-service-name>"

Note

This step can take a few minutes to complete.

Option Description
name The display name to use for your bot channels registration. Default is the value of the botId parameter.
template-file The path to the ARM template. Usually, the template-with-new-rg.json file is provided in the deploymentTemplates folder of the bot project. This is a path to an existing template file. It can be an absolute path, or relative to the current directory. All bot templates generate ARM template files.
location Location. Values from: az account list-locations. You can configure the default location using az configure --defaults location=<location>.
parameters Deployment parameters, provided as a list of key=value pairs. Enter the following parameter values:
  • appId - The app id value from the JSON output generated by the create the application registration step.
  • appSecret - The password you provided in the create the application registration step.
  • botId - A name for the Bot Channels Registration resource to create. It must be globally unique. It is used as the immutable bot ID. It is also used as the default display name, which is mutable.
  • botSku - The pricing tier; it can be F0 (Free) or S1 (Standard).
  • newAppServicePlanName - The name of the new application service plan.
  • newWebAppName - A name for the bot application service.
  • groupName - A name for the new resource group.
  • groupLocation - The location of the Azure resource group.
  • newAppServicePlanLocation - The location of the application service plan.
Deploy via ARM template with existing Resource Group

In this step, you create a bot application service which sets the deployment stage for the bot. When using an existing resource group, you can either use an existing app service plan or create a new one. Choose the option that works best for you:

Note

This step can take a few minutes to complete.

Option 1: Existing App Service Plan

In this case, we are using an existing App Service Plan, but creating a new Web App and Bot Channels Registration.

This command below sets the bot's ID and display name. The botId parameter should be globally unique and is used as the immutable bot ID. The bot's display name is mutable.

az deployment group create --resource-group "<name-of-resource-group>" --template-file "<path-to-template-with-preexisting-rg.json>" --parameters appId="<app-id-from-previous-step>" appSecret="<password-from-previous-step>" botId="<id or bot-app-service-name>" newWebAppName="<bot-app-service-name>" existingAppServicePlan="<name-of-app-service-plan>" appServicePlanLocation="<region-location-name>" --name "<bot-app-service-name>"
Option 2: New App Service Plan

In this case, we are creating App Service Plan, Web App, and Bot Channels Registration.

az deployment group create --resource-group "<name-of-resource-group>" --template-file "<path-to-template-with-preexisting-rg.json>" --parameters appId="<app-id-from-previous-step>" appSecret="<password-from-previous-step>" botId="<id or bot-app-service-name>" newWebAppName="<bot-app-service-name>" newAppServicePlanName="<name-of-app-service-plan>" appServicePlanLocation="<region-location-name>" --name "<bot-app-service-name>"
Option Description
name The display name to use for your bot channels registration. Default is the value of the botId parameter.
resource-group Name of the azure resource group.
template-file The path to the ARM template. Usually, the template-with-preexisting-rg.json file is provided in the deploymentTemplates folder of the project. This is a path to an existing template file. It can be an absolute path, or relative to the current directory. All bot templates generate ARM template files.
location Location. Values from: az account list-locations. You can configure the default location using az configure --defaults location=<location>.
parameters Deployment parameters, provided as a list of key=value pairs. Enter the following parameter values:
  • appId - The appId value generated by the 3.1 create the application registration step.
  • appSecret - The password you provided in the the 3.1 create the application registration step.
  • botId - A name for the Bot Channels Registration resource to create. It must be globally unique. It is used as the immutable bot ID. It is also used as the default display name, which is mutable.
  • newWebAppName - A name for the bot application service.
  • newAppServicePlanName - A name for the application service plan resource to create.
  • newAppServicePlanLocation - The location of the application service plan.

5. Prepare your code for deployment

Retrieve or create necessary IIS/Kudu files

You need to prepare your project files before you can deploy your C#, Javascript, or Typescript bot. See the Python information if you need to prepare the project files before deploying your Python bot.

az bot prepare-deploy --lang Csharp --code-dir "." --proj-file-path "MyBot.csproj"

You must provide the path to the .csproj file relative to --code-dir. This can be performed via the --proj-file-path argument. The command would resolve --code-dir and --proj-file-path to "./MyBot.csproj".

This command generates a .deployment file in your bot project folder.

Zip up the code directory manually

When using the non-configured zip deploy API to deploy your bot's code, Web App/Kudu's behavior is as follows:

Kudu assumes by default that deployments from zip files are ready to run and do not require additional build steps during deployment, such as npm install or dotnet restore/dotnet publish.

It is important to include your built code with all necessary dependencies in the zip file being deployed, otherwise your bot will not work as intended.

Important

Before zipping your project files, make sure that you are in the bot's project folder.

  • For C# bots, it is the folder that has the .csproj file.
  • For JavaScript bots, it is the folder that has the app.js or index.js file.
  • For TypeScript bots, it is the folder that includes the src folder (where the bot.ts and index.ts files are).
  • For Python bots, it is the folder that has the app.py file.

Within the project folder, make sure you select all the files and folders before running the command to create the zip file. This will create a single zip file within the project folder. If your root folder location is incorrect, the bot will fail to run in the Azure portal.

Deploy code to Azure

At this point we are ready to deploy the code to the Azure Web App. Run the following command from the command line to perform deployment using the kudu zip push deployment for a web app.

az webapp deployment source config-zip --resource-group "<resource-group-name>" --name "<name-of-web-app>" --src "<project-zip-path>"
Option Description
resource-group The name of the Azure resource group that contains your bot. (This will be the resource group you used or created when creating the app registration for your bot.)
name Name of the Web App you used earlier.
src The path to the zipped project file you created.

Note

This step can take a few minutes to complete. Also it can take a few more minutes between when the deployment finishes and when your bot is available to test.

Test in Web Chat

  1. In your browser, navigate to the Azure portal.
  2. In the left panel, click Resource groups.
  3. In the right panel, search for your group.
  4. Click on your group name.
  5. Click the link of your Bot Channels Registration.
  6. In the Bot Channels Registration panel, click Test in Web Chat. Alternatively, in the right panel, click the Test box.

For more information about bot channels registration, see Register a bot with Bot Service.

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.

If you create your bot through the Azure portal, you are able to provision additional resources, like Application Insights for telemetry.

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