Начало работы с WebView2 в приложениях WPF

  • Статья

В этой статье описано, как настроить средства разработки и создать начальное приложение WebView2 для Windows Presentation Foundation (WPF), а также ознакомиться с основными понятиями WebView2.

В этом руководстве вы используете шаблон проекта приложения WPF или приложения WPF (платформа .NET Framework), чтобы создать приложение WPF, а затем установить пакет SDK WebView2 для проекта, чтобы добавить WebView2.

Завершенный проект

Полная версия этого учебного проекта доступна в репозитории WebView2Samples :

  • Имя примера: WPF_GettingStarted
  • Каталог репозитория: WPF_GettingStarted
  • Файл решения: WPFSample.sln

Шаг 1. Установка Visual Studio с поддержкой .NET

Для работы с этим руководством требуется Microsoft Visual Studio, а не Microsoft Visual Studio Code. В этой статье описывается главным образом использование Visual Studio 2022.

  1. Установите Visual Studio. Установите поддержку разработки классических приложений .NET , чтобы получить необходимые шаблоны проектов, как показано ниже.

  2. Если вы находитесь на начальном экране Visual Studio, прокрутите вниз диалогового окна Create новый проект и щелкните ссылку Открыть без кода. Откроется Visual Studio.

  3. В Visual Studio выберите Сервис>Получить средства и компоненты. Откроется окно Visual Studio Installer, а над ним откроется диалоговое окно Изменение.

  4. Выберите рабочую нагрузку разработка классических приложений .NET , чтобы на ней был установлен флажок.

  5. В разделе Сведения об>установке.Разработка классических приложений> .NET справа убедитесь, что средства разработки классических приложений .NET и средства разработки платформа .NET Framework версии 4.7.2 указаны с флажком рядом с ними.

  6. В разделе Сведения об>установке.Разработка классических приложений.NET>Необязательно справа:

    • Если вы используете Visual Studio 2022, убедитесь, что выбраны средства разработки для .NET :

    Диалоговое окно

    • Если вы используете Visual Studio 2019, убедитесь, что выбраны средства разработки .NET :

    Диалоговое окно

  7. Нажмите кнопку Изменить .

Это руководство также работает с Visual Studio 2017. См. более старые загрузки Visual Studio. Установите поддержку .NET, чтобы получить необходимые шаблоны проектов, как описано выше.

Шаг 2. Установка канала предварительной версии Microsoft Edge

  1. Скачайте любой канал предварительной версии Microsoft Edge (бета-версия, разработка или Canary) в поддерживаемой операционной системе:

    • Windows 10
    • Windows 11

    Для этого перейдите в раздел Стать участником программы предварительной оценки Microsoft Edge. Каналы предварительной версии также называются каналами предварительной оценки.

    Рекомендуется использовать канал Canary Microsoft Edge. Минимальная требуемая версия — 82.0.488.0.

Шаг 3. Create одноокне приложения WebView2

Начните с создания базового классического проекта, содержащего одно окно main.

  1. Решите, следует ли создать проект .NET Core/5/6 (более новый) или проект приложения WPF (платформа .NET Framework) (более старый). Дополнительные сведения см. в разделе:

    • Журнал .NET в разделе Что такое .NET? Введение и обзор.
    • .NET в Википедии.

  2. Следуйте инструкциям в соответствующем разделе ниже.

Создание проекта .NET Core/5/6

Если вы создаете проект .NET Core/5/6, выполните следующие действия. В противном случае перейдите к разделу Создание проекта приложения WPF (платформа .NET Framework).

  1. Откройте Microsoft Visual Studio, например Visual Studio 2022.

  2. На открывающейся панели щелкните Create новый проект. Или в окне main Visual Studio выберите Файл>Создать>проект. Откроется диалоговое окно Create нового проекта.

  3. В текстовом поле Поиск для шаблонов введите WPF Application. На Create панели нового проекта отображаются установленные шаблоны проектов, соответствующие введенном тексту. В этой статье показаны диалоговые окна C# вместо VB. Для WebView2 поддерживаются оба языка.

  4. Если вы используете Visual Studio 2022, щелкните шаблон проекта с заголовком ПРИЛОЖЕНИЕ WPF и текстом описания Проект для создания приложения WPF для .NET:

    Выбор шаблона

    Если вы используете Visual Studio 2019, щелкните шаблон проекта с заголовком ПРИЛОЖЕНИЕ WPF и текстом описания Проект для создания приложения WPF для .NET Core:

    Выбор шаблона

    Если указанный выше шаблон проекта отсутствует в списке, см. шаг 1. Установка Visual Studio с поддержкой .NET выше, чтобы установить средства разработки классических приложений .NET.

  5. Нажмите кнопку Далее .

    Откроется диалоговое окно Настройка нового проекта: приложение WPF :

    Диалоговое окно

  6. В текстовом поле Имя проекта введите имя проекта, например MyWpfDotnetCoreWv2App.

  7. В текстовом поле Расположение выберите путь на локальном диске, например C:\Users\myusername\Documents\MyProjects, и нажмите кнопку Далее .

    Откроется диалоговое окно Дополнительные сведения с раскрывающимся списком Целевая платформа :

    Диалоговое окно

  8. Выберите .NET Core 3.1 или более поздней версии, например .NET 6.0. (Не выбирайте .NET Core 3.0.) Затем нажмите кнопку Create.

    Начальный проект приложения WPF для .NET Core открывается в Visual Studio:

    Начальный проект в Visual Studio 2022 с использованием шаблона приложения WPF для .NET Core

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

Создание проекта приложения WPF (платформа .NET Framework)

Если вы создаете проект приложения WPF (платформа .NET Framework), выполните следующие действия. В противном случае перейдите к шагу 4. Сборка и запуск начального проекта без WebView2.

  1. Откройте Microsoft Visual Studio, например Visual Studio 2022.

  2. На открывающейся панели щелкните Create новый проект. Или в окне main Visual Studio выберите Файл>Создать>проект. Откроется диалоговое окно Create нового проекта.

  3. В текстовом поле Поиск для шаблонов введите WPF App. На Create панели нового проекта отображаются установленные шаблоны проектов, соответствующие введенном тексту. В этой статье показаны диалоговые окна C# вместо VB. Для WebView2 поддерживаются оба языка.

  4. Щелкните шаблон проекта с заголовком ПРИЛОЖЕНИЕ WPF (платформа .NET Framework) и текстом описания Windows Presentation Foundation клиентского приложения:

    Выбор шаблона

    Если указанный выше шаблон проекта отсутствует в списке, см. шаг 1. Установка Visual Studio с поддержкой .NET выше, чтобы установить средства разработки классических приложений .NET.

  5. Нажмите кнопку Далее .

    Откроется диалоговое окно Настройка нового проекта: приложение WPF (платформа .NET Framework):

    Диалоговое окно

  6. В текстовом поле Имя проекта введите имя проекта, например MyWpfDotnetFwkWv2App.

  7. В текстовом поле Расположение выберите путь на локальном диске, например C:\Users\myusername\Documents\MyProjects.

  8. В раскрывающемся списке Платформа выберите платформа .NET Framework 4.6.2 или более поздней версии.

  9. Нажмите кнопку Создать.

    Начальный проект приложения WPF (платформа .NET Framework) откроется в Visual Studio:

    Начальный проект в Visual Studio 2022 с использованием шаблона приложения WPF (платформа .NET Framework)

Шаг 4. Сборка и запуск начального проекта без WebView2

  1. Выберите Файл>Сохранить все , чтобы сохранить проект.

  2. Нажмите клавишу F5, чтобы выполнить сборку и запуск проекта.

    Проект запускается и отображает пустое окно:

    Пустое окно приложения без WebView2

    Может потребоваться установить выбранную версию платформа .NET Framework, как показано ниже.

  3. Если приложение не открывается, выберите Отладка>Начать без отладки.

    Если выбранная версия платформа .NET Framework не установлена, может появиться следующее диалоговое окно: "Не удалось запустить это приложение. Приложению требуется одна из следующих версий платформа .NET Framework: . NETFramework,Version=v4.8.1 . Установить эту платформа .NET Framework версию сейчас?

  4. Если появится такое диалоговое окно, перейдите в раздел Скачать платформа .NET Framework и скачайте, а затем установите необходимую версию пакета разработчика (не среду выполнения). Например, скачайте ndp481-devpack-enu.exe файл в C:\Users\username\Downloads, а затем дважды щелкните файл, чтобы установить его.

  5. При появлении запроса перезагрузите компьютер:

    Перезапуск для установки платформа .NET Framework

  6. Перейдите в скачанный файл, например ndp481-devpack-enu.exe в C:\Users\username\Downloads, и снова дважды щелкните скачанный файл, чтобы установить пакет разработчика платформа .NET Framework. Откроется диалоговое окно Успешно :

    Установка успешной установки платформа .NET Framework

  7. При появлении запроса перезагрузите компьютер еще раз.

  8. Откройте Visual Studio и откройте созданное решение.

  9. Нажмите клавишу F5 , чтобы запустить начальное приложение (показано выше), но еще не включив пакет SDK для WebView2.

  10. Закройте начальное приложение.

Шаг 5. Установка пакета SDK для WebView2

В Visual Studio используйте диспетчер пакетов NuGet, чтобы добавить пакет SDK WebView2 в проект следующим образом:

  1. В Обозреватель решений щелкните правой кнопкой мыши имя проекта (на основе шаблона проекта .NET (Core) или платформа .NET Framework), а затем выберите Управление пакетами NuGet:

    Команда

  2. В левом верхнем углу щелкните вкладку Обзор . В строке поиска введите Microsoft.Web.WebView2, а затем щелкните пакет Microsoft.Web.WebView2 .

    В диалоговом окне диспетчера пакетов NuGet отображаются результаты поиска, включая пакет Microsoft.Web.WebView2 . В диалоговом окне есть номер версии и кнопка Установить .

    Диалоговое окно диспетчера пакетов NuGet отображает пакет Microsoft.Web.WebView2

  3. Примите версию по умолчанию и нажмите кнопку Установить .

  4. В диалоговом окне Предварительный просмотр изменений нажмите кнопку ОК .

  5. Выберите Файл>Сохранить все , чтобы сохранить проект.

  6. Нажмите клавишу F5, чтобы выполнить сборку и запуск проекта.

    Проект запускается и отображает пустое окно. Это подтверждает, что WebView2 установлен и работает, хотя у WebView2 пока нет содержимого для отображения:

    Пустое окно приложения с пакетом SDK для WebView2

  7. Закройте приложение.

Шаг 6. Create одного элемента управления WebView2

Добавьте элемент управления WebView2 в приложение.

  1. MainWindow.xaml В файле, чтобы добавить пространство имен XAML WebView2, вставьте в тег следующую строку<Window/>:

    xmlns:wv2="clr-namespace:Microsoft.Web.WebView2.Wpf;assembly=Microsoft.Web.WebView2.Wpf"

  2. Убедитесь, что код в MainWindow.xaml выглядит следующим образом:

    <Window x:Class="WPF_Getting_Started.MainWindow"
      xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
      xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
      xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
      xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
      xmlns:local="clr-namespace:{YOUR PROJECT NAME}"
      xmlns:wv2="clr-namespace:Microsoft.Web.WebView2.Wpf;assembly=Microsoft.Web.WebView2.Wpf"
      mc:Ignorable="d"
      Title="MainWindow"
      Height="450"
      Width="800"
>
   <Grid>

   </Grid>
</Window>

  3. Чтобы добавить элемент управления WebView2, замените <Grid> теги следующим кодом. Свойство Source задает начальный URI, отображаемый в элементе управления WebView2.

    <DockPanel>
   <wv2:WebView2 Name="webView"
                  Source="https://www.microsoft.com"
   />
</DockPanel>

  4. Выберите Файл>Сохранить все , чтобы сохранить проект.

  5. Нажмите клавишу F5, чтобы выполнить сборку и запуск проекта.

  6. Убедитесь, что элемент управления WebView2 отображает :https://www.microsoft.com

    Элемент управления WebView2, отображающий содержимое веб-страницы из microsoft.com

Шаг 7. Навигация

Разрешить пользователям изменять URL-адрес, отображаемый элементом управления WebView2, добавив адресную строку в приложение.

  1. MainWindow.xaml В файле добавьте адресную строку, скопировав и вставив следующий код в <DockPanel> , который содержит элемент управления WebView2. Оставьте существующий код под новым фрагментом кода.

    <DockPanel DockPanel.Dock="Top">
    <Button x:Name="ButtonGo"
              DockPanel.Dock="Right"
              Click="ButtonGo_Click"
              Content="Go"
    />
    <TextBox Name="addressBar"/>
</DockPanel>

  2. Убедитесь, <DockPanel> что раздел MainWindow.xaml файла соответствует следующему коду:

    <DockPanel>
    <DockPanel DockPanel.Dock="Top">
        <Button x:Name="ButtonGo" DockPanel.Dock="Right" Click="ButtonGo_Click" Content="Go"/>
        <TextBox Name = "addressBar"/>
    </DockPanel>
    <wv2:WebView2 Name = "webView"
                  Source = "https://www.microsoft.com"
    />
</DockPanel>

  3. Чтобы MainWindow.xaml.csдобавить CoreWebView2 пространство имен, вставьте следующий код в начало файла:

    using Microsoft.Web.WebView2.Core;

  4. Скопируйте следующий код в MainWindow.xaml.csфайл, чтобы создать ButtonGo_Click метод . Этот код перемещает элемент управления WebView2 на URL-адрес, указанный в адресной строке.

    private void ButtonGo_Click(object sender, RoutedEventArgs e)
{
    if (webView != null && webView.CoreWebView2 != null)
    {
        webView.CoreWebView2.Navigate(addressBar.Text);
    }
}

  5. Вставьте код сразу после Public MainWIndow объявления, как показано в следующем коде:

    namespace WpfApp1
{
   /// <summary>
   /// Interaction logic for MainWindow.xaml
   /// </summary>
   public partial class MainWindow : Window
   {
      public MainWindow()
      {
            InitializeComponent();
      }
      void ButtonGo_Click(object sender, RoutedEventArgs e)
      {
            if (webView != null && webView.CoreWebView2 != null)
            {
               webView.CoreWebView2.Navigate(addressBar.Text);
            }
      }
   }
}

  6. Выберите Файл>Сохранить все , чтобы сохранить проект.

  7. Нажмите клавишу F5, чтобы выполнить сборку и запуск проекта.

  8. Введите новый URL-адрес в адресной строке и нажмите кнопку Перейти. Например, введите https://www.bing.com.

  9. Убедитесь, что элемент управления WebView2 открывает введенный URL-адрес.

    Убедитесь, что вы ввели полный URL-адрес в адресной строке. Приложение создает , ArgumentException если URL-адрес не начинается с http:// или https://.

    Пример приложения отображает веб-сайт Bing с URL-адресом https://www.bing.com в адресной строке:

    Приложение отображает веб-сайт Bing

Шаг 8. События навигации

Во время навигации по веб-странице элемент управления WebView2 вызывает события. Приложение, в котором размещаются элементы управления WebView2, прослушивает следующие события:

  • NavigationStarting
  • SourceChanged
  • ContentLoading
  • HistoryChanged
  • NavigationCompleted

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

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

Путь к успеху

Успешный путь включает полную последовательность событий:

  1. Начало навигации.
  2. Источник изменен, с возможными входными данными из того же документа.
  3. Загрузка содержимого.
  4. Изменения журнала.
  5. Навигация завершена.

Дополнительные сведения см. в разделе События навигации для приложений WebView2.

Путь сбоя

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

При возникновении ошибки возникают следующие события, которые могут зависеть от перехода на веб-страницу ошибки:

  • SourceChanged
  • ContentLoading
  • HistoryChanged

Перенаправление

Если происходит перенаправление HTTP, в строке имеется несколько NavigationStarting событий.

Пример, демонстрирующий события навигации

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

  1. В файле измените MainWindow.xaml.cs конструктор, чтобы он соответствовал верхней части следующего кода. Под конструктором добавьте функцию EnsureHttps :

    public MainWindow()
{
    InitializeComponent();
    webView.NavigationStarting += EnsureHttps;
}

void EnsureHttps(object sender, CoreWebView2NavigationStartingEventArgs args)
{
    String uri = args.Uri;
    if (!uri.StartsWith("https://"))
    {
        args.Cancel = true;
    }
}

    В конструкторе EnsureHttps регистрируется как обработчик события в элементе NavigationStarting управления WebView2.

  2. Выберите Файл>Сохранить все , чтобы сохранить проект.

  3. Нажмите клавишу F5, чтобы выполнить сборку и запуск проекта.

  4. Попытка открыть http-сайт. Убедитесь, что элемент управления WebView2 остается неизменным.

  5. Попытка открыть сайт HTTPS. Элемент управления WebView2 позволяет открывать сайты HTTPS.

Шаг 9. Создание скриптов

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

Внедренный Код JavaScript выполняется с определенным временем:

  • Запустите его после создания глобального объекта.
  • Запустите его перед выполнением любого другого скрипта, включенного в HTML-документ.

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

  1. Измените функцию EnsureHttps , чтобы внедрить скрипт в веб-содержимое, использующее метод ExecuteScriptAsync .

    void EnsureHttps(object sender, CoreWebView2NavigationStartingEventArgs args)
{
   String uri = args.Uri;
   if (!uri.StartsWith("https://"))
   {
      webView.CoreWebView2.ExecuteScriptAsync($"alert('{uri} is not safe, try an https link')");
      args.Cancel = true;
   }
}

  2. Выберите Файл>Сохранить все , чтобы сохранить проект.

  3. Нажмите клавишу F5, чтобы выполнить сборку и запуск проекта.

  4. Убедитесь, что приложение отображает оповещение при переходе на веб-сайт, который не использует HTTPS.

    Сообщение о том, что URL-адрес http: не является безопасным, и рекомендуется использовать URL-адрес https:

Шаг 10. Обмен данными между хост-содержимым и веб-сайтом

Содержимое узла и веб-сайта может взаимодействовать следующими способами с помощью postMessage:

  • Веб-содержимое в элементе управления WebView2 может отправлять сообщение на узел с помощью window.chrome.webview.postMessage. Узел обрабатывает сообщение с помощью любого зарегистрированного WebMessageReceived на узле.

  • Размещает публикацию сообщений в веб-содержимое в элементе управления WebView2 с помощью CoreWebView2.PostWebMessageAsString или CoreWebView2.PostWebMessageAsJSON. Сообщения перехватываются обработчиками, добавленными в window.chrome.webview.addEventListener.

Механизм связи передает сообщения из веб-содержимого на узел с помощью собственных возможностей.

В проекте, когда элемент управления WebView2 переходит по URL-адресу, он отображает URL-адрес в адресной строке и оповещает пользователя о URL-адресе, отображаемом в элементе управления WebView2.

  1. В MainWindow.xaml.csобновите конструктор и создайте функцию, соответствующую InitializeAsync приведенному ниже коду. Функция InitializeAsync ожидает EnsureCoreWebView2Async, так как инициализация выполняется асинхронно CoreWebView2 .

    public MainWindow()
{
   InitializeComponent();
   webView.NavigationStarting += EnsureHttps;
   InitializeAsync();
}

async void InitializeAsync()
{
   await webView.EnsureCoreWebView2Async(null);
}

  2. После инициализации CoreWebView2 зарегистрируйте обработчик событий для реагирования на WebMessageReceived. В MainWindow.xaml.csобновите InitializeAsync и добавьте UpdateAddressBar с помощью следующего кода:

    async void InitializeAsync()
{
   await webView.EnsureCoreWebView2Async(null);
   webView.CoreWebView2.WebMessageReceived += UpdateAddressBar;
}

void UpdateAddressBar(object sender, CoreWebView2WebMessageReceivedEventArgs args)
{
   String uri = args.TryGetWebMessageAsString();
   addressBar.Text = uri;
   webView.CoreWebView2.PostWebMessageAsString(uri);
}

  3. Чтобы элемент управления WebView2 отправлял веб-сообщение и реагировал на него, после CoreWebView2 инициализации узел выполняет следующие действия:

    1. Внедряет скрипт в веб-содержимое, который регистрирует обработчик для печати сообщения с узла.
    2. Внедряет скрипт в веб-содержимое, которое публикует URL-адрес на узле.

  4. В MainWindow.xaml.csобновите InitializeAsync , чтобы соответствовать следующему коду:

    async void InitializeAsync()
{
   await webView.EnsureCoreWebView2Async(null);
   webView.CoreWebView2.WebMessageReceived += UpdateAddressBar;

   await webView.CoreWebView2.AddScriptToExecuteOnDocumentCreatedAsync("window.chrome.webview.postMessage(window.document.URL);");
   await webView.CoreWebView2.AddScriptToExecuteOnDocumentCreatedAsync("window.chrome.webview.addEventListener(\'message\', event => alert(event.data));");
}

  5. Выберите Файл>Сохранить все , чтобы сохранить проект.

  6. Нажмите клавишу F5, чтобы выполнить сборку и запуск проекта.

  7. При открытии нового URI элемент управления WebView2 отображает URI в адресной строке.

    Пример приложения отображает универсальный код ресурса (URI) в адресной строке и на веб-сайте Майкрософт: https://www.microsoft.com

    Пример приложения отображает универсальный код ресурса (URI) в адресной строке и на веб-сайте Майкрософт

Поздравляем, вы создали свое первое приложение WebView2!

См. также

developer.microsoft.com:

  • Microsoft Edge WebView2 — начальное введение в функции WebView2 на developer.microsoft.com.

Локальные страницы:

Github: