Manage resources with a .bot file

Bots usually consume lots of different services, such as or When you are developing a bot, there is no uniform place to store the metadata about the services that are in use. This prevents us from building tooling that looks at a bot as a whole.

To address this problem, we have created a .bot file to act as the place to bring all service references together in one place to enable tooling. For example, the Bot Framework Emulator (V4) uses a .bot file to create a unified view over the connected services your bot consumes.

With a .bot file, you can register services like:

  • Localhost local debugger endpoints
  • Azure Bot Service Azure Bot Service registrations.
  • LUIS.AI LUIS gives your bot the ability to communicate with people using natural language..
  • QnA Maker Build, train and publish a simple question and answer bot based on FAQ URLs, structured documents or editorial content in minutes.
  • Dispatch models for dispatching across multiple services.
  • Azure Application Insights for insights and bot analytics.
  • Azure Blob Storage for bot state persistence.
  • Azure Cosmos DB - globally distributed, multi-model database service to persist bot state.

Apart from these, your bot might rely on other custom services. You can leverage the generic service capability to connect a generic service configuration.

When is a .bot file created?

  • If you create a bot using Azure Bot Service, a .bot file is automatically created for you with list of connected services provisioned. The .bot is encrypted by default.
  • If you create a bot using Bot Framework V4 SDK Template for Visual Studio or using Bot Builder Yeoman Generator, a .bot file is automatically created. No connected services are provisioned in this flow and the bot file is not encrypted.
  • If you are starting with BotBuilder-samples, every sample for Bot Framework V4 SDK includes a .bot file and the .bot file is not encrypted.
  • You can also create a bot file using the MSBot tool.

What does a bot file look like?

Take a look at a sample .bot file. To learn about encrypting and decrypting the .bot file, see Bot Secrets.

Why do I need a .bot file?

A .bot file is not a requirement to build bots with Bot Framework SDK. You can continue to use appsettings.json, web.config, env, keyvault or any mechanism you see fit to keep track of service references and keys that your bot depends on. However, to test the bot using the Emulator, you'll need a .bot file. The good news is that Emulator can create a .bot file for testing. To do that, start the Emulator, click on the create a new bot configuration link on the Welcome page. In the dialog box that appears, type a Bot name and an Endpoint URL. Then connect.

The advantages of using .bot file are:

  • Provides a standard way of storing resources regardless of the language/platform you use.
  • Bot Framework Emulator and CLI tools rely on and work great with tracking connected services in a consistent format (in a .bot file)
  • Elegant tooling solutions around services creation and management is harder without a well defined schema (.bot file).

Using .bot file in your Bot Framework SDK bot

You can use the .bot file to get service configuration information in your bot's code. The BotFramework-Configuration library available for C# and JS helps you load a bot file and supports several methods to query and get the appropriate service configuration information.

Additional resources

Refer to MSBot readme file for more information on using a bot file.