瞭解不同的 WebView2 SDK 版本

發行項
03/26/2024

WebView2 SDK 會提供為 Microsoft.Web.WebView2 NuGet 套件的發行前版本或發行版。使用發行前版本 SDK 搭配 Microsoft Edge 的預覽通道，或搭配 WebView2 運行時間使用發行 SDK。

發行前版本 如果您想要在將這些 API 的支援新增至運行時間之前測試最新的 WebView2 API，包括實驗性 API，SDK 套件會在開發期間使用。建議使用 Canary 通道，因為它具有最新 API 的實作。當您想要測試和使用實驗性 WebView2 API 時，請使用下列組合：

WebView2 SDK 的 發行前版本 。
開發用戶端上 Microsoft Edge 的 預覽通道 。

釋放 SDK 套件只包含穩定 API，而非實驗性 API。當您處理 WebView2 應用程式的生產版本時，請使用下列組合：

WebView2 SDK 的發行版。
開發用戶端上的 WebView2 運行時間 。

以下提供有關發行前版本和發行 SDK 套件的詳細數據。

引進 API 的階段

新的 API 會分階段引進，如下所示：

API 狀態	描述
實驗	1.首先，API 在發行前版本 SDK 中是實驗性的。您可以測試這些 API 並提供意見反應。 API 尚未在發行 SDK 中。
發行前版本 SDK 中的穩定	2.然後 API 會在發行前版本 SDK 中升級為穩定。 API 尚未在發行 SDK 中。
在發行 SDK 中穩定	3.然後將穩定 API 升級為包含在發行 SDK 中。這通常會在 API 升級為發行前版本 SDK 中的 Stable 1 個月後發生。 API 也會保留在發行前版本 SDK 中。

引進新 API 的階段圖

選取要使用的 SDK 類型

若要選取 Visual Studio 專案使用的 WebView2 SDK NuGet 套件版本，請在 Visual Studio 中以滑鼠右鍵單擊專案，選取 [ 管理 NuGet 套件]，選取或清除 [ 包含發行前版本 ] 複選框，選取 Microsoft.Web.WebView2 套件，然後在 [ 版本 ] 下拉式列表中選取 Microsoft.Web.WebView2 NuGet 套件的版本。

如需詳細資訊，請參閱在設定 WebView2 的開發環境中安裝或更新 WebView2 SDK。您也可以在 NuGet 網站上檢視 Microsoft.Web.WebView2 SDK 套件清單。

使用 SDK 發行前版本以及 Microsoft Edge 的預覽通道

開發 Evergreen WebView2 應用程式時，除了針對 WebView2 運行時間進行測試之外，還會定期針對最新的 Microsoft Edge 預覽通道測試應用程式。因為 Web 平台不斷演進，所以定期測試是確保您的應用程式能繼續如預期般運作的最佳方式。

當您使用 WebView2 發行前版本 SDK 套件時，請在開發用戶端上使用 Microsoft Edge 預覽通道。預覽頻道也稱為 測試人員 通道。 Canary 預覽通道是建議的，而不是 Beta 或 Dev，因為 Canary 是最新的，且具有最新實驗性 API 的實作。

發行前版本 SDK 套件是發行 SDK 套件的超集。發行前版本 SDK 包含下列方法簽章：

實驗性 API。
已不再是實驗性，但尚未包含在發行 SDK 中的穩定 API。
已新增至發行 SDK 的穩定 API。

Microsoft Edge 的預覽通道提供實驗性 WebView2 API 和穩定 API 的實作。實驗性 API 可能會根據意見反應而變更。避免使用發行前版本 SDK 套件來建置生產應用程式。

如需暫時將您的應用程式指向預覽通道，而不是預設為 WebView2 運行時間的相關信息，請參閱測試即將推出的 API 和功能。

另請參閱:

搭配運行時間使用 SDK 的發行版

當您使用 WebView2 版本 SDK 套件時，請在開發用戶端上使用 Evergreen WebView2 運行時間 ，而不是 Microsoft Edge 預覽通道。根據預設，WebView2 應用程式會以運行時間為目標，而不是以 Microsoft Edge 為目標。根據設計，Microsoft Edge 穩定通道不支援 WebView2。

發行 SDK 套件包含生產版本中的所有穩定 Win32 C/C++ 和 .NET API，不包含實驗性 API 的方法簽章。在 WebView2 運行時間的相同或更高組建編號中，完全支援發行 SDK 套件中的所有 API。

Release SDK 套件包含下列元件：

Win32 C/C++ API。
.NET API： WPF、 WinForms 和 Core。

如需自動更新 Evergreen 執行時間的詳細資訊，請參閱散發您的應用程式和 WebView2 運行時間。

發行頻率

新版本的 WebView2 SDK 會以與 Microsoft Edge 瀏覽器相同的一般頻率出貨，大約每四週一次。

用來具現化 WebView2 的最小版本和組建編號

若要讓客戶端能夠建立 WebView2 實例，並使用 WebView2 正式運作版本中的 API 集合 (SDK 組建 616) ，客戶端必須具有 WebView2 運行時版本 86.0.616.0 或更新版本。運行時間 86.0.616.0 是特殊版本，因為它是正式發行版。

在開發計算機上，客戶端必須具有 Microsoft Edge 預覽通道 86.0.616.0 版或更新版本，或 WebView2 運行時間 86.0.616.0 版或更高版本。

API 的向前相容性

自 WebView2 SDK) 的封存版本資訊中第 1 版 (版本 SDK 1.0.622.22 以來 ，WebView2 版本 SDK 一直向前相容。您可以更新 WebView2 應用程式，以使用最新版本 SDK 的最新 API。您的應用程式會繼續在用戶端上運作，因為用戶端會自動擁有最新的 Evergreen WebView2 運行時間。

發行 SDK 套件中的 WebView2 API 是穩定且向前相容的。 WebView2 API 可在使用組建編號等於或更高的WebView2運行時間作為引進 API 的 SDK 組建編號時運作。組建編號是 Webview2 SDK 四部分版本號碼的第三個部分，以及 Microsoft Edge 和 WebView2 運行時間的四部分版本號碼的第三個部分。

當您使用組建編號 等於或小於 WebView2 執行時間的 WebView2 SDK 時，您在該 SDK 中可存取的每個 API 都會與該版本的運行時間搭配運作。
當您使用組建編號大於 WebView2 運行時間的 WebView2 SDK 時，運行時間中無法使用較新的 API 實作。

例如，如果 API 是在 SDK 1.0 中引進。900.0，該 API 可搭配運行時間 94.0 運作。900+.0，但不含運行時間 90.0。700.0。

您必須協調用於開發的 WebView2 SDK 版本，以及安裝在用戶端電腦上的 WebView2 運行時版本。客戶端應該有一個運行時間版本，其支援您用來開發應用程式之 SDK 版本中的所有最新 API。若要完整支援 SDK 發行版中的最新 API，用戶端上的運行時間必須具有大於或等於 SDK 組建編號的組建編號。

實驗性 API

若要試用即將開發的新功能，請使用 實驗性 API。實驗性 API 包含在發行前版本 SDK 中，但不包含在發行 SDK 中。

使用實驗性 API 進行開發並提供意見反應

WebView2 發行前版本 SDK 套件中的實驗性 API 不保證會向前相容，而且在未來的運行時間更新中可能會移除。

如需實驗性 API 的完整支援，請使用 Microsoft Edge 預覽通道，而不是 Evergreen WebView2 運行時間。一開始提供 WebView2 SDK 發行前版本時，該 SDK 僅適用於 Microsoft Edge Canary。不久之後，發行前版本 SDK 也會與 Beta 和 Dev 通道搭配運作。

使用發行前版本 SDK 來及早試用新的實驗性 API，並在將實驗性 API 升級為穩定、順向相容的 API 之前提供意見反應。

發行前版本 SDK) 中 (的實驗性 API 不保證會向前相容。
發行前版本 SDK 中的穩定 API 是向前相容的，即使它們尚未包含在發行 SDK 中也一樣。
發行 SDK 中的穩定 API 是向前相容的。

如需詳細資訊，請參閱上述 API 的轉送相容性。

WebView2 小組正尋求有關實驗性 WebView2 API 的意見反應，這些 API 可能會在未來版本中升級為穩定。在 WebView2 SDK 參考檔中，實驗性 API 會指出為「實驗性」，例如：「注意：這是隨附於發行前版本 SDK 的實驗性 API」。

若要協助您評估實驗性 API 並分享您的意見反應，請使用 WebView2Feedback 存放庫。

從實驗性 API 移至穩定 API

一旦 API 從實驗性狀態移至穩定狀態，您必須將應用程式的程式代碼移至穩定 API。不建議針對生產應用程式使用實驗性 API 或發行前版本 SDK。將應用程式從使用實驗性 API 移至使用穩定 API 時，請遵循下列做法：

在 Visual Studio 的專案中，將 WebView2 SDK 套件版本更新為較新的發行前版本 SDK 或版本 SDK。請參閱在設定 WebView2 的開發環境中安裝或更新 WebView2 SDK。
更新應用程式的程序代碼，以使用穩定 API，而非 COM) 的實驗性 API (。穩定 API 將會受到錯誤修正的支援，但實驗性 API 將會被取代，且無法在較新的 (發行前版本或發行) SDK 中使用。將 API 升級為穩定之後，處於已淘汰狀態的兩個發行前版本 SDK 支援該 API 的實驗性版本。在後續版本的發行前版本 SDK 中，可能會修改、移除或新增實驗性 API。
請一律使用功能偵測，以確保穩定 API 是在使用者的 WebView2 運行時間版本中實作。請參閱功能偵測，以測試已安裝的運行時間是否支援最近新增的 API，如下所示。
僅適用於 .NET 的注意事項：在發行前版本 WebView2 SDK 中，如果使用者的 WebView2 運行時間只有實驗性 API 實作，而且沒有穩定 API 實作，則 .NET Stable API 會後援至對應的實驗性 API。

比對運行時版本與 SDK 版本

在 Evergreen 散發方法中，用戶端的 WebView2 運行時間會自動更新為可用的最新版本。不過，使用者或IT系統管理員可能會選擇防止自動更新WebView2運行時間。在用戶端上產生過時的運行時間，可能會導致更新的 WebView2 應用程式使用來自最近 SDK 之新 API 的相容性問題。

如果客戶端上無法更新 WebView2 運行時間，請確定您知道應用程式所需的 WebView2 運行時間組建編號下限。若要檢視或取得最新的 WebView2 運行時間版本，請參閱下載 Microsoft Edge WebView2 頁面中的 WebView2 運行時間，網 developer.microsoft.com。支援 SDK (組建 616) 正式運作版本的最低必要運行時版本，比最新的運行時間還舊。最新的運行時間支援最新版本 SDK 中的所有 API。

若要檢查 SDK 的特定組建編號與運行時間或 Microsoft Edge 預覽通道之間的相容性，請參閱 WebView2 SDK 的版本資訊。

功能偵測，以測試已安裝的運行時間是否支援最近新增的 API

如果您的應用程式使用 Evergreen 執行時間，而不是固定版本，您應該使用 QueryInterface 或 try-catch，將任何呼叫包裝到相對較新的 WebView2 API。在某些邊緣案例中，用戶端的 Evergreen 運行時間不是最新的組建，因此會落後 SDK 組建編號，因為管理員可能已關閉 WebView2 運行時間的更新，或用戶端可能脫機。

當您使用最新版本的 WebView2 SDK 開發 WebView2 應用程式時，如果您使用最近新增的 API，您應該測試或「功能偵測」該 API 是否存在於用戶端安裝的 WebView2 運行時間中。您的應用程式如何以程式設計方式測試 API 支援，取決於編碼平臺。

Win32 C/C++。要求 DLL 匯出CreateCoreWebView2Environment時，以及在任何CoreWebView2物件上執行QueryInterface時，請測試的E_NOINTERFACE傳回值。該傳回值可能表示用戶端的 WebView2 運行時間是不支援該介面的較舊版本。

如需檢查執行時間中特定 WebView2 API 是否存在的範例，請在 AppWindow.cpp 中尋找 try_query 。此檔案會將 WebView2 API 呼叫包裝在宏函式中 CHECK_FAILURE ，定義於 CheckFailure.h。
.NET 和 WinUI。使用新增至較新版本 WebView2 SDK 的方法、屬性和事件時，請使用 try/catch 並檢查 No such interface supported 是否有例外狀況。此例外狀況可能表示用戶端的 WebView2 運行時間是不支援該 API 的較舊版本。

如果您的程式代碼判斷用戶端安裝的 WebView2 執行時間中無法使用 API，您應該提供相關聯功能的正常後援，或通知使用者必須更新 WebView2 運行時間才能使用此功能。

這項技術會在測試已安裝的 WebView2 運行時間是否支援 API 中列為 WebView2 開發最佳做法。