移轉概觀Migration overview


Bot Framework SDK v4 建基於客戶的意見反應和先前 Sdk 的學習體驗。The Bot Framework SDK v4 builds on customers' feedback and the learning experience from previous SDKs. 它引進了適當的抽象層級,同時啟用彈性的 bot 元件架構。It introduces the right levels of abstraction while enabling a flexible bot components architecture. 此外,這可讓您建立簡單的 bot,然後使用 Bot Framework SDK v4 的模組化和擴充性來擴展其複雜程度。Among other things, this allows you to create a simple bot and then expand its sophistication using the modularity and extensibility of the Bot Framework SDK v4.


Bot Framework SDK v4 致力於讓簡單的事情保持簡單,並讓複雜的事情得以實現。The Bot Framework SDK v4 strives to keep simple things simple and makes complex things possible.

由於採用了開放式方法,Bot Framework SDK v4 是透過與社群合作而建置起來的。An open approach has been adopted so that the Bot Framework v4 SDK has been built with the cooperation from the community. 首次提交提取要求時,參與者授權合約 (CLA) 會自動判斷您是否需要授權。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.

使用 SDK v3 所建置的聊天機器人會發生什麼事What happens to bots built using SDK v3

Bot Framework SDK v3 將會淘汰,但現有的 V3 聊天機器人工作負載會繼續執行而不會中斷。The Bot Framework SDK v3 will be retired but existing V3 bot workloads will continue to run without interruption. 如需詳細資訊,請參閱Bot Framework SDK 第 3 版存留期支援For more information, see: Bot Framework SDK Version 3 Lifetime Support.

強烈建議您開始將 V3 聊天機器人遷移至 V4。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.

如果您無法立即從 v3 Bot 遷移至 v4 Bot,但您仍想要使用 v4 SDK 中提供的其他功能。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. 您可以將 v3 Bot 轉換成技能並建立以 v4 SDK 為基礎的技能取用者 Bot,來將訊息傳遞至 v3 Bot。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. 如需詳細資訊,請參閱如何將 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
  • 在開發週期擴充了主題專家 (SME) 人員:新的 GUI 設計工具可讓非開發人員針對對話設計進行共同作業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
  • 針對 .NET Core 來建置Built for .NET Core
    • 提升效能Improved performance
    • 跨平台相容性 (Windows/Mac/Linux)Cross platform compatibility (Windows/Mac/Linux)
  • 跨多種程式設計語言的一致程式設計模型Consistent programming model across multiple programming languages
  • 經過改善的文件Improved documentation
  • Bot Inspector 會提供已擴充的偵錯功能Bot Inspector provides extended debugging capabilities
  • 虛擬小幫手Virtual Assistant
    • 全方位的解決方案,可讓您更容易地建立有基本對話式意圖、分派整合、QnA Maker、Application Insights 和自動化部署的聊天機器人。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
  • 遙測:利用對話式 AI 分析,讓您的 bot 健康情況和行為達到重要見解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 對話設計工具GUI Dialog Designer
  • Azure Bot 服務Azure Bot Service
    • Direct Line Speech 通道。Direct Line Speech Channel. 結合 Bot Framework 和 Microsoft 的語音服務。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

Bot Framework SDK v4 支援與 v3 相同的基礎 Bot Framework Service。The Bot Framework SDK v4 supports the same underlying Bot Framework Service as v3. 不過,v4 是舊版 SDK 的重構,目的是為了提升聊天機器人的建立彈性和控制力。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
    • 其會處理 Bot Framework 驗證,並為每個回合初始化內容It handles Bot Framework authentication and initializes context for each turn
    • 其會管理通道和聊天機器人回合處理常式之間的傳入和傳出流量,並封裝對 Bot Framework 連接器服務的呼叫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
    • 狀態資料不再於 Bot 內自動提供使用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 對話需要針對新的對話程式庫重新撰寫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. 在 [發生次數] 資料行中,將 count 取代為實際數值。In the Occurrences column replace count with your actual numeric value. 在 [T 恤] 資料行中,輸入如下的值:(視您的評估而定)。In the T Shirt column enter values such as: Small, Medium, Large based on your estimation.

步驟Step V3V3 V4V4 發生次數Occurrences 複雜度Complexity T 恤T Shirt
若要取得連入活動To get the incoming activity IDialogContext.ActivityIDialogContext.Activity ITurnContext.ActivityITurnContext.Activity countcount 小型Small
若要建立活動並傳送給使用者To create and send an activity to the user 活動。CreateReply ( "text" ) IDialogCoNtext. PostAsyncactivity.CreateReply("text") IDialogContext.PostAsync MessageFactory: Text ( "text" ) >iturncoNtext. SendActivityAsyncMessageFactory.Text("text") ITurnContext.SendActivityAsync countcount 小型Small
狀態管理State management UserData、ConversationData 和 PrivateConversationData context.UserData.SetValue context.UserData.TryGetValue botDataStore.LoadAsynUserData, ConversationData, and PrivateConversationData context.UserData.SetValue context.UserData.TryGetValue botDataStore.LoadAsyn UserState、ConversationState 和 PrivateConversationState (含屬性存取子)UserState, ConversationState, and PrivateConversationState With property accessors context.UserData.SetValue - count context.UserData.TryGetValue - count botDataStore.LoadAsyn - countcontext.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.StartAsyncImplement IDialog.StartAsync 讓此項成為瀑布式對話的第一個步驟。Make this the first step of a waterfall dialog. countcount 小型Small
傳送活動Send an activity IDialogContext.PostAsync.IDialogContext.PostAsync. Call ITurnContext.SendActivityAsync.Call ITurnContext.SendActivityAsync. countcount 小型Small
等候使用者回應Wait for a user's response 使用 IAwaitableparameter 參數並呼叫 IDialogContext.WaitUse an IAwaitableparameter and call IDialogContext.Wait 傳回等候 ITurnContext.PromptAsync 以開始提示對話方塊。Return await ITurnContext.PromptAsync to begin a prompt dialog. 然後在瀑布的下一個步驟中擷取結果。Then retrieve the result in the next step of the waterfall. countcount 中 (視流程而定)Medium (depends on flow)
處理對話的接續Handle continuation of your dialog IDialogContext.WaitIDialogContext.Wait 在瀑布式對話方塊中新增其他步驟,或實作 Dialog.ContinueDialogAsyncAdd additional steps to a waterfall dialog, or implement Dialog.ContinueDialogAsync countcount 大型Large
表示在使用者的下一則訊息前處理結束Signal the end of processing until the user's next message IDialogContext.WaitIDialogContext.Wait 傳回 Dialog.EndOfTurn。Return Dialog.EndOfTurn. countcount Medium
開始子對話Begin a child dialog IDialogContext.CallIDialogContext.Call 傳回等候步驟內容的 BeginDialogAsyncmethod。Return await the step context's BeginDialogAsyncmethod. 如果子對話方塊傳回值,該值可透過步驟內容的 Resultproperty 用於瀑布的下一個步驟。If the child dialog returns a value, that value is available in the next step of the waterfall via the step context's Resultproperty. countcount Medium
以新對話取代目前的對話Replace the current dialog with a new dialog IDialogContext.ForwardIDialogContext.Forward 傳回等候 ITurnContext.ReplaceDialogAsync。Return await ITurnContext.ReplaceDialogAsync. countcount 大型Large
表示目前對話已完成的訊號Signal that the current dialog has completed IDialogContext.DoneIDialogContext.Done 傳回等候步驟內容的 EndDialogAsync 方法。Return await the step context's EndDialogAsync method. countcount Medium
對話失敗。Fail out of a dialog. IDialogContext.FailIDialogContext.Fail 擲回要在聊天機器人的另一個層級攔截的例外狀況、結束狀態為「已取消」的步驟,或呼叫該步驟或對話內容的 CancelAllDialogsAsync。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. countcount 小型Small

Bot Framework SDK v4 是以與 v3 相同的基礎 REST API 作為基礎。The Bot Framework SDK v4 is based on the same underlying REST API as v3. 不過,v4 是舊版 SDK 的重構,目的是為了提升聊天機器人的彈性和控制力。However, v4 is a refactoring of the previous version of the SDK to allow more flexibility and control over the bots.

建議您遷移至 .NET Core,其效能已有極大改善。We recommend migrating to .NET Core, since the performance is very much improved. 不過,某些現有的 V3 聊天機器人會使用沒有對等 .NET Core 的外部程式庫。However, some existing V3 bots are using external libraries that do not have a .NET Core equivalent. 在此情況下,Bot Framework SDK v4 可以與 .NET Framework 版本4.6.1 或更新版本搭配使用。In this case, the Bot Framework SDK v4 can be used with .NET Framework version 4.6.1 or later. 您可以在 corebot 位置中找到範例。You can find an example at corebot location.

將專案從 v3 遷移至 v4 時,您可以選擇下列其中一個選項:就地轉換為 .NET Framework 或植入到適用於 .NET Core 的新專案。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.NET Framework

  • 更新和安裝 NuGet 套件Update and install NuGet packages
  • 更新 Global.asax.cs 檔案Update your Global.asax.cs file
  • 更新 MessagesController 類別Update your MessagesController class
  • 轉換您的對話Convert your dialogs

如需詳細資訊,請參閱將 .NET v3 聊天機器人遷移至 .NET Framework v4 聊天機器人For more information, see Migrate a .NET v3 bot to a .NET Framework v4 bot.

.NET Core.NET Core

  • 使用範本建立新專案Create the new project using a template


VSIX封裝包含 .net core 2.1 和 .net core 3.1 版本的 c # 範本。The VSIX package includes both .NET Core 2.1 and .NET Core 3.1 versions of the C# templates. 在 Visual Studio 2019 中建立新的 Bot 時,您應該使用 .NET Core 3.1 範本。When creating new bots in Visual Studio 2019, you should use the .NET Core 3.1 templates. 目前的 Bot 範例會使用 .NET Core 3.1 範本。The current bot samples use .NET Core 3.1 templates. 您可以在 BotBuilder-Samples 存放庫的 4.7-archive 分支中,找到使用 .NET Core 2.1 範本的範例。You can find the samples that use .NET Core 2.1 templates in the 4.7-archive branch of the BotBuilder-Samples repository. 如需將 .NET Core 3.1 bot 部署至 Azure 的詳細資訊,請參閱如何將 您的 bot 部署至 azureFor information about deploying .NET Core 3.1 bots to Azure, see how to deploy your bot to Azure.

  • 視需要安裝其他 NuGet 套件Install additional NuGet packages as necessary
  • 將聊天機器人個人化、更新 Startup.cs 檔案,然後更新控制器類別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

如需詳細資訊,請參閱將 .NET v3 聊天機器人遷移至 .NET Core v4 聊天機器人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.

下列主題說明 .NET v3 和 v4 Bot Framework SDK 之間的差異、兩個版本之間的重大變更,以及要將聊天機器人從 v3 遷移至 v4 的步驟。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
v3 和 v4.NET SDK 之間的差異Differences between the v3 and v4 .NET SDK v3 和 v4 SDK 之間的常見差異Common differences between v3 and v4 SDKs
.NET 移轉快速參考.NET migration quick reference v3 和 v4 SDK 之間的重大變更Major changes in v3 vs v4 SDKs
將 .NET v3 bot 遷移至 Framework v4 botMigrate a .NET v3 bot to a Framework v4 bot 使用相同的專案類型從 v3 遷移至 v4 聊天機器人Migrate a v3 to a v4 bot using the same project type
將 .NET v3 聊天機器人遷移至 Core v4 聊天機器人Migrate a .NET v3 bot to a Core v4 bot 在新的 .NET Core 專案中將聊天機器人從 v3 遷移至 v4Migrate a v3 to a v4 bot in a new .NET Core project

程式碼範例Code samples

以下程式碼範例可讓您了解 Bot Framework SDK V4 或快速啟動您的專案。The following are code samples you can use to learn the Bot Framework SDK V4 or jump start your project.

範例Samples 描述Description
Bot Framework 從 V3 到 V4 的移轉範例Bot Framework Migration from V3 to V4 Samples 從 Bot Framework V3 SDK 到 V4 SDK 的移轉範例Migration samples from Bot Framework V3 SDK to V4 SDK
Bot Builder .NET 範例Bot Builder .NET Samples Bot Builder C# .NET core 範例Bot builder C# .NET core samples
Bot Builder JavaScript 範例Bot Builder JavaScript Samples Bot Builder JavaScript (node.js) 範例Bot builder JavaScript (node.js) samples
Bot Builder 所有範例Bot Builder All Samples Bot Builder 所有範例Bot builder all samples

取得說明Getting help

下列資源提供了用於開發聊天機器人的其他資訊和支援。The following resources provide additional information and support for developing bots.

Bot Framework 其他資源Bot Framework additional resources


請參閱下列資源以取得詳細資料和背景資訊。Please, refer to the following resources for more details and background information.

主題Topic 描述Description
Bot Framework 中的新功能What's new in Bot Framework Bot Framework 和 Azure Bot 服務的重要功能和改進Bot Framework and Azure Bot Service key features and improvements
Bot 的運作方式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