Пример приложения WinUI 3 (Windows App SDK)

Статья
11/07/2024

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

В этом примере показано использование элемента управления WebView2 в упаковавом приложении WinUI 3 (Windows App SDK).

Пример приложения

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

Пакеты NuGet и компоненты рабочей нагрузки

Перед сборкой мы сделаем следующее:

Обновите пакет NuGet Microsoft.Windows.SDK.BuildTools для проекта и проекта (Пакет).
Обновите пакет NuGet Microsoft.WindowsAppSDK для проекта и проекта (Пакет).
Установите компонент "пакет SDK для Windows 10" рабочей нагрузки "Разработка приложений для Windows", если он еще не установлен.

Каталоги

Каталог	Содержание
WebView2_WinUI3_Sample	Код проекта
WebView2_WinUI3_Sample (пакет)	Проект упаковки и распространения
WebView2_WinUI3_Sample (пакет)\FixedRuntime	(Необязательно) Исправлена среда выполнения WebView2
WebView2_WinUI3_Sample (пакет)\FixedRuntime\130.0.2849.39	(Необязательно) Исправлен пример среды выполнения WebView2

Шаг 1. Установка последней версии Visual Studio 2022

Убедитесь, что Visual Studio 2022 установлена и обновлена.

Чтобы установить последнюю версию Visual Studio 2022, выполните следующие действия:

Перейдите в Visual Studio: интегрированная среда разработки и Код Редактор для разработчиков программного обеспечения и Teams, а затем в разделе Visual Studio 2022 нажмите кнопку Скачать, а затем выберите Community 2022 или другую версию.
Во всплывающем окне Загрузки в правом верхнем углу Microsoft Edge VisualStudioSetup.exe отображается список. Щелкните Открыть файл.

откроется Visual Studio Installer.
Следуйте инструкциям и примите значения по умолчанию.

Шаг 2. Клонирование или скачивание репозитория WebView2Samples

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

Шаг 3. Открытие решения в Visual Studio

Эти начальные шаги для репозитория и ветви не требуются, но они рекомендуется, чтобы избежать изменения кода, который находится в ветви "main" клонируемой копии репозитория WebView2Samples. Это позволяет изменять файлы проекта (для сборки и запуска примера), сохраняя при этом код, который находится в ветви "main", идентичен репозиторию.

Эти действия можно выполнить в любом средстве для операций Git, например:

GitHub Desktop.
Вкладка Изменения Git рядом с вкладкой Обозреватель решений в правом нижнем углу Visual Studio.
Командная строка git bash.

Чтобы открыть файл решения примера в рабочей ветви, выполните следующие действия:

В GitHub Desktop в списке Текущий репозиторий в левом верхнем углу выберите репозиторий WebView2Samples .
Щелкните Получить источник в верхней середине окна.
В меню Текущая ветвь создайте рабочую ветвь, например user/myGithubUsername/winui3-sample , и переключитесь на нее.

Теперь вы безопасно находитесь в рабочей ветви, а не в ветви "main", и можете приступить к изменению файлов примера.
На локальном .sln диске откройте файл в Visual Studio.

Примеры расположений .sln файла: если вы клонировали репозиторий, имя каталога репозитория будет:/WebView2Samples/

<your-repos-directory>/WebView2Samples/SampleApps/WebView2_WinUI3_Sample/WebView2_WinUI3_Sample.sln

Если вы скачали репозиторий, имя каталога репозитория — /WebView2Samples-main/, представляющее ветвь "main":

<your-repos-directory>/WebView2Samples-main/SampleApps/WebView2_WinUI3_Sample/WebView2_WinUI3_Sample.sln

Шаг 4. Обновление пакетов NuGet

В Обозреватель решений щелкните правой кнопкой мыши проект WebView2_WinUI3_Sample и выберите Управление пакетами NuGet.

В Visual Studio откроется диспетчер пакетов NuGet :

Выбрана вкладка Установленные со списком пакетов NuGet:
- Microsoft.Windows.SDK.BuildTools
- Microsoft.WindowsAppsDK
- Microsoft.Web.WebView2
Перейдите на вкладку Обновления.
В левом верхнем углу установите флажок Выбрать все пакеты .
Справа от этого флажка нажмите кнопку Обновить .

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

Откроется диалоговое окно Принятие лицензии .
Нажмите кнопку Принимаю .

Пакеты NuGet обновляются, а число рядом с вкладкой Обновления удаляется.
Откройте меню Вид, а затем выберите меню Выводвывыберите.

На вкладке Вывод в раскрывающемся списке Показать выходные данные из выбран диспетчер пакетов . Выходные данные включают такие строки, как:
```
Installing NuGet package Microsoft.Windows.SDK.BuildTools
Installing NuGet package Microsoft.WindowsAppSDK

Successfully uninstalled 'Microsoft.Windows.SDK.BuildTools
Successfully uninstalled 'Microsoft.WindowsAppSDK

Successfully installed 'Microsoft.Web.WebView2
Successfully installed 'Microsoft.Windows.SDK.BuildTools
Successfully installed 'Microsoft.WindowsAppSDK
```
Обновление пакетов NuGet в проекте (Пакет)
В Обозреватель решений щелкните правой кнопкой мыши проект WebView2_WinUI3_Sample (пакет) и выберите Управление пакетами NuGet.
Перейдите на вкладку Обновления.
В левом верхнем углу установите флажок Выбрать все пакеты .
Справа от этого флажка нажмите кнопку Обновить .

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

Откроется диалоговое окно Принятие лицензии .
Нажмите кнопку Принимаю .

Пакеты NuGet обновляются, а число рядом с вкладкой Обновления удаляется.
Откройте меню Вид, а затем выберите меню Выводвывыберите.

На вкладке Вывод в раскрывающемся списке Показать выходные данные из выбран диспетчер пакетов . Выходные данные включают строки, как показано выше.
Закройте окно диспетчера пакетов NuGet .

Шаг 5. Установка пакета SDK для Windows 10 или других компонентов рабочей нагрузки

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

Чтобы установить компонент пакета SDK для Windows 10 рабочей нагрузки разработки приложений для Windows, выполните следующие действия:

В Visual Studio щелкните меню Сервис , а затем выберите пункт Меню Получить инструменты и компоненты .

Откроется окно Visual Studio Installer.
Выберите карта разработки приложений для Windows, чтобы появилась галочка.
В дереве Сведения об установке справа установите флажок компонент пакета SDK Windows 10 10.0.19041.0.
Нажмите кнопку Изменить .

Откроется диалоговое окно Контроль учетных записей пользователей .
Нажмите кнопку Да .

Откроется диалоговое окно Перед началом работы (Visual Studio Installer) с предложением сохранить работу в Visual Studio.
Закройте main окно Visual Studio, сохранив при необходимости.
В диалоговом окне Перед началом работы нажмите кнопку Повторить .

Через несколько минут компонент рабочей нагрузки пакета SDK для Windows 10 10.0.19041.0 будет скачан и установлен. Visual Studio Installer говорит: "Все установки актуальны".

Шаг 6. Сборка и запуск приложения

Откройте решение в Visual Studio 2022. Например, в Visual Studio Installer в разделе Visual Studio 2022 нажмите кнопку Запустить.

Откроется средство запуска Visual Studio с разделами Открыть недавно и Начало работы.
В разделе Открыть последние выберите WebView2_WinUI3_Sample.sln.

Решение откроется в Visual Studio 2022.
Нажмите клавишу F5.

В Обозреватель решений проект (Пакет) выделен полужирным шрифтом, что указывает на то, что это проект по умолчанию. Приложение будет создано, а затем откроется окно приложения WebView2_WinUI3_Sample (пакет):

Внизу отображается сообщение "Навигация завершена".
В адресной строке (текстовое поле) введите https://bing.com (полный URL-адрес HTTPS) и нажмите клавишу ВВОД (эквивалентно нажатию кнопки Go ).

Элемент управления WebView2 переходит к Bing, а затем внизу отображается сообщение "Навигация завершена".

В Visual Studio в окне Вывод отображаются такие сообщения, как:
```
AddressBar_KeyDown [Enter]: https://bing.com
TryNavigate
TryCreateUri
Navigation complete
```

Шаг 7. Фиксация изменений в рабочей ветви

В средстве Git, таком как GitHub Desktop, на этом этапе можно зафиксировать изменения и при необходимости отправить их в вилку филиала на сайте GitHub. Эти типы операций актуальны при изменении, эксперименте и настройке примера. Это также обеспечивает очистку рабочей ветви и упорядочение клона репозитория, чтобы можно было переключиться на другой пример.

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

В Visual Studio выберите Файл>сохранить все (CTRL+SHIFT+S).
В GitHub Desktop введите краткое сообщение о фиксации, например "обновленный, созданный, запущенный пример", а затем нажмите кнопку Фиксация .
Выберите Отправить репозиторий>. Рабочая ветвь копируется с локального диска в разветвленную ветвь репозитория WebView2Samples на сайте GitHub.

Просмотр рабочей ветви на сайте GitHub
В Microsoft Edge перейдите к вилке репозитория, например https://github.com/myGithubUsername/WebView2Samples/.
Щелкните ссылку [#] Ветви и выберите новую рабочую ветвь, например user/myGithubUsername/winui3-sample.

Шаг 8. Проверка кода

Закройте приложение WebView2_WinUI3_Sample (Пакет).
В Обозреватель решений в проекте WebView2_WinUI3_Sample дважды щелкните каждый .xaml файл и его .cs файл:
- App.xaml — Нет кода WebView2.
  - App.cs — Код для использования среды выполнения WebView2 фиксированной версии.
- MainWindow.xaml — Элементы WebView2.
  - MainWindow.cs — код WebView2.

Ниже приведены сокращенные версии этих файлов.

App.xaml

В этом файле нет кода, относягося к WebView2.

Сокращенный список

<Application
    x:Class="WebView2_WinUI3_Sample.App"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:WebView2_WinUI3_Sample">
    <Application.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>
                <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
            </ResourceDictionary.MergedDictionaries>
        </ResourceDictionary>
    </Application.Resources>
</Application>

App.cs

Код WebView2 в этом файле закомментирован. Эти строки можно снять с комментариев, чтобы использовать среду выполнения фиксированной версии. См . раздел Использование среды выполнения WebView2 фиксированной версии ниже.

Сокращенный список

namespace WebView2_WinUI3_Sample
{
    /// <summary>
    /// Provides application-specific behavior to supplement the default Application class.
    /// </summary>
    public partial class App : Application
    {
        /// <summary>
        /// Initializes the singleton application object.  Equivalent to main() or WinMain().
        /// </summary>
        public App()
        {
            this.InitializeComponent();

            // If you're shipping a fixed-version WebView2 Runtime with your app, un-comment the
            // following lines of code, and change the version number to the version number of the
            // WebView2 Runtime that you're packaging and shipping to users:

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

        /// <summary>
        /// Invoked when the application is launched normally by the end user.
        /// </summary>
        /// <param name="args">Details about the launch request and process.</param>
        protected override void OnLaunched(Microsoft.UI.Xaml.LaunchActivatedEventArgs args)
        {
            m_window = new MainWindow();
            m_window.Activate();
        }

        private Window m_window;
    }
}

MainWindow.xaml

В окне main есть следующие элементы XAML в качестве элементов управления:

<TextBox> — Адресная строка.
<Button> — Кнопка "Перейти ".
<WebView2> — элемент управления WebView2.
<TextBlock> — строка состояния.

Сокращенный список

<Window
    xmlns:local="using:WebView2_WinUI3_Sample">
    <Grid>
        <Grid.RowDefinitions>
        </Grid.RowDefinitions>
        <Grid Grid.Row="0" Background="LightGray">
            <TextBox Grid.Column="0"  x:Name="AddressBar" KeyDown="AddressBar_KeyDown" VerticalAlignment="Center" Margin="10,0,0,0"/>
            <Button Grid.Column="1" x:Name="Go" Content="Go" Click="Go_OnClick" VerticalAlignment="Center" HorizontalAlignment="Center"/>
        </Grid>

        <WebView2 x:Name="WebView2" Grid.Row="1"/>

        <Rectangle Grid.Row="2" Fill="LightGray"/>
        <TextBlock x:Name="StatusBar" Text="WebView2" VerticalAlignment="Center" Grid.Row="2" Margin="10,0,10,0"/>
    </Grid>
</Window>

MainWindow.cs

Класс MainWindow имеет следующие методы:

Конструктор
StatusUpdate
WebView2_CoreWebView2Initialized
WebView2_NavigationCompleted
TryCreateUri
TryNavigate
Go_OnClick
AddressBar_KeyDown
SetTitle
GetWebView2Version

Ниже приведены фрагменты или сокращенные версии этих методов.

Класс MainWindow

using Microsoft.Web.WebView2.Core;

namespace WebView2_WinUI3_Sample
{
    /// <summary>
    /// An empty window that can be used on its own or navigated to within a Frame.
    /// </summary>
    public sealed partial class MainWindow : Window
    {

constructor

public MainWindow()
{
    this.InitializeComponent();

    Closed += (obj, eventArgs) =>
    {
        if (WebView2 != null)
        {
            // Ensure that WebView2 resources are released when
            // the MainWindow is closed. 
            // WebView2 lifecycle in WinUI3 and the Close() method:
            // https://github.com/microsoft/microsoft-ui-xaml/issues/4752#issuecomment-819687363
            WebView2.Close();
        }
    };

    AddressBar.Text = "https://developer.microsoft.com/en-us/microsoft-edge/webview2/";

    WebView2.NavigationCompleted += WebView2_NavigationCompleted;
    WebView2.CoreWebView2Initialized += WebView2_CoreWebView2Initialized;

    WebView2.Source = new Uri(AddressBar.Text);
    StatusUpdate("Ready");
    SetTitle();
}

StatusUpdate

private void StatusUpdate(string message)
{
    StatusBar.Text = message;
    Debug.WriteLine(message);
}

WebView2_CoreWebView2Initialized

private void WebView2_CoreWebView2Initialized(WebView2 sender, CoreWebView2InitializedEventArgs args)
{
    if (args.Exception != null)
    {
        StatusUpdate($"Error initializing WebView2: {args.Exception.Message}");
    }
    else
    {
        SetTitle(sender);
    }
}

WebView2_NavigationCompleted

private void WebView2_NavigationCompleted(WebView2 sender, CoreWebView2NavigationCompletedEventArgs args)
{
    StatusUpdate("Navigation complete");

    // Update the address bar with the full URL that was navigated to.
    AddressBar.Text = sender.Source.ToString();
}

TryCreateUri

private bool TryCreateUri(String potentialUri, out Uri result)
{
    StatusUpdate("TryCreateUri");

    Uri uri;
    if ((Uri.TryCreate(potentialUri, UriKind.Absolute, out uri) || Uri.TryCreate("http://" + potentialUri, UriKind.Absolute, out uri)) &&
        (uri.Scheme == Uri.UriSchemeHttp || uri.Scheme == Uri.UriSchemeHttps))
    {
        result = uri;
        return true;
    }
    else
    {
        StatusUpdate("Unable to configure URI");
        result = null;
        return false;
    }
}

TryNavigate

private void TryNavigate()
{
    StatusUpdate("TryNavigate");

    Uri destinationUri;
    if (TryCreateUri(AddressBar.Text, out destinationUri))
    {
        WebView2.Source = destinationUri;
    }
    else
    {
        StatusUpdate("URI couldn't be figured out use it as a bing search term");

        String bingString = $"https://www.bing.com/search?q={Uri.EscapeDataString(AddressBar.Text)}";
        if (TryCreateUri(bingString, out destinationUri))
        {
            AddressBar.Text = destinationUri.AbsoluteUri;
            WebView2.Source = destinationUri;
        }
        else
        {
            StatusUpdate("URI couldn't be configured as bing search term, giving up");
        }
    }
}

Go_OnClick

private void Go_OnClick(object sender, RoutedEventArgs e)
{
    StatusUpdate("Go_OnClick: " + AddressBar.Text);

    TryNavigate();
}

AddressBar_KeyDown

private void AddressBar_KeyDown(object sender, KeyRoutedEventArgs e)
{
    if (e.Key == Windows.System.VirtualKey.Enter)
    {
        StatusUpdate("AddressBar_KeyDown [Enter]: " + AddressBar.Text);

        e.Handled = true;
        TryNavigate();
    }
}

SetTitle

private void SetTitle(WebView2 webView2 = null)
{
    var packageDisplayName = Windows.ApplicationModel.Package.Current.DisplayName;
    var webView2Version = (webView2 != null) ? " - " + GetWebView2Version(webView2) : string.Empty;
    Title = $"{packageDisplayName}{webView2Version}";
}

GetWebView2Version

private string GetWebView2Version(WebView2 webView2)
{
    var runtimeVersion = webView2.CoreWebView2.Environment.BrowserVersionString;

    CoreWebView2EnvironmentOptions options = new CoreWebView2EnvironmentOptions();
    var targetVersionMajorAndRest = options.TargetCompatibleBrowserVersion;
    var versionList = targetVersionMajorAndRest.Split('.');
    if (versionList.Length != 4)
    {
        return "Invalid SDK build version";
    }
    var sdkVersion = versionList[2] + "." + versionList[3];

    return $"{runtimeVersion}; {sdkVersion}";
}

Использование среды выполнения WebView2 с фиксированной версией

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

На следующих шагах отображается номер 130.0.2849.39версии среды выполнения. Вы измените этот номер на любую версию, которую вы упаковываете и отправляете.

Чтобы использовать среду выполнения фиксированной версии, выполните следующие действия.

Включите фиксированную среду выполнения WebView2 в проект пакета:
```
\WebView2_WinUI3_Sample\WebView2_WinUI3_Sample (Package)\FixedRuntime\130.0.2849.39\
```
Выше используйте версию, которую вы отправляете, а не 130.0.2849.39.
Обновите файл проекта wapproj пакета для используемой версии (используйте свою версию 130.0.2849.39вместо ):
```
< Content Include="FixedRuntime\130.0.2849.39\\**\*.*" >
```

В App.xaml.csраскомментируйте пять закомментированных строк кода под комментарием, чтобы включить переопределение среды выполнения:

public App()
{
   this.InitializeComponent();

   // If you're shipping a fixed-version WebView2 Runtime with your app, un-comment the
   // following lines of code, and change the version number to the version number of the
   // WebView2 Runtime that you're packaging and shipping to users:

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

В приведенном выше коде измените номер версии с 130.0.2849.39 на версию, которую вы отправляете.

Поделиться через

Пример приложения WinUI 3 (Windows App SDK)

Пакеты NuGet и компоненты рабочей нагрузки

Каталоги

Шаг 1. Установка последней версии Visual Studio 2022

Шаг 2. Клонирование или скачивание репозитория WebView2Samples

Шаг 3. Открытие решения в Visual Studio

Шаг 4. Обновление пакетов NuGet

Шаг 5. Установка пакета SDK для Windows 10 или других компонентов рабочей нагрузки

Шаг 6. Сборка и запуск приложения

Шаг 7. Фиксация изменений в рабочей ветви

Шаг 8. Проверка кода

App.xaml

Сокращенный список

App.cs

Сокращенный список

MainWindow.xaml

Сокращенный список

MainWindow.cs

Класс MainWindow

constructor

StatusUpdate

WebView2_CoreWebView2Initialized

WebView2_NavigationCompleted

TryCreateUri

TryNavigate

Go_OnClick

AddressBar_KeyDown

SetTitle

GetWebView2Version

Использование среды выполнения WebView2 с фиксированной версией

См. также

Обратная связь

Дополнительные ресурсы