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. Only critical security and bug fixes within this repository will be undertaken.

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

For new bot building, consider using Power Virtual Agents and read about choosing the right chatbot 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.36.0
    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# and JavaScript in version 4.15.0. These app types aren't supported in the other languages or in Bot Framework Composer, Bot Framework Emulator, or ngrok.

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

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.

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

Sign in and select 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 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.

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

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

  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

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

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

az webapp deployment source config-zip --resource-group "<resource-group-name>" --name "<name-of-app-service>" --src "<project-zip-path>"
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 deployment source config-zip command reference.

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