Debug a bot

This article describes how to debug your bot using an integrated development environment (IDE) such as Visual Studio or Visual Studio Code and the Bot Framework Emulator. While you can use these methods to debug any bot locally, this article uses a C# and JS bot created in the quickstart.

Prerequisites

Debug a JavaScript bot using command-line and emulator

To run a JavaScript bot using the command line and testing the bot with the emulator, do the following:

  1. From the command line, change directory to your bot project directory.

  2. Start the bot by running the command node app.js.

  3. Start the emulator and connect to the bot's endpoint (e.g.: http://localhost:3978/api/messages). If this is the first time you are running the bot then click File > New Bot and follow the instructions on screen. Otherwise, click File > Open Bot to open an existing bot. Since this bot is running locally on your computer, you can leave the MSA app ID and MSA app password fileds blank. For more information, see Debug with the Emulator.

  4. From the emulator, send your bot a message (e.g.: send the message "Hi").

  5. Use the Inspector and Log panels on the right side of the emulator window to debug your bot. For example, clicking on any of the messages bubble (e.g.: the "Hi" message bubble in the screenshot below) will show you the detail of that message in the Inspector panel. You can use it to view requests and responses as messages are exchanged between the emulator and the bot. Alternatively, you can click on any of the linked text in the Log panel to view the details in the Inspector panel.

    Inspector panel on the Emulator

Debug a JavaScript bot using breakpoints in Visual Studio Code

In Visual Studio Code, you can set breakpoints and run the bot in debug mode to step through your code. To set breakpoints in VS Code, do the following:

  1. Launch VS Code and open your bot project folder.
  2. From the menu bar, click Debug and click Start Debugging. If you are prompted to select a runtime engine to run your code, select Node.js. At this point, the bot is running locally.
  1. Set breakpoint as necesary. In VS Code, you can set breakpoints by hovering your mouse over the column to the left of the line numbers. A small red dot will appear. If you click on the dot, the breakpoint is set. If you click the dot again, the breakpoint is removed.

    Set breakpoint in VS Code

  2. Start the Bot Framework Emulator and connect to your bot as described in the section above.

  3. From the emulator, send your bot a message (e.g.: send the message "Hi"). Execution will stop at the line where you place the breakpoint.

    Debug in VS Code

Debug a C# bot using breakpoints in Visual Studio

In Visual Studio (VS), you can set breakpoints and run the bot in debug mode to step through your code. To set breakpoints in VS, do the following:

  1. Navigate to your bot folder and open the .sln file. This will open the solution in VS.
  2. From the menu bar, click Build and click Build Solution.
  3. In the Solution Explorer, click EchoWithCounterBot.cs. This file defines your main bot logic.Set breakpoint as necesary. In VS, you can set breakpoints by hovering your mouse over the column to the left of the line numbers. A small red dot will appear. If you click on the dot, the breakpoint is set. If you click the dot again, the breakpoint is removed.
  4. From the menu bar, click Debug and click Start Debugging. At this point, the bot is running locally.

Set breakpoint in VS

  1. Start the Bot Framework Emulator and connect to your bot as described in the section above.

  2. From the emulator, send your bot a message (e.g.: send the message "Hi"). Execution will stop at the line where you place the breakpoint.

    Debug in VS

Debug a Consumption plan C# Functions bot

The Consumption plan serverless C# environment in Bot Service has more in common with Node.js than a typical C# application because it requires a runtime host, much like the Node engine. In Azure, the runtime is part of the hosting environment in the cloud, but you must replicate that environment locally on your desktop.

Prerequisites

Before you can debug your Consumption plan C# bot, you must complete these tasks.

If you want to be able to debug your code by using breakpoints in Visual Studio 2017, you must also complete these tasks.

Note

Visual Studio Code is not currently supported.

Debug a Consumption plan C# Functions bot using the emulator

The simplest way to debug your bot locally is to start the bot and then connect to it from Bot Framework Emulator. First, open a command prompt and navigate to the folder where the project.json file is located in your repository. Then, run the command dotnet restore to restore the various packages that are referenced in your bot.

Note

Visual Studio 2017 changes how Visual Studio handles dependencies. While Visual Studio 2015 uses project.json to handle dependencies, Visual Studio 2017 uses a .csproj model when loading in Visual Studio. If you are using Visual Studio 2017, download this .csproj file to the /messages folder in your repository before you run the dotnet restore command.

Command prompt

Next, run debughost.cmd to load and start your bot.

Command prompt run debughost.cmd

At this point, the bot is running locally. From the console window, copy the endpoint that debughost is listening on (in this example, http://localhost:3978). Then, start the Bot Framework Emulator and paste the endpoint into the address bar of the emulator. For this example, you must also append /api/messages to the endpoint. Since you do not need security for local debugging, you can leave the Microsoft App ID and Microsoft App Password fields blank. Click Connect to establish a connection to your bot using the specified endpoint.

Configure emulator

After you have connected the emulator to your bot, send a message to your bot by typing some text into the textbox that is located at the bottom of the emulator window (i.e., where Type your message... appears in the lower-left corner). By using the Log and Inspector panels on the right side of the emulator window, you can view the requests and responses as messages are exchanged between the emulator and the bot.

test via emulator

Additionally, you can view log details in the console window.

Console window

Additional resources

Next steps