Debug an SDK-first bot

Article
2024-12-19

APPLIES TO: SDK v4

This article describes how to debug your bot using an IDE, such as Visual Studio or Visual Studio Code, and the Bot Framework Emulator. Use these methods to debug a bot locally. This article uses an echo bot, such as the one created in the Create a bot quickstart.

Note

In this article, we use the Bot Framework Emulator to send and receive messages from the bot during debugging. If you're looking for other ways to debug your bot using the Bot Framework Emulator, please read the Debug with the Bot Framework Emulator article.

Note

To build agents with your choice of AI services, orchestration, and knowledge, consider using the Microsoft 365 Agents SDK. The Agents SDK has support for C#, JavaScript or Python. You can learn more about the Agents SDK at aka.ms/agents. If you're looking for a SaaS-based agent platform, consider Microsoft Copilot Studio. If you have an existing bot built with the Bot Framework SDK, you can update your bot to the Agents SDK. You can review the core changes and updates at Bot Framework SDK to Agents SDK migration guidance. Support tickets for the Bot Framework SDK will no longer be serviced as of December 31, 2025.

Prerequisites

Download and install the Bot Framework Emulator.
Download and install Visual Studio Code or Visual Studio.

Set C# 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 Visual Studio Code, do the following:

Launch Visual Studio Code and open your bot project folder.
Set breakpoints as necessary. To set a breakpoint, hover your mouse over the column to the left of the line numbers. A small red dot will appear. If you select the dot, the breakpoint is set. If you select the dot again, the breakpoint is removed.
From the menu bar, select Run, then Start Debugging. Your bot will start running in debugging mode from the Terminal in Visual Studio Code.
Start the Bot Framework Emulator and connect to your bot as described in how to Debug with the Bot Framework Emulator.
From the Emulator, send your bot a message (for example, send the message "Hi"). Execution will stop at the line where you place the breakpoint.

Set C# breakpoints in Visual Studio

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

Navigate to your bot folder and open the .sln file. This will open the solution in Visual Studio.
From the menu bar, select Build and select Build Solution.
In the Solution Explorer, select the .cs file and set breakpoints as necessary. This file defines your main bot logic. To set a breakpoint, hover your mouse over the column to the left of the line numbers. A small dot will appear. If you select the dot, the breakpoint is set. If you select the dot again, the breakpoint is removed.
From the menu, select Debug, then Start Debugging. At this point, the bot is running locally.
Start the Bot Framework Emulator and connect to your bot as described in the section above.
From the Emulator, send your bot a message, such as "Hi". Execution will stop at the line where you place the breakpoint.

Set Java 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. See also Create a bot with the Bot Framework SDK for Java.

Install the Java Extension Pack in Visual Studio Code, if you haven't already done so. This extension provides rich support for Java in Visual Studio Code, including debugging.
Launch Visual Studio Code and open your bot project folder.
Set breakpoints as necessary. To set a breakpoint, hover your mouse over the column to the left of the line numbers. A small red dot will appear. If you select the dot, the breakpoint is set. If you select the dot again, the breakpoint is removed.
Select the EchoBot.java file and add a breakpoint to a desired ___location.
From the menu bar, select Run and then select Start Debugging.
Select Java if prompted to debug the currently selected file.
Start the Bot Framework Emulator and connect to your bot as described in the Debug with the Bot Framework Emulator article.
From the Emulator, send your bot a message (for example, send the message "Hi"). Execution will stop at the line where you place the breakpoint.

For more information, see Running and debugging Java.

Set Python 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. See also Create a bot with the Bot Framework SDK for Python.

Install the Python extension in Visual Studio Code, if you haven't already done so. This extension provides rich support for Python in Visual Studio Code, including debugging.
Launch Visual Studio Code and open your bot project folder.
Set breakpoints as necessary. To set a breakpoint, hover your mouse over the column to the left of the line numbers. A small red dot will appear. If you select the dot, the breakpoint is set. If you select the dot again, the breakpoint is removed.
Select the app.py file.
From the menu bar, select Debug and then select Start Debugging.
Select Python File to debug the currently selected file.
Start the Bot Framework Emulator and connect to your bot as described in the Debug with the Bot Framework Emulator article.
From the Emulator, send your bot a message (for example, send the message "Hi"). Execution will stop at the line where you place the breakpoint.

For more information, see Debug your Python code.

Additional resources

Troubleshoot bot configuration issues and the other troubleshooting articles in that section.
Debug with the Emulator.

Next steps

Debug your bot using transcript files.

Share via

Set C# breakpoints in Visual Studio Code

Set C# breakpoints in Visual Studio

Set JavaScript breakpoints in Visual Studio Code

Set Java breakpoints in Visual Studio Code

Set Python breakpoints in Visual Studio Code