Provision and publish a bot

APPLIES TO: SDK v4

This article describes how to use the Azure CLI to create resources for your bot, prepare your bot for deployment, and deploy your bot to Azure.

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.

Tip

This article creates an Azure Bot resource for your bot. Existing bots that use a Web App Bot resource or a Bot Channels Registration resource will continue to work, but you can't create new bots that use these resource types.

Note

The Bot Framework JavaScript, C#, and Python SDKs will continue to be supported, however, the Java SDK is being retired with final long-term support ending in November 2023.

Existing bots built with the Java SDK will continue to function.

For new bot building, consider using Microsoft Copilot Studio and read about choosing the right copilot solution.

For more information, see The future of bot building.

Prerequisites

• For Java bots, install Maven.

• This process uses two Azure Resource Manager templates (ARM templates) to create resources for your bot.

  If you don't have the current templates, create a copy in your bot project of the deploymentTemplates folder: C#, JavaScript, Python, or Java.

To use the Azure CLI to provision and publish bots, you need:

• An Azure account that has an active subscription. Create a free account.

• An install of the Azure CLI.

  For your programming language, use the following version of the Azure CLI. Some steps won't work with later versions of the CLI.

  Language	CLI version
  C# and JavaScript	2.39.0 or later
  Python	2.55.0 or later
  Java	2.29.2

Note

If your bot uses additional resources, such as a storage service or language services, these need to be deployed separately.

Plan your deployment

Before you begin, make these decisions.

Decision	Notes
How you'll manage the identities of your bot resources in Azure	You can use a user-assigned managed identity, a single-tenant app registration, or a mutli-tenant app registration. For more information, see Create an identity resource.
In which resource group or resource groups you'll create your bot resources	Until you're familiar with this process, we recommend using one resource group. For more information, see Manage Azure resources.
Whether your bot will be regional or global	For information about regional bots, see Regionalization in Azure AI Bot Service.

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 to the Bot Framework SDK for C#, JavaScript, and Python. These app types aren't supported in the other languages or in Bot Framework Composer, Bot Framework Emulator, or Dev Tunnels.

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

Important

Python bots can't be deployed to a resource group that contains Windows services or bots. However, multiple Python bots can be deployed to the same resource group. Create other services, such as Azure AI services, in a different resource group.

Azure resources

Before you can deploy your bot, you create (or provision) the Azure resources it will need. For some of the steps, you can use an existing resource or create a new one.

You may find it helpful to decide ahead of time on the names of the new resources you'll create and the names of the existing resources you'll use. Your bot will use these types of resources.

• The Azure subscription that you'll use to provision, publish, and manage the bot
• One or more resource groups
• A user-assigned managed identity or an Microsoft Entra ID app registration
• An App Service Plan resource
• An App Service resource
• An Azure Bot resource

Information used across resources

As you create resources in Azure, Azure will generate or request IDs, passwords, and other information that you'll need in later steps. The following table lists the information beyond resource names you'll need to record, in which step it's generated, and in which steps it's used.

Caution

Many of these IDs and passwords are sensitive information. For information about common security guidelines, see Bot Framework security guidelines.

User-assigned managed identity

Information	Where generated or found	Where used
Tenant ID	Sign in and select subscription	Use Azure CLI to create an App Service resource, Use Azure CLI to create or update an Azure Bot resource, Update project configuration settings
App type	Create an identity resource	Use Azure CLI to create an App Service resource, Use Azure CLI to create or update an Azure Bot resource, Update project configuration settings
Client ID	Create an identity resource	Use Azure CLI to create an App Service resource, Use Azure CLI to create or update an Azure Bot resource, Update project configuration settings
Base app service URL	Use Azure CLI to create an App Service resource	Use Azure CLI to create or update an Azure Bot resource
App Service name	Use Azure CLI to create an App Service resource	Publish your bot to Azure

Single-tenant

Information	Where generated or found	Where used
Tenant ID	Sign in and select subscription	Use Azure CLI to create an App Service resource, Use Azure CLI to create or update an Azure Bot resource, Update project configuration settings
App type	Create an identity resource	Use Azure CLI to create an App Service resource, Use Azure CLI to create or update an Azure Bot resource, Update project configuration settings
App ID	Create an identity resource	Use Azure CLI to create an App Service resource, Use Azure CLI to create or update an Azure Bot resource
App password	Create an identity resource	Use Azure CLI to create an App Service resource, Update project configuration settings
Base app service URL	Use Azure CLI to create an App Service resource	Use Azure CLI to create or update an Azure Bot resource
App Service name	Use Azure CLI to create an App Service resource	Publish your bot to Azure

Multi-tenant

Information	Where generated or found	Where used
App type	Create an identity resource	Use Azure CLI to create an App Service resource, Use Azure CLI to create or update an Azure Bot resource, Update project configuration settings
App ID	Create an identity resource	Use Azure CLI to create an App Service resource, Use Azure CLI to create or update an Azure Bot resource
App password	Create an identity resource	Use Azure CLI to create an App Service resource, Update project configuration settings
Base app service URL	Use Azure CLI to create an App Service resource	Use Azure CLI to create or update an Azure Bot resource
App Service name	Use Azure CLI to create an App Service resource	Publish your bot to Azure

Sign in and select subscription

1. Open a command window.

2. Sign in to Azure.

   Azure CLI

   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:

   Azure CLI

   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 resource groups

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

Azure CLI

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.

Create an identity resource

User-assigned managed identity

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

   Azure CLI

   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.

2. Record values you'll need in later steps.

   1. The resource group name for the identity resource
   2. The name of the identity resource
   3. The clientId from the command output

Single-tenant

Use the following commands to create your app registration and set its password. On success, these commands generate JSON output.

1. Use the az ad app create command to create an Microsoft Entra ID app registration. This command generates an app ID that you'll use in the next step.

   Azure CLI

   az ad app create --display-name "<app-registration-display-name>" --sign-in-audience "AzureADMyOrg"
   

   Option	Description
   display-name	The display name for your app registration.
   sign-in-audience	The supported Microsoft accounts for the app. Use AzureADMyOrg for a single tenant app.

2. Use the az ad app credential reset command to generate a new password for your app registration.

   Azure CLI

   az ad app credential reset --id "<appId>"
   

3. Record values you'll need in later steps: the app ID and password from the command output.

For more information about az ad app, see the command reference. For more information about the sign-in-audience parameter, see sigInAudience values.

Multi-tenant

C# / JavaScript / Python

For Azure CLI 2.39.0 or later, use the following commands to create your app registration and set its password. On success, these commands generate JSON output.

1. Use the az ad app create command to create an Microsoft Entra ID app registration. This command generates an app ID that you'll need in later steps.

   Azure CLI

   az ad app create --display-name "<app-registration-display-name>" --sign-in-audience "AzureADandPersonalMicrosoftAccount"
   

   Option	Description
   display-name	The display name for your app registration.
   sign-in-audience	The supported Microsoft accounts for the app. Use AzureADandPersonalMicrosoftAccount for a multi-tenant app.

2. Use the az ad app credential reset command to generate a new password for your app registration.

   Azure CLI

   az ad app credential reset --id "<appId>"
   

3. Record values you'll need in later steps: the app ID and password from the command output.

For more information about az ad app, see the command reference. For more information about the sign-in-audience parameter, see sigInAudience values.

Java

For Azure CLI 2.36.0 or earlier, use the following command to create your app registration and set its password. On success, this command generates JSON output.

1. Use the az ad app create command to create an Microsoft Entra ID app registration.

   Azure CLI

   az ad app create --display-name "<name>" --password "<password>" --available-to-other-tenants
   

   Option	Description
   display-name	The display name for the app registration.
   password	The password, or client secret, for the application. It must be at least 16 characters long and contain at least one upper-case or lower-case alphabetical character, at least one numeric character, and at least one special character.
   available-to-other-tenants	Include this flag to create a multi-tenant bot. It allows the application to be accessible from any Microsoft Entra ID tenant.

2. Record values you'll need in later steps.

   1. The password you used
   2. The app ID from the command output

Create resources with ARM templates

Create the App Service and the Azure Bot resources for your bot. Both steps use an ARM template and the az deployment group create Azure CLI command to create the resource or resources.

1. Create an App Service resource for your bot. The App service can be within a new or existing App Service Plan.

   For detailed steps, see Use Azure CLI to create an App Service.

2. Create an Azure Bot resource for your bot.

   For detailed steps, see Use Azure CLI to create or update an Azure Bot.

Important

You can do these steps in either order. However, if you create your Azure Bot first, you'll need to update its messaging endpoint after you create your App Service resource.

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 version of the Bot Framework SDK only supports multi-tenant bots. The C#, JavaScript, and Python 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	Supports all three application types for managing your bot's identity.

The identity information you need to add depends on the bot's application type. Provide the following values in your configuration file.

User-assigned managed identity

Available for C#, JavaScript, and Python 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.

Single-tenant

Available for C#, JavaScript, and Python bots.

Property	Value
MicrosoftAppType	SingleTenant
MicrosoftAppId	The bot's app ID.
MicrosoftAppPassword	The bot's app password.
MicrosoftAppTenantId	The bot's app tenant ID.

Multi-tenant

Available for bots in all programming languages: C#, JavaScript, Java, and Python.

Property	Value
MicrosoftAppType	MultiTenant
MicrosoftAppId	The bot's app ID.
MicrosoftAppPassword	The bot's app password.
MicrosoftAppTenantId	Not applicable. Leave this blank for a multi-tenant bot.

Prepare your project files

Prepare your project files before you deploy your bot.

C#

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.

   Azure CLI

   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.

JavaScript

1. Switch to your project's root folder.

   • For JavaScript, the root is the folder that contains the app.js or index.js file.
   • For TypeScript, the root is the folder that contains the src folder (where the bot.ts and index.ts files are).

2. Run npm install.

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 web.config file in your project folder. Azure App Services requires each Node.js bot to include a web.config file in its project root folder.

   Azure CLI

   az bot prepare-deploy --lang <language> --code-dir "."
   

   Option	Description
   lang	The language or runtime of the bot. Use Javascript or Typescript.
   code-dir	The directory to place the generated deployment files in. Use your project's root folder. Default is the current directory.

4. Within your project's root folder, create a zip file that contains all files and subfolders.

Java

1. Switch to your project's root folder.

2. In the project directory, run the following command from the command line:

   Console

   mvn clean package
   

Python

Tip

For Python bots, dependency installation is performed on the server. The ARM templates require your dependencies to be listed in a requirements.txt file.

1. If you're using a dependency and package manager:
   1. Convert your dependencies list to a requirements.txt file
   2. Add requirements.txt to the folder that contains app.py.
2. Within your project's root folder, create a zip file that contains all files and subfolders.

Publish your bot to Azure

At this point, you're ready to deploy code for your bot to your App Service resource.

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.

C# / JavaScript / Python

Run the az webapp deploy command from the command line to perform deployment using the Kudu zip push deployment for your app service (web app).

Option	Description
resource-group	The name of the Azure resource group that contains your bot.
name	Name of the app service you used earlier.
src	The absolute or relative path to the zipped project file you created.

Tip

By default, this command deploys to the production slot. Use the optional --slot parameter to specify a different slot. For more information, see the az webapp deploy command reference documentation.

Java

In the project directory, run the following command from the command line.

Console

mvn azure-webapp:deploy -Dgroupname="<resource-group-name>" -Dbotname="<name-of-web-app>"

Option	Description
Dgroupname	The name of the Azure resource group that contains your bot.
Dbotname	Name of the app service you used earlier.

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.

Clean up resources

If you're not going to publish 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 Microsoft Entra ID blade.
   2. Locate the app registration you used for your bot, and delete it.

Additional resources

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 Microsoft Entra ID
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

Kudu files

The web app deployment command uses Kudu to deploy C#, JavaScript, and Python bots. When using the non-configured zip deploy API to deploy your bot's code, the 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 won't work as intended. For more information, see the Azure documentation on how to Deploy files to App Service.

Next steps

Set up continuous deployment