Deploy your bot in Azure
APPLIES TO: SDK v4
This article demonstrates how to deploy a basic bot to Azure. It explains how to prepare your bot for deployment, deploy your bot to Azure, and test your bot in Web Chat. Read through this article before following the steps, so that you fully understand what is involved in deploying a bot.
Important
Use the latest version of the Azure CLI. If you are using an Azure CLI version older than 2.2.0, you might encounter errors. Also, don't mix the Azure CLI deployment shown in this article with Azure portal deployment.
Prerequisites
- If you don't have an Azure subscription, create a free account before you begin.
- A C#, JavaScript, TypeScript, Java, or Python bot that you have developed on your local machine. If you don't have a bot to deploy yet, see Create a bot with the Bot Framework SDK.
- Latest version of the Azure CLI.
- Familiarity with Azure CLI and ARM templates.
- For Java only, Maven.
Prepare for deployment
This article assumes that you have a bot ready to be deployed. For information on how to create a simple echo bot, see Create a bot with the Bot Framework SDK. You can also use one of the samples provided in the Bot Framework Samples repository.
If you are deploying a C#, bot make sure that it has been built in Release mode. In Visual Studio, make sure that the solution configuration is set to Release and perform a clean rebuild of the solution before continuing. The deployment may fail if the solution configuration is set to Debug.
When you Create a bot, 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
The VSIX package includes both .NET Core 2.1 and .NET Core 3.1 versions of the C# templates. When creating new bots in Visual Studio 2019 or later, 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.
To install the templates in Visual Studio, in the top menu bar, navigate to Extensions > Manage Extensions. Then search for and install Bot Framework v4 SDK for Visual Studio.
For information about deploying .NET Core 3.1 bots to Azure, see how to deploy your bot to Azure.
Sign in 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.
Set the subscription
Set the default subscription to use.
az account set --subscription "<azure-subscription-id>"
If you aren't 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.
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.
Note
The Web Chat channel is configured by default. If you want to connect your bot to any other channel, you need to perform the related configuration steps. For example, this is how you Connect a bot to Microsoft Teams.
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.
Create the Azure application registration
Note
The user-assigned managed identity and single-tenant app types are only supported for C# and JavaScript bots:
- The Bot Framework SDK for C# or JavaScript version 4.15.0 or later is required.
- The SDKs for Python and Java only support multi-tenant bots.
- Bot Framework Composer and Emulator only support multi-tenant bots.
To create an Azure application registration, use the following command:
az identity create --group "resourceGroupName" --name "userAssignedManagedIdentityName"
| Option | Description |
|---|---|
| group | The name of resource group name in which to create the identity. |
| name | The name of the identity resource to create |
Deploy using an 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:
- Deploy via ARM template with new resource group
- Deploy via ARM template with existing resource group
Important
Python and Java 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 you need to 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.
This step can take a few minutes to complete.
Important
Web App Bot and Bot Channels Registration are deprecated but existing resources will continue to work. Bots created with a version 4.14.1.2 or later template will generate an Azure Bot resource.
az deployment sub create --template-file "<path-to-template-with-new-rg.json" --location <region-location-name> --parameters appType="UserAssignedMSI" appId="<client-id-from-previous-step>" tenantId="<azure-ad-tenant-id>" existingUserAssignedMSIName="<user-assigned-managed-identity-name>" existingUserAssignedMSIResourceGroupName="<user-assigned-managed-identity-resource-group>" 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>"
| Option | Description |
|---|---|
| location | Location. |
| name | The deployment name. |
| parameters | Deployment parameters, provided as a list of key-value pairs. See the table of parameters for descriptions. |
| 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. |
Tip
Use the ARM template for a new resource group, template-with-new-rg.json.
| Parameter | Description |
|---|---|
| appId | The client ID or app ID value from the JSON output generated in the create the application registration step. |
| appSecret | For single-tenant and multi-tenant bots, the password you provided in the create the application registration step. |
| appType | The type of app service to create: "MultiTenant", "SingleTenant", or "UserAssignedMSI". |
| botId | The name of the Azure Bot resource your created earlier. |
| botSku | The pricing tier: F0 (Free), or S1 (Standard). |
| existingUserAssignedMSIName | For user-assigned managed identity bots, the name of the identity resource you created in the previous step. |
| existingUserAssignedMSIResourceGroupName | For user-assigned managed identity bots, the name of resource group name in which you created the identity. |
| groupLocation | The location of the Azure resource group. |
| groupName | A name for the new resource group. |
| newAppServicePlanLocation | The location of the application service plan. |
| newAppServicePlanName | The name of the new application service plan. |
| newWebAppName | A name for the bot application service. |
| tenantId | For user-assigned managed identity and single-tenant bots, the bot's app tenant ID. |
Tip
- Use
az account list-locationsto list supported regions for the current subscription. - Use
az config set defaults.location=<location>to set he default location to use for all commands.
Deploy via ARM template with existing resource group
In this step, you create a bot application service that 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:
This step can take a few minutes to complete.
Important
Web App Bot and Bot Channels Registration are deprecated but existing resources will continue to work. Bots created with a version 4.14.1.2 or later template will generate an Azure Bot resource.
Option 1: Existing App Service Plan
In this case, we are using an existing App Service Plan, but creating a new Web App and Azure Bot resource.
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 group deployment create --resource-group "<name-of-resource-group>" --template-file "<path-to-template-with-preexisting-rg.json>" --parameters appId="<client-id-from-previous-step>" appType="UserAssignedMSI" tenantId="<azure-ad-tenant-id>" existingUserAssignedMSIName="<user-assigned-managed-identity-name>" existingUserAssignedMSIResourceGroupName="<user-assigned-managed-identity-resource-group>" 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 Azure Bot resource.
az group deployment create --resource-group "<name-of-resource-group>" --template-file "<path-to-template-with-preexisting-rg.json>" --parameters appId="<client-id-from-previous-step>" appType="UserAssignedMSI" tenantId="<azure-ad-tenant-id>" existingUserAssignedMSIName="<user-assigned-managed-identity-name>" existingUserAssignedMSIResourceGroupName="<user-assigned-managed-identity-resource-group>" 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 deployment name. |
| parameters | Deployment parameters, provided as a list of key-value pairs. See the table of parameters for descriptions. |
| 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. |
Tip
Use the ARM template for an existing resource group, template-with-preexisting-rg.json.
| Parameter | Description |
|---|---|
| appId | The client ID or app ID value from the JSON output generated in the create the application registration step. |
| appSecret | For single-tenant and multi-tenant bots, the password you provided in the create the application registration step. |
| appServicePlanLocation | The location for the new app service plan. |
| appType | The type of app service to create: "MultiTenant", "SingleTenant", or "UserAssignedMSI". |
| botId | The name of the Azure Bot resource your created earlier. |
| existingAppServicePlan | The name of the existing app service plan to use. |
| existingUserAssignedMSIName | For user-assigned managed identity bots, the name of the identity resource you created in the previous step. |
| existingUserAssignedMSIResourceGroupName | For user-assigned managed identity bots, the name of resource group name in which you created the identity. |
| newAppServicePlanName | The name of the new app service plan to create. |
| newWebAppName | The name of the app service to create. |
| tenantId | For user-assigned managed identity and single-tenant bots, the bot's app tenant ID. |
Prepare your code for deployment
Bot identity information
You need to add identity information to your bot's configuration file. The file differs depending on the programming language you use to create the bot.
Important
The Java and Python versions of the Bot Framework SDK only support multi-tenant bots. The C# and JavaScript versions support all three application types for managing the bot's identity.
| Language | File name | Notes |
|---|---|---|
| C# | appsettings.json | Supports all three application types for managing your bot's identity. |
| JavaScript | .env | Supports all three application types for managing your bot's identity. |
| Java | application.properties | Only supports multi-tenant bots. |
| Python | config.py | Only supports multi-tenant bots. Provide the identity properties as arguments to the os.environ.get method calls. |
The identity information you need to add depends on the bot's application type. Provide the following values in your configuration file.
Only available for C# and JavaScript bots.
| Property | Value |
|---|---|
MicrosoftAppType |
UserAssignedMSI |
MicrosoftAppId |
The client ID of the user-assigned managed identity. |
MicrosoftAppPassword |
Leave this blank for a user-assigned managed identity bot. |
MicrosoftAppTenantId |
The bot's app tenant ID. |
Important
After you have updated the configuration file, make sure to clean and rebuild the bot project.
Retrieve or create necessary IIS/Kudu files
You need to prepare your project files before you can deploy your bot.
Make sure you're in your bot's project folder. Then prepare your bot code for deployment.
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 don't require extra build steps during deployment, such as npm install or dotnet restore/dotnet publish.
It's important to include your built code with all necessary dependencies in the zip file being deployed, otherwise your bot will not work as intended. For more information, see the Azure documentation on how to Deploy files to App Service.
Important
Before zipping your project files, make sure that you are in the bot's project folder.
- For C# bots, it's the folder that has the .csproj file.
- For JavaScript bots, it's the folder that has the app.js or index.js file.
- For TypeScript bots, it's the folder that includes the src folder (where the bot.ts and index.ts files are).
- For Python bots, it's 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 the bot 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. |
| 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
- In your browser, navigate to the Azure portal.
- Go to your bot resource.
- Open the Test in Web Chat pane.
- Interact with your deployed bot.
For more information about bot registration, see Register a bot with Bot Service.
Additional information
Deploying your bot to Azure will involve paying for the services you use. The billing and cost management article helps you understand Azure billing, monitor usage and costs, and manage your account and subscriptions. See also Azure Command-Line Interface (CLI) documentation and Azure CLI release notes.