Пакеты SDK для предварительной версии и выпуска для WebView2

Пакет SDK для WebView2 предоставляется в виде предварительной версии или выпуска пакета NuGet Microsoft.Web.WebView2 . Используйте пакет SDK предварительной версии с каналом предварительной версии Microsoft Edge или используйте пакет SDK для выпуска со средой выполнения WebView2.

Предварительных Пакеты SDK можно использовать во время разработки, если вы хотите протестировать последние API WebView2, включая экспериментальные API, до добавления поддержки этих API в среду выполнения. Рекомендуется использовать канал Canary, так как он содержит реализации последних API. Если вы хотите протестировать и использовать экспериментальные API WebView2, используйте следующую комбинацию:

• Предварительная версия пакета SDK для WebView2.
• Канал предварительной версии Microsoft Edge в клиенте разработки.

Отпускать Пакеты SDK содержат только стабильные API, но не экспериментальные API. При работе над рабочим выпуском приложения WebView2 используйте следующую комбинацию:

• Версия пакета SDK для WebView2.
• Среда выполнения WebView2 в клиенте разработки.

Дополнительные сведения о пакетах SDK для предварительной версии и выпуска приведены ниже.

Этапы внедрения API

Новые API-интерфейсы внедряются поэтапно следующим образом:

Состояние API	Описание
Экспериментальный	1. Сначала API является экспериментальным в предварительном пакете SDK. Вы можете протестировать эти API и предоставить отзыв. API еще не в пакете SDK выпуска.
Стабильная в предварительной версии пакета SDK	2. После этого в пакете SDK предварительной версии API будет повышен до стабильного. API еще не в пакете SDK выпуска.
Стабильный в пакете SDK для выпуска	3. Затем стабильный API будет повышен до включения в пакет SDK выпуска. Обычно это происходит через 1 месяц после повышения уровня API до стабильного в предварительном пакете SDK. API также остается в предварительном пакете SDK.

Выбор типа пакета SDK для использования

Чтобы выбрать версию пакета NuGet пакета NuGet пакета Пакета NuGet для WebView2 для пакета Visual Studio, в Visual Studio щелкните проект правой кнопкой мыши, выберите Управление пакетами NuGet, установите или снимите флажок Включить предварительную версию , выберите пакет Microsoft.Web.WebView2 , а затем в раскрывающемся списке Версия выберите версию пакета NuGet Microsoft.Web.WebView2 .

Дополнительные сведения см. в статье Установка или обновление пакета SDK для WebView2статьи Настройка среды разработки для WebView2. Список пакетов ПАКЕТА SDK microsoft.Web.WebView2 также можно просмотреть на сайте NuGet.

Использование предварительной версии пакета SDK вместе с каналом предварительной версии Microsoft Edge

При разработке приложения Evergreen WebView2 регулярно тестируйте приложение по последнему каналу предварительной версии Microsoft Edge в дополнение к тестированию в среде выполнения WebView2. Так как веб-платформа постоянно развивается, регулярное тестирование — лучший способ убедиться, что приложение будет работать должным образом.

При использовании пакета SDK предварительной версии WebView2 используйте канал предварительной версии Microsoft Edge в клиенте разработки. Каналы предварительной версии также называются каналами программы предварительной оценки . Рекомендуется использовать канал предварительной версии Canary, а не бета-версию или разработку, так как Canary является последним и содержит реализации последних экспериментальных API.

Пакет SDK предварительной версии является надмножеством пакета SDK выпуска. Пакет SDK для предварительной версии содержит сигнатуры методов для:

• Экспериментальные API.
• Стабильные API, которые больше не являются экспериментальными, но еще не включены в пакет SDK для выпуска.
• Стабильные API, добавленные в пакеты SDK для выпуска.

Каналы предварительной версии Microsoft Edge предоставляют реализации экспериментальных API WebView2 и стабильных API. Экспериментальные API могут быть изменены на основе отзывов. Избегайте использования пакета SDK предварительной версии для создания рабочих приложений.

Сведения о временном перенаправлении приложения на канал предварительной версии вместо использования по умолчанию среды выполнения WebView2 см. в разделе Тестирование предстоящих API и функций.

См. также:

• Предварительное тестирование с помощью каналов предварительной версии
• Самостоятельное размещение путем развертывания каналов предварительной версии

Использование выпуска пакета SDK вместе со средой выполнения

При использовании пакета SDK выпуска WebView2 используйте среду выполнения Evergreen WebView2 в клиенте разработки, а не канал предварительной версии Microsoft Edge. По умолчанию приложение WebView2 предназначено для среды выполнения, а не для Microsoft Edge. По умолчанию канал Microsoft Edge Stable не поддерживает WebView2.

Пакет SDK для выпуска содержит все api-интерфейсы C/C++ и .NET Для стабильных win32 и .NET, которые находятся в рабочем выпуске, и не включает сигнатуры методов для экспериментальных API. Все API-интерфейсы, которые находятся в пакете SDK выпуска, полностью поддерживаются в равном или более высоком числе сборки среды выполнения WebView2.

Пакет SDK для выпуска содержит следующие компоненты:

• Api Win32 C/C++.
• API-интерфейсы .NET: WPF, WinForms и Core.

Дополнительные сведения об автоматическом обновлении среды выполнения Evergreen см. в разделе Распространение приложения и среды выполнения WebView2.

Периодичность выпуска

Новые версии пакета SDK для WebView2 поставляются в той же общей частоте, что и браузер Microsoft Edge, что происходит примерно каждые четыре недели.

Минимальная версия и номер сборки для создания экземпляра WebView2

Чтобы клиент мог создать экземпляр WebView2 и использовать набор API в выпуске общей доступности WebView2 (сборка пакета SDK 616), у клиента должна быть среда выполнения WebView2 версии 86.0.616.0 или более поздней. Среда выполнения 86.0.616.0 — это специальный выпуск, так как это выпуск общей доступности.

На компьютере разработки клиент должен иметь канал предварительной версии Microsoft Edge версии 86.0.616.0 или более поздней версии или среду выполнения WebView2 версии 86.0.616.0 или более поздней.

Прямая совместимость API

Пакет SDK для выпуска WebView2 совместим с пересылкой с версии 1 (пакет SDK для выпуска 1.0.622.22 в архивных заметках о выпуске пакета SDK для WebView2). Вы можете обновить приложение WebView2, чтобы использовать последние API из последней версии пакета SDK. Ваше приложение будет продолжать работать на клиентах, так как клиенты автоматически получают последнюю версию Evergreen WebView2 Runtime.

API WebView2 в пакете SDK для выпуска являются стабильными и совместимыми с пересылкой. API WebView2 работает при использовании среды выполнения WebView2, которая имеет номер сборки, равный или более высокому номеру сборки пакета SDK, в котором был представлен API. Номер сборки является третьей частью четырехкомпонентного номера версии пакета SDK для Webview2 и четырехкомпонентного номера версии для Microsoft Edge и среды выполнения WebView2.

• При использовании пакета SDK для WebView2 с номером сборки, равным или меньше, чем в среде выполнения WebView2, каждый API, к которому у вас есть доступ в этом пакете SDK, работает с этой версией среды выполнения.

• При использовании пакета SDK для WebView2 с номером сборки больше, чем в среде выполнения WebView2, новые реализации API недоступны в среде выполнения.

Например, если API появился в пакете SDK 1.0. 900.0, этот API будет работать со средой выполнения 94.0. 900+.0, но не со средой выполнения 90.0. 700.0.

Необходимо согласовать версию пакета SDK для WebView2, используемую для разработки, и версию среды выполнения WebView2, установленную на клиентских компьютерах. Клиент должен иметь версию среды выполнения, которая поддерживает все последние API-интерфейсы, которые находятся в версии пакета SDK, используемой для разработки приложения. Для полной поддержки последних API в выпускной версии пакета SDK среда выполнения на клиенте должна иметь номер сборки, который больше или равен номеру сборки пакета SDK.

Экспериментальные API

Чтобы опробовать новые предстоящие функции, которые находятся в разработке, используйте экспериментальные API. Экспериментальные API содержатся в пакетах SDK для предварительной версии, но не в пакетах SDK для выпуска.

Разработка с помощью экспериментальных API и предоставление отзывов

Экспериментальные API в пакете ПАКЕТА SDK для предварительной версии WebView2 не гарантируются, что будут совместимы с пересылкой и могут быть удалены в будущих обновлениях среды выполнения.

Для полной поддержки экспериментальных API используйте канал предварительной версии Microsoft Edge, а не среду выполнения Evergreen WebView2. Когда предварительная версия пакета SDK для WebView2 изначально становится доступной, этот пакет SDK работает только с Microsoft Edge Canary. Вскоре после этого пакет SDK для предварительной версии также работает с бета-версиями и каналами разработки.

Используйте пакет SDK для предварительной версии, чтобы опробовать новые экспериментальные API на ранней стадии и оставить отзыв до того, как экспериментальные API будут повышены до того, как они превратятся в стабильные, совместимые с пересылкой API.

• Экспериментальные API (в предварительном пакете SDK) не гарантируют прямую совместимость.
• Стабильные API-интерфейсы, которые находятся в пакете SDK для предварительной версии, совместимы с пересылкой, даже если они еще не включены в пакет SDK для выпуска.
• Стабильные API- интерфейсы, которые находятся в пакете SDK для выпуска, совместимы с пересылкой.

Дополнительные сведения см. в разделе Прямая совместимость API выше.

Команда WebView2 ищет отзывы о экспериментальных API WebView2, которые могут быть повышены до стабильной в будущих выпусках. Экспериментальные API указаны как экспериментальные в справочной документации по пакету SDK для WebView2, например: "Примечание. Это экспериментальный API, поставляемый с нашим предварительным пакетом SDK".

Чтобы помочь вам оценить экспериментальные API и поделиться своими отзывами, используйте репозиторий WebView2Feedback .

Переход от экспериментальных API к стабильным API

После перемещения API из состояния "Экспериментальный" на "Стабильный" необходимо переместить код приложения в стабильный API. Использование экспериментальных API или пакета SDK для предварительной версии не рекомендуется использовать для рабочих приложений. При перемещении приложения с экспериментальных API на стабильные API следуйте приведенным ниже рекомендациям.

• В проекте в Visual Studio обновите версию пакета SDK для WebView2 до более новой версии пакета SDK для предварительного выпуска или пакета SDK выпуска. См . статью Установка или обновление пакета SDK для WebView2 в статье Настройка среды разработки для WebView2.

• Обновите код приложения, чтобы использовать стабильные API вместо экспериментальных API (для COM). Стабильный API будет поддерживаться с исправлениями ошибок, но экспериментальный API будет нерекомендуем и недоступен в более новом пакете SDK (предварительная версия или выпуск). После повышения уровня API до стабильного экспериментальная версия этого API поддерживается для двух выпусков пакета SDK для предварительной версии в устаревшем состоянии. В последующих версиях пакета SDK для предварительной версии экспериментальные API-интерфейсы могут быть изменены, удалены или добавлены.

• Всегда используйте обнаружение функций, чтобы убедиться, что стабильный API реализован в пользовательской версии среды выполнения WebView2. См. раздел Определение компонентов, чтобы проверить, поддерживает ли установленная среда выполнения недавно добавленные API ниже.

• Примечание только для .NET. В предварительном пакете SDK Для WebView2 стабильные API .NET будут откатиться к соответствующим экспериментальным API, если среда выполнения WebView2 пользователя имеет только экспериментальную реализацию API и не имеет реализации стабильного API.

Сопоставление версии среды выполнения с версией пакета SDK

При подходе к распространению Evergreen клиентская среда выполнения WebView2 автоматически обновляется до последней доступной версии. Однако пользователь или ИТ-администратор может запретить автоматическое обновление среды выполнения WebView2. Устаревшая среда выполнения на клиенте может вызвать проблемы совместимости с обновленным приложением WebView2, которое использует новые API из недавнего пакета SDK.

Если обновление среды выполнения WebView2 запрещено на клиенте, убедитесь, что вы знаете минимальный номер сборки среды выполнения WebView2, необходимый вашему приложению. Чтобы просмотреть или получить последние версии среды выполнения WebView2, см . статью Скачивание среды выполнения WebView2 на странице Microsoft Edge WebView2 на developer.microsoft.com. Минимальная требуемая версия среды выполнения для поддержки общедоступного выпуска пакета SDK (сборка 616) старше, чем для последней версии среды выполнения. Последняя версия среды выполнения поддерживает все API, которые входят в пакет SDK последней версии.

Сведения о совместимости между определенными номерами сборки пакета SDK и каналом предварительной версии среды выполнения или Microsoft Edge см. в статье Заметки о выпуске пакета SDK для WebView2.

Обнаружение компонентов для проверки того, поддерживает ли установленная среда выполнения недавно добавленные API

Если в вашем приложении используется среда выполнения Evergreen, а не фиксированная версия, следует обертывать все вызовы к относительно новым API WebView2 с помощью QueryInterface или try-catch. Бывают пограничные случаи, когда клиентская среда выполнения Evergreen не является последней сборкой и, следовательно, отстает от номера сборки пакета SDK, так как администратор мог отключить обновление среды выполнения WebView2 или клиент может находиться в автономном режиме.

При разработке приложения WebView2 с помощью последней версии пакета SDK для WebView2, если вы используете недавно добавленный API, необходимо проверить или "определить признаки", присутствует ли этот API в установленной клиентом среде выполнения WebView2. Способ программного тестирования приложения на поддержку API зависит от платформы программирования.

• Win32 C/C++. При запросе экспорта CreateCoreWebView2Environment БИБЛИОТЕКи DLL и при выполнении QueryInterface для любого CoreWebView2 объекта проверьте возвращаемое значение E_NOINTERFACE. Это возвращаемое значение, скорее всего, указывает на то, что клиентская среда выполнения WebView2 является более старой версией, которая не поддерживает этот интерфейс.

  Пример проверки наличия определенных API WebView2 в среде выполнения можно найти try_query в AppWindow.cpp. Этот файл заключает вызовы API WebView2 в функцию CHECK_FAILURE макросов, определенную в CheckFailure.h.

• .NET и WinUI. Используйте try/catch и проверьте наличие No such interface supported исключения при использовании методов, свойств и событий, добавленных в более поздние версии пакета SDK для WebView2. Это исключение, скорее всего, указывает на то, что клиентская среда выполнения WebView2 является более старой версией, которая не поддерживает этот API.

Если код определяет, что API недоступен в установленной клиентом среде выполнения WebView2, следует предоставить удобный резервный вариант для связанной функции или сообщить пользователю, что он должен обновить среду выполнения WebView2, чтобы использовать эту функцию.