Распространение приложения WebView2 и среда выполнения WebView2

При распространении приложения WebView2 убедитесь, что среда выполнения WebView2 присутствует на клиентском компьютере. Это требование распространяется как на актуальную, так и на фиксированную версию.

Вводные сведения см. в статье "Актуальная и неизменяемая версия среды выполнения WebView2".

Обслуживание среды выполнения WebView2 через службы Windows Server Update Services (WSUS)

См. Windows Server Update Services (WSUS) в статье «Управление WebView2 на предприятии».

Поддержка среды выполнения или браузера в процессе разработки или рабочей среды

Во время разработки и тестирования приложение WebView2 может использовать любой из вариантов в качестве резервной веб-платформы:

  • Среда выполнения WebView2. Среда выполнения обычно предоставляет те же возможности веб-платформы и частоту выпуска обновлений, что и стабильный канал браузера Microsoft Edge; см. расписание выпусков Microsoft Edge. Используйте среду выполнения WebView2 в рабочей среде или для разработки и тестирования на текущей веб-платформе.

  • Ознакомительная версия (предварительная версия) канала браузера Microsoft Edge. Это каналы с предварительными версиями Microsoft Edge: Beta, Dev и Canary. Используйте этот подход для проверки совместимости приложений с предыдущими обновлениями, чтобы знать, грядут ли критические изменения, требующие обновления приложения. См. раздел "Тестирование предстоящих API и функций".

В производственном выпуске приложения WebView2 в качестве резервной веб-платформы может использоваться только среда выполнения WebView2, но не Microsoft Edge.

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

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

  • Присутствие Microsoft Edge на всех устройствах пользователей не гарантируется. Многие устройства на предприятиях и в образовательных учреждениях отключены от клиентского компонента Центра обновления Windows или не управляются корпорацией Майкрософт напрямую. На таких устройствах может не быть установлен Microsoft Edge. Требование использовать среду выполнения WebView2 в производственной версии приложений WebView2, а не Microsoft Edge, позволяет избежать использования Microsoft Edge в качестве обязательного условия для запуска приложения WebView2.

  • Браузеры и приложения имеют разные варианты использования. Если приложению WebView2 требуется присутствие Microsoft Edge в клиенте, это может привести к непредвиденным побочным эффектам для приложения WebView2. Например, ИТ-администратор может запретить обновление браузера до определенной версии, чтобы обеспечить совместимость браузера с внутренним веб-сайтом. Требование использовать среду выполнения WebView2 в производственной версии приложения WebView2, а не браузер, позволяет приложению WebView2 оставаться актуальным, даже если обновление браузера запрещено администратором клиентов.

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

Актуальная среда выполнения WebView2 будет включена в операционную систему Windows 11. Различные приложения WebView2 установили актуальную среду выполнения на устройствах с операционной системой до Windows 11. Однако на некоторых устройствах среда выполнения может быть предварительно не установлена, поэтому рекомендуется проверить, присутствует ли среда выполнения на клиенте.

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

Режим распространения актуальной среды выполнения

Режим распространения Evergreen гарантирует, что приложение WebView2 использует преимущества новейших функций WebView2 и обновлений для системы безопасности. Вводные сведения см. в статье Режим распространения актуальной среды выполнения в постоянно актуальной версии среды выполнения WebView2 и исправленной версии среды выполнения WebView2.

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

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

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

  • В подходящих системах двоичные файлы для Microsoft Edge и актуальной среды выполнения WebView2 жестко связаны, если они находятся в одной и той же версии. Такое связывание дает преимущества с точки зрения занимаемого места на диске, объема памяти и производительности.

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

Устройства с Windows 11 и Windows 10 (подробности)

Вводные сведения см. в статьях Устройства с Windows 11 и устройства с Windows 10 в Evergreen и исправленная версия среды выполнения WebView2.

На подавляющем большинстве устройств с Windows 10 среда выполнения WebView2 уже установлена, как описано в разделе "Доставка среды выполнения Microsoft Edge WebView2 на управляемые устройства с Windows 10". На небольшом количестве устройств с Windows 10 среда выполнения WebView2 не установлена. Мы рекомендуем обработать этот пограничный случай, используя один из следующих подходов:

См. также:

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

Для всех постоянно актуальных приложений на устройстве требуется только одна установка актуальной среды выполнения WebView2. В разделе "Скачать среду выполнения WebView2 " доступно несколько средств, которые помогут вам развернуть актуальную среду выполнения.

  • Для онлайн-клиентов: WebView2 Runtime Bootstrapper — это крошечный (примерно 2 МБ) установщик. Загрузчик среды выполнения WebView2 скачивает и устанавливает с серверов Майкрософт актуальную среду выполнения в соответствии с архитектурой устройства пользователя.

    • В разделе настройки приложения WebView2 создайте ссылку на начальный загрузчик. Используйте ссылку, чтобы программно загрузить начальный загрузчик; нажмите кнопку "Получить ссылку" на странице загрузки выше.

    • Или скачайте начальный загрузчик и упакуйте его в приложении WebView2.

  • Для автономных клиентов: установщик изолированной среды выполнения WebView2 — это полнофункциональный установщик, устанавливающий актуальную среду выполнения WebView2 в автономных средах.

  • Если вы используете установщик приложений для развертывания приложений MSIX, можно указать среду выполнения WebView2 в качестве зависимости, чтобы она устанавливалась вместе с приложением. Подробные сведения о том, как это сделать, см. в win32dependencies:ExternalDependency (Windows 10, Windows 11) в документах манифеста пакета приложения. См. также: установка приложений для Windows 10 с помощью установщика приложений.

Установка среды выполнения для компьютера или пользователя

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

Если вы запускаете установщик из процесса с повышенными привилегиями или из командной строки, среда выполнения устанавливается для каждого компьютера. Если вы не запустите установщик из процесса с повышенными привилегиями или командной строки, среда выполнения будет установлена для отдельного пользователя. Однако установка для каждого пользователя автоматически заменяется установкой на отдельном компьютере , если используется средство обновления Microsoft Edge для каждого компьютера . Средство обновления Microsoft Edge для каждого компьютера входит в состав Microsoft Edge, за исключением канала предварительной версии Canary в Microsoft Edge.

Используйте следующий рабочий процесс развертывания в сети или в автономном режиме, чтобы убедиться, что среда выполнения уже установлена перед запуском приложения. Вы можете настроить рабочий процесс в зависимости от сценария. Пример кода доступен в репозитории Samples.

Определение того, установлена ли уже среда выполнения WebView2

Чтобы убедиться, что среда выполнения WebView2 установлена, используйте один из следующих подходов:

  • Способ 1. Проверка pv (REG_SZ) раздела реестра для среды выполнения WebView2 в обоих следующих расположениях реестра. Этот HKEY_LOCAL_MACHINE раздел реестра используется для установки на каждом компьютере . Ключ HKEY_CURRENT_USER реестра используется для установки на уровне пользователя .

    Для приложений WebView2 по крайней мере один из этих разделов реестра должен присутствовать и быть определен с версией больше 0.0.0.0. Если ни один из этих разделов реестра не существует или существует только один из этих разделов реестра, но его значение равно null, пустая строка или 0.0.0.0, это означает, что среда выполнения WebView2 не установлена на клиенте. Проверьте эти разделы реестра, чтобы определить, установлена ли среда выполнения WebView2, и узнать версию среды выполнения WebView2. Найдите pv (REG_SZ) в следующих двух местах.

    Два раздела реестра для проверки в 64-разрядной версии Windows:

    HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}

HKEY_CURRENT_USER\Software\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}

    Два раздела реестра для проверки в 32-разрядной версии Windows:

    HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}

HKEY_CURRENT_USER\Software\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}

  • Способ 2: Запустите GetAvailableCoreWebView2BrowserVersionString и оцените, является ли .versionInfonullptr nullptr указывает, что среда выполнения WebView2 не установлена. Этот API возвращает сведения о версии для среды выполнения WebView2 или для любых установленных предварительных каналов Microsoft Edge (бета-версии, разработки или канала Canary).

Развертывание только через Интернет

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

  1. Во время настройки приложения запустите тест, чтобы убедиться, что среда выполнения WebView2 уже установлена. См. раздел "Определение установки среды выполнения WebView2" выше.

  2. Если среда выполнения не установлена, в процессе настройки приложения используйте ссылку (от кнопки " Получить ссылку " на странице загрузки), чтобы программно скачать загрузчик среды выполнения WebView2.

  3. Вызовите загрузчик среды выполнения WebView2, выполнив следующую команду.

    При выполнении следующей команды из процесса с повышенными привилегиями или командной строки запускается установка для каждого компьютера . Если вы не выполните команду из процесса с повышенными привилегиями или командной строки, будет выполнена установка для каждого пользователя . Однако установка для каждого пользователя автоматически заменяется установкой на отдельном компьютере , если используется средство обновления Microsoft Edge для каждого компьютера . Средство обновления Microsoft Edge для каждого компьютера предоставляется как часть Microsoft Edge, за исключением канала предварительной версии Canary в Microsoft Edge. Дополнительные сведения см. в разделе Установка среды выполнения для компьютера или пользователя.

    MicrosoftEdgeWebview2Setup.exe /silent /install

Описанный выше рабочий процесс имеет несколько преимуществ:

  • Среда выполнения устанавливается только при необходимости.

  • Вам не требуется упаковывать установщик среды выполнения с приложением WebView2.

  • Загрузчик среды выполнения WebView2 автоматически определяет архитектуру устройства (платформу) и устанавливает соответствующую среду выполнения WebView2.

  • Среда выполнения устанавливается автоматически.

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

Автономное развертывание

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

  1. Скачайте установщик изолированной актуальной версии в статье Загрузите среду выполнения WebView2 на компьютер разработки. Установщик изолированной актуальной версии устанавливает среду выполнения Evergreen WebView2 на клиенте.

  2. Включите установщик изолированной актуальной версии в установщик или средство обновления приложений.

  3. Во время настройки приложения запустите тест, чтобы убедиться, что среда выполнения WebView2 уже установлена. См. раздел "Определение установки среды выполнения WebView2" выше.

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

    При выполнении следующей команды из процесса с повышенными привилегиями или командной строки запускается установка для каждого компьютера . Если вы не выполните команду из процесса с повышенными привилегиями или командной строки, будет выполнена установка для каждого пользователя . Однако установка для каждого пользователя автоматически заменяется установкой на отдельном компьютере , если используется средство обновления Microsoft Edge для каждого компьютера . Средство обновления Microsoft Edge для каждого компьютера предоставляется как часть Microsoft Edge, за исключением канала предварительной версии Canary в Microsoft Edge. Дополнительные сведения см. в разделе Установка среды выполнения для компьютера или пользователя.

    MicrosoftEdgeWebView2RuntimeInstaller{X64/X86/ARM64}.exe /silent /install

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

Новые версии актуальной среды выполнения WebView2 автоматически скачиваются в клиент. Клиент использует новую версию среды выполнения WebView2 при перезапуске приложения WebView2. Однако если приложение работает непрерывно, оно будет продолжать использовать предыдущую версию среды выполнения WebView2. Это влияет на безопасность, так как предыдущая версия среды выполнения WebView2 может содержать уязвимости системы безопасности, которые исправлены в новой версии. Подумайте о том, важно ли для вашего приложения как можно скорее перейти на последнюю версию среды выполнения WebView2, исходя из модели угроз вашего приложения. Например, если приложение WebView2 получает доступ к стороннему содержимому, это содержимое следует считать ненадежным, поэтому вашему приложению необходимо использовать последнюю версию среды выполнения WebView2.

Чтобы использовать новую версию среды выполнения WebView2, необходимо либо освободить все ссылки на предыдущие объекты среды WebView2, либо перезапустить приложение. При следующем создании приложением среды WebView2 оно будет использовать новую версию среды выполнения WebView2. Для этого можно использовать обработчик NewBrowserVersionAvailable событий, чтобы приложение автоматически уведомляло пользователя о необходимости перезапустить приложение. Если приложение обрабатывает перезапуск, рассмотрите возможность сохранения состояния пользователя до завершения работы приложения WebView2.

Тестирование приложения на совместимость с обновлениями

В режиме распространения Evergreen среда выполнения WebView2 автоматически обновляется на клиенте, чтобы предоставлять новейшие функции и исправления безопасности. Если вы используете распространение Evergreen и хотите обеспечить совместимость приложения WebView2 с Интернетом, настройте инфраструктуру тестирования.

Рекомендации по проверке приложения на совместимость с будущими обновлениями см. в статьях Тестирование предварительного выпуска с использованием каналов предварительногопросмотра и Self-host путем развертывания каналов предварительного просмотра.

Определение компонентов при использовании последних API

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

Дополнительные сведения см. в разделе "Обнаружение компонентов", чтобы проверить, поддерживает ли установленная среда выполнения недавно добавленные API в предварительной версии и пакетах SDK для выпуска WebView2.

Для Microsoft Edge и среды выполнения WebView2 существуют отдельные политики обновления. Отключение обновлений для Microsoft Edge не влияет на доступность последних API WebView2, так как среда выполнения WebView2 по-прежнему может обновляться автоматически (если обновление среды выполнения WebView2 не отключено администратором).

Режим распространения неизменяемой версии среды выполнения

В средах с ограниченными возможностями, предъявляющих строгие требования к совместимости, рекомендуется использовать режим распространения неизменяемой версии. (Режим распространения неизменяемой версии ранее назывался "принеси свое".) Вводные сведения см. в статье Режим распространения неизменяемой версии в Evergreen и фиксированная версия среды выполнения WebView2.

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

Размер двоичных файлов неизменяемой версии превышает 250 МБ, и пакет приложения увеличивается на этот размер.

Использование режима распространения неизменяемой версии:

  1. Скачайте исправленную версию среды выполнения WebView2 в разделе "Загрузите среду выполнения WebView2" в виде пакета.

    Наиболее исправленные версии последних и вторых последних основных выпусков доступны для загрузки на этом сайте. Сохраняйте архивные копии всех необходимых версий.

  2. Распакуйте пакет среды выполнения WebView2 с помощью команды expand {path to the package} -F:* {path to the destination folder} командной строки или средства распаковки, например WinRAR. Избегайте распаковки через проводник, так как такой подход может привести к повреждению правильной структуры папок.

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

  4. Укажите путь к двоичным файлам неизменяемой версии при создании среды WebView2.

    • Для Win32 C/C++ можно создать среду с помощью функции CreateCoreWebView2EnvironmentWithOptions . Используйте browserExecutableFolder этот параметр, чтобы указать путь к папке, содержащей среду выполнения WebView2 (msedgewebview2.exe).

    • Для .NET необходимо указать среду до того, как свойство WebView2 Source вступит в силу. Для .NET можно указать среду одним из следующих способов:

      • Установите свойство CreationProperties (WPF/WinForms) элемента WebView2 . Используйте BrowserExecutableFolder член в CoreWebView2CreationProperties классе (WPF/WinForms), чтобы указать путь к двоичным файлам неизменяемой версии.

      • Кроме того, можно использовать EnsureCoreWebView2Async (WPF/WinForms) для указания среды. Используйте browserExecutableFolder параметр в CoreWebView2Environment.CreateAsync , чтобы указать путь к двоичным файлам неизменяемой версии.

    • Для WinUI убедитесь, что у приложения есть доступ к папке, указав расположение установки и задав переменную среды для пути среды выполнения. Один из способов сделать это — добавить в приложение следующий код C#:

      StorageFolder localFolder = Windows.ApplicationModel.Package.Current.InstalledLocation;
String fixedPath = Path.Combine(localFolder.Path, "FixedRuntime\\(version number)");
Debug.WriteLine($"Launch path [{localFolder.Path}]");
Debug.WriteLine($"FixedRuntime path [{fixedPath}]");
Environment.SetEnvironmentVariable("WEBVIEW2_BROWSER_EXECUTABLE_FOLDER", fixedPath);

  5. Упакуйте и отправьте двоичные файлы неизменяемой версии вместе с вашим приложением. Соответствующим образом обновите двоичные файлы.

    • Для WinUI это может включать открытие файла проекта (.csproj) в редакторе кода и последующее добавление следующего кода в теги проекта:

      <ItemGroup>
    <Content Include="FixedRuntime\(version number)\\**\*.*">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </Content>
</ItemGroup>

      Убедитесь, что в bin\**designated architecture**\Release папке есть соответствующая папка FixedRuntime\(номер версии) с файлами времени выполнения.

  6. На устройствах с Windows 10, начиная с Fixed Version 120, разработчики неупакованных приложений Win32, использующих Fixed Version, должны выполнять следующие команды, чтобы Fixed Version продолжала работать. Это связано с улучшением безопасности в версии 120 для запуска процесса обработчика в контейнере приложений. Это изменение не влияет на устройства с Windows 11, старую среду выполнения или упакованные приложения.

    1. Найдите путь, по которому вы развертываете пакет неизменяемой версии на устройстве пользователя, например следующее:

      D:\myapp\Microsoft.WebView2.FixedVersionRuntime.87.0.664.8.x64

    2. Выполните следующие команды на устройстве пользователя:

      icacls {Fixed Version path} /grant *S-1-15-2-2:(OI)(CI)(RX)
icacls {Fixed Version path} /grant *S-1-15-2-1:(OI)(CI)(RX)

    3. Подтвердите предоставление разрешений на вкладке "Безопасность" папки ALL APPLICATION PACKAGESALL RESTRICTED APPLICATION PACKAGES"Неизменяемая версия", как показано ниже:

      Разрешение для PlayReady

Известные проблемы исправленной версии

  • В настоящее время неизменяемая версия не может быть запущена из сетевого расположения или UNC-пути.

Files поставляться вместе с приложением

Код WebView2Loader должен поставляться вместе с приложением. Это можно сделать, статически связывая WebView2Loader.lib двоичные файлы с двоичными файлами приложения или включая WebView2Loader.dll элементы, соответствующие архитектуре приложения. Обычно это обрабатывается Visual Studio автоматически при использовании .targets файла в SDK WebView2, но в некоторых случаях может потребоваться вручную указать, какие файлы опубликовать в приложении. Сведения о статической привязке библиотеки загрузчика WebView2 см. в статье Распространение приложения WebView2 в виде единого исполняемого файла.

WebView2Loader.dll является двоичным файлом, зависящим от архитектуры машинного кода, поэтому вам необходимо включить все возможности этого двоичного файла, в которых предполагается запускать приложение. Например, вы можете:

  • Для x86 необходимо включить версию x86 .WebView2Loader.dll

  • Для управляемого приложения, использующего AnyCPU, следует включить версии x86, x64 и arm64 .WebView2Loader.dll Правильная версия WebView2Loader.dll загружается из соответствующей папки, относящейся к архитектуре.

Пример структуры папок собственного приложения:

\<myApp>
    \WebView2Loader.dll

Для управляемых приложений .NET также необходимо включить сборки WebView2 .NET для основной функциональности WebView2 (Microsoft.Web.WebView2.Core.dll) и для функций, специфичных для WPF/WinForms (Microsoft.Web.WebView2.Winforms.dll или Microsoft.Web.WebView2.WPF.dll).

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

\<myApp>
    \Microsoft.Web.WebView2.Core.dll
    \Microsoft.Web.WebView2.Winforms.dll
    \Microsoft.Web.WebView2.WPF.dll
    \runtimes
        \win-arm64\native\WebView2Loader.dll (arm64)
        \win-x64\native\WebView2Loader.dll (x64)
        \win-x86\native\WebView2Loader.dll (x86)

См. также

Корпоративные документы

developer.microsoft.com:

Блоги:

Windows:

GitHub:

API-интерфейс среды выполнения Windows:

Справочник по API:

  • Last updated on