Migration overview

The Bot Framework SDK v4 builds on the customers' feedback and learning experience from previous SDKs. The new version introduces the right levels of abstraction while enabling a flexible architecture of the bot components. This, for example, allows you to create a simple bot and then expand it in sophistication using the modularity and extensibility of the Bot Framework SDK v4.


The Bot Framework SDK v4 strives to keep simple things simple and makes complex things possible.

An open approach has been adopted so that the Bot Framework v4 SDK has been built with the cooperation from the community. When you first submit a Pull Request, a Contributor License Agreement (CLA) automatically determines whether you need a license. You will only need to do this once across all repositories. Typically, there is a time interval to establish a set of objectives to achieve.

What happens to bots built using SDK v3

The Bot Framework SDK v3 will be retired but existing V3 bot workloads will continue to run without interruption. For more information, see: Bot Framework SDK Version 3 Lifetime Support.

We highly recommend that you start migrating your V3 bots to V4. In order to support this migration we have produced related documentation and will provide extended support for migration initiatives via standard channels.

If you can not migrate from a v3 bot to a v4 bot immediately, you may still want to take advantage of the additional functionality available in the v4 SDK. You can convert your v3 bot to a skill, and create a skill consumer bot based on the v4 SDK to pass messages to your v3 bot. For more information, see how to convert a v3 bot to a skill.


  • Richer, flexible and open architecture: Enables more flexible conversations design
  • Availability: Introduces additional scenarios with new channel capabilities
  • Expanded Subject Matter Expert (SME) personnel in the development cycle: New GUI designer permits non-developers to collaborate on conversation design
  • Development velocity: New debugging and testing developer tools
  • Performance insights: New telemetry features to evaluate and improve conversation quality
  • Intelligence: Improved cognitive services capabilities

Why migrate

  • Flexible and improved conversation management
    • Bot Adapter for activity processing
    • Refactored state management
    • New dialogs library
    • Middleware for composable and extensible designs: Clean and consistent hooks to customize behavior
  • Built for .NET Core
    • Improved performance
    • Cross platform compatibility (Windows/Mac/Linux)
  • Consistent programming model across multiple programming languages
  • Improved documentation
  • Bot Inspector provides extended debugging capabilities
  • Virtual Assistant
    • Comprehensive solution that simplifies the creation of bots with basic conversational intents, Dispatch integration, QnA Maker, Application Insights and an automated deployment.
    • Extensible Skills. Compose conversational experiences by stitching together re-usable conversational capabilities, known as Skills.
  • Testing Framework: Out of the box test capabilities with new transport independent adaptor architecture
  • Telemetry: Gain key insights into your bot’s health and behavior with the Conversational AI Analytics
  • Coming (preview)
    • Adaptive Dialogs: Build conversations that can be dynamically changed as the conversation progresses
    • Language Generation: Define multiple variations on a phrase
  • Future
    • Declarative design permits level of abstraction for designers
    • GUI Dialog Designer
  • Azure Bot Service
    • Direct Line Speech Channel. Bringing together the Bot Framework and Microsoft's Speech Services. This provides a channel that enables streamed speech and text bi-directionally from the client to the bot application

What's changed

The Bot Framework SDK v4 supports the same underlying Bot Framework Service as v3. However, v4 is a refactoring of the previous SDKs to allow more flexibility and control over a bot's creation. This includes the following:

  • Introduced a bot adapter
    • The adapter is part of the activity processing stack
    • It handles Bot Framework authentication and initializes context for each turn
    • It manages incoming and outgoing traffic between a channel and your bot's turn handler, encapsulating the calls to the Bot Framework Connector service
    • For more details, see How bots work
  • Refactored state management
    • State data is no longer automatically available within a bot
    • State is now managed via state management objects and property accessors
    • For more details, see Managing state
  • Introduced new Dialogs library
    • v3 dialogs need to be rewritten for the new dialog library
    • For more details, see Dialogs library

What's involved in migration work

  • Update setup logic
  • Port any critical user state
    • Note: sensitive user state cannot be kept in a bot state, instead store in separate storage under your control
  • Port bot and dialog logic (see language-specific topics for more details)

Migration estimation worksheet

The following worksheets can guide you in estimating your migration workload. In the Occurrences column replace count with your actual numeric value. In the T Shirt column enter values such as: Small, Medium, Large based on your estimation.

Step V3 V4 Occurrences Complexity T Shirt
To get the incoming activity IDialogContext.Activity ITurnContext.Activity count Small
To create and send an activity to the user activity.CreateReply(“text”) IDialogContext.PostAsync MessageFactory.Text(“text”) ITurnContext.SendActivityAsync count Small
State management UserData, ConversationData, and PrivateConversationData context.UserData.SetValue context.UserData.TryGetValue botDataStore.LoadAsyn UserState, ConversationState, and PrivateConversationState With property accessors context.UserData.SetValue - count context.UserData.TryGetValue - count botDataStore.LoadAsyn - count Medium to Large (See user state management available)
Handle the start of your dialog Implement IDialog.StartAsync Make this the first step of a waterfall dialog. count Small
Send an activity IDialogContext.PostAsync. Call ITurnContext.SendActivityAsync. count Small
Wait for a user's response Use an IAwaitableparameter and call IDialogContext.Wait Return await ITurnContext.PromptAsync to begin a prompt dialog. Then retrieve the result in the next step of the waterfall. count Medium (depends on flow)
Handle continuation of your dialog IDialogContext.Wait Add additional steps to a waterfall dialog, or implement Dialog.ContinueDialogAsync count Large
Signal the end of processing until the user's next message IDialogContext.Wait Return Dialog.EndOfTurn. count Medium
Begin a child dialog IDialogContext.Call Return await the step context's BeginDialogAsyncmethod. If the child dialog returns a value, that value is available in the next step of the waterfall via the step context's Resultproperty. count Medium
Replace the current dialog with a new dialog IDialogContext.Forward Return await ITurnContext.ReplaceDialogAsync. count Large
Signal that the current dialog has completed IDialogContext.Done Return await the step context's EndDialogAsync method. count Medium
Fail out of a dialog. IDialogContext.Fail Throw an exception to be caught at another level of the bot, end the step with a status of Cancelled, or call the step or dialog context's CancelAllDialogsAsync. count Small

The Bot Framework SDK v4 is based on the same underlying REST API as v3. However, v4 is a refactoring of the previous version of the SDK to allow more flexibility and control over the bots.

We recommend migrating to .NET Core, since the performance is very much improved. However, some existing V3 bots are using external libraries that do not have a .NET Core equivalent. In this case, the Bot Framework SDK v4 can be used with .NET Framework version 4.6.1 or higher. You can find an example at corebot location.

When migrating a project from v3 to v4, you can choose one of these options: convert in place for .NET Framework or port to a new project for .NET Core.

.NET Framework

  • Update and install NuGet packages
  • Update your Global.asax.cs file
  • Update your MessagesController class
  • Convert your dialogs

For more information, see Migrate a .NET v3 bot to a .NET Framework v4 bot.

.NET Core

  • Create the new project using a template


Both .NET Core 2.1 and .NET Core 3.1 versions of the C# templates are available. When creating new bots in Visual Studio 2019, you should use the .NET Core 3.1 templates. The current bot samples use .NET Core 3.1 templates. You can find the samples that use .NET Core 2.1 templates in the 4.7-archive branch of the BotBuilder-Samples repository. For information about deploying .NET Core 3.1 bots to Azure, see Deploy your bot.

  • Install additional NuGet packages as necessary
  • Personalize your bot, update your Startup.cs file, and update your controller class
  • Update your bot class
  • Copy over and update your dialogs and models

For more information, see Migrate a .NET v3 bot to a .NET Core v4 bot.

Additional resources

The following additional resources provide more information that can help during the migration.

The following topics describe the differences between .NET v3 and v4 Bot Framework SDKs, the major changes between the two versions, and the steps to migrate a bot from v3 to v4.

Topic Description
Differences between the v3 and v4 .NET SDK Common differences between v3 and v4 SDKs
.NET migration quick reference Major changes in v3 vs v4 SDKs
Migrate a .NET v3 bot to a Framework v4 bot Migrate a v3 to a v4 bot using the same project type
Migrate a .NET v3 bot to a Core v4 bot Migrate a v3 to a v4 bot in a new .NET Core project

Code samples

The following are code samples you can use to learn the Bot Framework SDK V4 or jump start your project.

Samples Description
Bot Framework Migration from V3 to V4 Samples Migration samples from Bot Framework V3 SDK to V4 SDK
Bot Builder .NET Samples Bot builder C# .NET core samples
Bot Builder JavaScript Samples Bot builder JavaScript (node.js) samples
Bot Builder All Samples Bot builder all samples

Getting help

The following resources provide additional information and support for developing bots.

Bot Framework additional resources


Please, refer to the following resources for more details and background information.

Topic Description
What's new in Bot Framework Bot Framework and Azure Bot Service key features and improvements
How bots work The internal mechanism of a bot
Managing state Abstractions to make state management easier
Dialogs library Central concepts to manage a conversation
Send and receive text messages Primary way a bot communicate with users
Send Media Media attachments, such as images, video, audio, and files
Sequential conversation flow Questioning as the main way a bot interacts with users
Save user and conversation data Tracking a conversation while stateless
Complex Flow Manage complex conversation flows
Reuse Dialogs Create independent dialogs to handle specific scenarios
Interruptions Handling interruptions to create a robust bot
Activity Schema Schema for humans and automated software