Tutorial: Create and deploy a basic bot
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.
- Visual Studio 2017 or later
- 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 Echo Bot (Bot Framework v4) template.
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 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:
- Click the Create a new bot configuration link in the emulator "Welcome" tab.
- Fill out the fields for your bot. Use your bot's welcome page address (typically http://localhost:3978) and append routing info '/api/messages' to this address.
- then click Save and connect.
Interact with your bot
Send a message to your bot, and the bot will respond back with a message.
If you see that the message cannot 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
- If you don't have an Azure subscription, create a free account before you begin.
- The bot from above, running on your local machine.
- Latest version of the Azure cli.
1. Prepare for deployment
When you create a bot using Visual Studio or Yeoman templates, the source code generated contains a
deploymentTemplates folder with ARM templates. The deployment process documented here uses the ARM template to provision required resources for the bot in Azure by using the Azure CLI.
Login to Azure
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.
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.
Create an App registration
Registering the application means that you can use Azure AD to authenticate users and request access to user resources. Your bot requires a Registered app in Azure that provides the bot access to the Bot Framework Service for sending and receiving authenticated messages. To create register an app via the Azure CLI, perform the following command:
az ad app create --display-name "displayName" --password "AtLeastSixteenCharacters_0" --available-to-other-tenants
|display-name||The display name of the application.|
|password||App password, aka 'client secret'. The password 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||The application can be used from any Azure AD tenants. Allowed values: false, true. True by default. This will enable your bot to work with the Azure Bot Service channels|
The above command outputs JSON with the key
appId, save the value of this key for the ARM deployment, where it will be used for the
appId parameter. The password provided will be used for the
You can deploy your bot in a new resource group or an existing resource group. Choose the option that works best for you.
- Deploy via ARM template (with new Resource Group)
- Deploy via ARM template (with existing Resource Group)
Create Azure resources
You'll create a new resource group in Azure and then use the ARM template to create the resources specified in it. In this case, we are providing App Service Plan, Web App, and Bot Channels Registration.
az deployment create --name "name-of-deployment" --template-file "template-with-new-rg.json" --location "location-name" --parameters appId="msa-app-guid" appSecret="msa-app-password" botId="id-or-name-of-bot" botSku=F0 newAppServicePlanName="name-of-app-service-plan" newWebAppName="name-of-web-app" groupName="new-group-name" groupLocation="location" newAppServicePlanLocation="location"
|name||Friendly name for the deployment.|
|template-file||The path to the ARM template. You can use
|location||Location. Values from:
|parameters||Provide deployment parameter values.
Retrieve or create necessary IIS/Kudu files
For C# bots
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 will fetch a web.config which is needed for Node.js apps to work with IIS on Azure App Services. Make sure web.config is saved to the root of your bot.
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.
As such, it is important to include your built code and with all necessary dependencies in the zip file being deployed to the Web App, otherwise your bot will not work as intended.
Before zipping your project files, make sure that you are in the correct folder.
- For C# bots, it is the folder that has the .csproj file.
- For JS bots, it is the folder that has the app.js or index.js file.
Select all the files and zip them up while in that folder, then run the command while still in that folder.
If your root folder location is incorrect, the bot will fail to run in the Azure portal.
2. 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 "new-group-name" --name "name-of-web-app" --src "code.zip"
|resource-group||Resource group name in Azure that you created earlier.|
|name||Name of the Web App you used earlier.|
|src||The path to the zipped file you created.|
3. Test in Web Chat
- In the Azure portal, go to your Web App bot blade.
- In the Bot Management section, click Test in Web Chat. Azure Bot Service will load the Web Chat control and connect to your bot.
- Wait for a few seconds after a successful deployment and optionally restart your Web App to clear any cache. Go back to your Web App Bot blade and test using the Web Chat provided in the Azure portal.
When you deploy a bot, typically these resources are created in the Azure portal:
|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.