Publish your bot to Azure

APPLIES TO: SDK v4

This article demonstrates how to deploy a basic bot to Azure. It explains how to create resources for your bot, prepare your bot for deployment, deploy your bot to Azure, and test your bot in Web Chat.

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.

Prerequisites

To use the Azure CLI, you need:

  • An Azure account that has an active subscription. Create a free account.
  • An install of the Azure CLI.
    • For C#, JavaScript, and Python bots, use the latest version of the Azure CLI.
    • For Java bots, use Azure CLI version 2.29.2. Some steps won't work with later versions of the CLI.

Starting with Bot Framework SDK 4.14.1.2, when you create a bot from a VSIX or Yeoman template, the resulting project contains ARM templates. The samples and any new bots created from a Bot Framework template contain a deployment templates directory that contains the ARM templates. You'll use the ARM templates to provision many of your bot resources.

For Java bots, install Maven.

Sign in to Azure and select a subscription

  1. Open a command window.

  2. Sign in to Azure.

    az login
    

    A browser window will open. Complete the sign in process. On success, the command outputs a list of the subscriptions your account has access to.

  3. To set the subscription to use, run:

    az account set --subscription "<subscription>"
    

    For <subscription>, use the ID or name of the subscription to use.

  4. If you'll create a user-assigned managed identity or a single-tenant bot, record the tenantId for the subscription. You'll use the tenant ID in the following steps.

Tip

If you need to work in a non-public cloud, see Azure cloud management with the Azure CLI.

Create an identity resource

Your bot identity can be managed in Azure in a few different ways.

  • As a user-assigned managed identity, so that you don't need to manage the bot's credentials yourself.
  • As a single-tenant app.
  • As a multi-tenant app.

Support for the user-assigned managed identity and single-tenant app types was added for C# and JavaScript to the Bot Framework SDK in version 4.15.0. These app types aren't supported in the other languages or in Composer, the Emulator, or ngrok.

App type Support
User-assigned managed identity Azure Bot Service and the C# and JavaScript SDKs
Single-tenant Azure Bot Service and the C# and JavaScript SDKs
Multi-tenant Azure Bot Service, all Bot Framework SDK languages, Composer, the Emulator, and ngrok

To create an Azure application registration:

Tip

You need an existing resource group in which to create the managed identity.

  1. If you don't already have an appropriate resource group, use the az group create command to create a new resource group.

    az group create --name "<group>" --location "<region>"
    
    Option Description
    name The name of the resource group to create.
    location The region in which to create the resource group.

    For more information, see How to manage Azure resource groups with the Azure CLI.

  2. To create a user-assigned managed identity, use the az identity create command. On success, the command generates JSON output.

    az identity create --resource-group "<group>" --name "<identity>"
    
    Option Description
    resource-group The name of the resource group in which to create the identity.
    name The name of the identity resource to create.

    For more information, see the az identity reference.

  3. Record the resource group and identity name you entered and the clientId from the command output. You'll use these values in following steps.

Create resources with an ARM template

You'll use an Azure Resource Manager (ARM) template to create an app service and Azure Bot resource.

Your bot project's deployment templates directory contains two ARM templates.

  • One creates resources in a new resource group, with a new app service plan.
  • One creates resources in an existing resource group, with a new or existing app service plan.

Choose the option that works best for you. This step can take a few minutes to complete.

Tip

The Azure Web App Bot and Bot Channels Registration resource types are deprecated. Resources configured and deployed prior to deprecation will continue to work. Bots created from a VSIX or Yeoman template from SDK version 4.14.1.2 or later contain ARM templates that will generate an Azure Bot resource.

For a user-assigned managed identity bot, run this command to provision resources in a new resource group and new app service plan.

az deployment sub create --template-file "<path>" --location <bot-region> --parameters appType="UserAssignedMSI" appId="<client-id>" tenantId="<tenant-id>" existingUserAssignedMSIName="<identity>" existingUserAssignedMSIResourceGroupName="<identity-group>" botId="<bot-id>" botSku=<tier> newAppServicePlanName="<plan-name>" newWebAppName="<service-name>" groupName="<group-name>" groupLocation="<group-region>" newAppServicePlanLocation="<plan-region>" --name "<deployment-name>"

This table describes the command options for the az deployment sub create command.

Option Description
location The region in which to create the Azure Bot resource.
name The deployment name.
parameters Deployment parameters for the ARM template, provided as a list of key-value pairs. See the table of parameters for descriptions.
template-file The path to the template-with-new-rg.json ARM template in the bot project's deployment templates folder. The path can be relative or absolute.

This table describes the deployment parameters to use with the --parameters command option. Not all parameters apply to all app types.

Parameter Description
appId The client or app ID from the identity resource you created earlier. This is used as the Microsoft app ID of the web app.
appSecret For for single-tenant and multi-tenant app types, the password for the identity resource you created earlier.
appType The type of app service to create: UserAssignedMSI, SingleTenant, or MultiTenant. Default is MultiTenant.
botId The ID of the Azure Bot resource to create. The bot ID is immutable.
botSku The pricing tier to use for the bot: F0 (Free) or S1 (Standard).
existingUserAssignedMSIName For user-assigned managed identity app types, the name of the identity resource you created earlier.
existingUserAssignedMSIResourceGroupName For user-assigned managed identity app types, the name of the resource group for your identity resource.
groupLocation The region in which to create your new resource group.
groupName A name for your new resource group.
newAppServicePlanLocation The region in which to create the application service plan.
newAppServicePlanName The name of the app service plan to create for the bot.
newAppServicePlanSku Optional, the pricing tier to use for the app service plan. Default is S1.
newWebAppName The name of the app service to create for the bot. Must be a globally-unique web app name. Default is the value for the botId parameter.
tenantId For users-assigned managed identity and single-tenant app types, the Azure AD tenant to use for bot authentication. Default is your subscription tenant ID.

Update project configuration settings

Bot identity information

Follow these steps 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 Not applicable. Leave this blank for a user-assigned managed identity bot.
MicrosoftAppTenantId The tenant ID of the user-assigned managed identity.

Prepare your project files

Prepare your project files before you deploy your bot.

  1. Switch to your project's root folder. For C#, the root is the folder that contains the .csproj file.

  2. Do a clean rebuild in release mode.

  3. If you haven't done so before, run az bot prepare-deploy to add required files to the root of your local source code directory. This command generates a .deployment file in your bot project folder.

    az bot prepare-deploy --lang Csharp --code-dir "." --proj-file-path "<my-cs-proj>"
    
    Option Description
    lang The language or runtime of the bot. Use Csharp.
    code-dir The directory to place the generated deployment files in. Use your project's root folder. Default is the current directory.
    proj-file-path The path to the .csproj file for your bot, relative to the code-dir option.
  4. Within your project's root folder, create a zip file that contains all files and subfolders.

Publish your bot

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

  1. In your browser, navigate to the Azure portal.
  2. Go to your bot resource.
  3. Open the Test in Web Chat pane.
  4. Interact with your deployed bot.

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

Additional information

Resource locations

Some of the commands require a location or region parameter.

  • Use az account list-locations to list supported regions for the current subscription.
  • Use az config set defaults.location=<location> to set the default location to use for all az commands.

To create bots with data residency in Europe or the US, use "westeurope" or "westus2", respectively, for the location for the resource group and all bot resources. For more information about data residency, see Answering Europe's Call: Storing and Processing EU Data in the EU.

Azure documentation

See these articles for more information about Azure applications and resources that are used to host a bot.

Subject Article
Azure CLI What is the Azure CLI?
Azure subscription management How to manage Azure subscriptions with the Azure CLI
Azure regions Regions and availability zones
Resource groups and resource management Manage Azure resources
Managed identities What are managed identities for Azure resources?
Single-tenant and multi-tenant apps Tenancy in Azure Active Directory
Web applications App Service
Compute resources for web applications App Service plans
Azure Resource Manager templates (ARM templates) What are ARM templates? and How to use Azure Resource Manager (ARM) deployment templates with Azure CLI
Azure billing Billing and cost management

Clean up resources

If you're not going to continue to use this application, delete the associated resources with the following steps:

  1. In the Azure portal, open the resource group for your bot.
    1. Select Delete resource group to delete the group and all the resources it contains.
    2. Enter the resource group name in the confirmation pane, then select Delete.
  2. If you created a single-tenant or multi-tenant app:
    1. Go to the Azure Active Directory blade.
    2. Locate the app registration you used for your bot, and delete it.

Next steps