WinUI 3 (Windows アプリ SDK) アプリでの WebView2 の概要

[アーティクル]
04/13/2024

この記事では、開発ツールを設定し、WinUI 3 用の初期 WebView2 アプリ (Windows アプリ SDK) を作成する方法と、その過程で WebView2 の概念について説明します。

このチュートリアルでは、 空のアプリ、パッケージ化 (デスクトップの WinUI) Visual Studio プロジェクトテンプレートを使用して、空白の WinUI 3 プロジェクトを作成します。そのプロジェクトテンプレートでは、WebView2 SDK を含む WindowsAppSDK が使用されます。 WebView2 コントロールを追加します。次に、アドレスバーとロジックを追加して、ユーザーがプレフィックス付きの URL に移動しようとしたときに警告ダイアログを http:// 表示します。

Bing Web サイトを表示するアプリ

完了したプロジェクト

このチュートリアルプロジェクトの完成したバージョン (2020 年時点) は 、WebView2Samples リポジトリで入手できます。

サンプル名: WinUI3_GettingStarted
リポジトリディレクトリ: WinUI3_GettingStarted
ソリューションファイル: WinUI_Sample.sln

現在のチュートリアルは更新され、2020 年のような 2 番目の "(Package)" プロジェクトではなく、1 つのプロジェクトのみが作成されます。

手順 1 - Visual Studio とWindows アプリ SDKをインストールする

Visual Studio がインストールされている場合でも、次のページを読み、ソフトウェアを更新してプロジェクトテンプレートをインストールする場合があります。

新しいウィンドウまたはタブで、[Windows アプリ SDKのツールのインストール] ページを開き、そのページの手順に従って、Visual Studio 2022 などの Microsoft Visual Studio をインストールします。

必要に応じて、新しいウィンドウまたはタブで、「WebView2 用の開発環境を設定する」の「Visual Studio のインストール」を参照してください。

そのページから戻り、次の手順に進みます。

このサンプルでは、WebView2 SDK を個別にインストールする必要はありません。次に、WebView2 SDK を含む WindowsAppSDK を使用するプロジェクトテンプレート の [パッケージ化済み (WinUI in Desktop)] を選択します。

手順 2 - Microsoft Edge のプレビューチャネルをインストールする

バージョン 1803 (ビルド 17134) 以降にインストールされている WebView2 ランタイムまたは Microsoft Edge プレビューチャネル (ベータ、開発、またはカナリア) Windows 10インストールします。

そのページから戻り、次の手順に進みます。

手順 3 - 空白の WinUI 3 プロジェクトを作成する

WebView2 アプリを作成するには、まず基本的なデスクトッププロジェクトを作成して、単一のメインウィンドウを含むデスクトップアプリを作成します。

Visual Studio が実行されていない場合は、Visual Studio を起動します (Visual Studio Code ではありません)。 Visual Studio のスタートアップウィンドウで、[新しいプロジェクトの作成] カードをクリックします。 [ 新しいプロジェクトの作成 ] ウィンドウが開きます。

または、Visual Studio が実行されている場合は、[ファイル>] [新しい>プロジェクト] を選択します。 [ 新しいプロジェクトの作成 ] ダイアログが開きます。

開発者モードを有効にする: 現在の記事の手順中のある時点で Visual Studio が開くと、コンピューターの開発者モードをオンにするように求められる場合があります。詳細については、必要に応じて、「Windows 用デスクトップアプリをビルドする」の「デバイスを開発用に有効にする」を参照してください。
[新しいプロジェクトの作成] ダイアログの [テンプレートのSearch] フィールドに、「デスクトップの WinUI 3」と入力します。
[空のアプリ]、[パッケージ (デスクトップの WinUI)] カードクリックして選択し、[次へ] ボタンをクリックします。

WinUI テンプレートが一覧にない場合は、Windows アプリ SDKの [ツールのインストール] から、上記のようにプロジェクトテンプレートをインストールする必要があります。テンプレートを表示するためのその他のヒント:

Visual Studio 2022 Community エディションの "既定の" オプションをインストールした後、Visual Studio インストーラーで .NET カードをクリックし、右側の [C# テンプレート] Windows アプリ SDKチェックボックスをオンにします。

正しいプロジェクトテンプレートがまだ表示されない場合は、Visual Studio インストーラーで UWP カードをクリックして選択し、右側の [v143 C++ ツール] チェックボックスをオンにして、[変更] ボタンをクリックします。

[ 新しいプロジェクトの構成 ] ダイアログが表示されます。
[ プロジェクト名 ] テキストボックスに、 MyWebView2WinUI3 などのプロジェクト名を入力します。
[ 場所 ] テキストボックスに、「」と入力するか、場所 (など C:\Users\username\Documents\WebView2) に移動します。
[作成] ボタンをクリックします。

新しい WinUI 3 プロジェクトは、Visual Studio のソリューションエクスプローラーで開きます。
- ファイルは App.xaml.cs 、アプリインスタンスを Application 表すクラスを定義します。
- ファイルはMainWindow.xaml.cs、MainWindowアプリインスタンスによって表示されるメインウィンドウを表すクラスを定義します。クラスは、WinUI の名前空間内の Microsoft.UI.Xaml 型から派生します。
[ ソリューション構成] ドロップダウンリスト (ウィンドウの上部の中央) で、[デバッグ] を選択 します。
[ ソリューションプラットフォーム ] ドロップダウンリストで、 x64 などのプラットフォームを選択します。
[ ファイル>すべて保存] (Ctrl + Shift + S) を選択して、プロジェクトを保存します。
F5 キーを押して、プロジェクトをビルドして実行します。空白の WinUI Desktop アプリが開き、WebView2 コントロールはまだ追加されていません。
アプリを閉じます。

ターゲットバージョン番号の更新

上記のビルド手順: 以前のプロジェクトを更新する場合は、 ターゲットバージョン と最小バージョンのバージョン番号を更新する必要がある場合があります。これを行うには、[ソリューション] でプロジェクトを右クリックし、[ プロジェクトファイルの編集] を選択します。ファイルが .csproj 開きます。値が次のように更新されていることを確認し、変更を保存してプロジェクトをビルドします。

    <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>

上記の値は次を表します。

ターゲットバージョン: Windows 10、バージョン 2004 (ビルド 19041) 以降。
最小バージョン: Windows 10 Version 1809 (ビルド 17763)。

手順 4 - WebView2 コントロールを追加する

このチュートリアルプロジェクトは、プロジェクトテンプレート Blank App Packaged (デスクトップの WinUI) に基づいています。このプロジェクトテンプレートでは、WebView2 SDK を含む WindowsAppSDK を使用します。

ファイルと MainWindow.xaml.cs ファイルをMainWindow.xaml編集して、次のように WebView2 コントロールを空白の WinUI 3 アプリプロジェクトに追加します。

Visual Studio のソリューションエクスプローラーで、ダブルクリックMainWindow.xamlしてコードエディターで開きます。

開始タグ内に次の属性を挿入して、WebView2 XAML 名前空間を <Window> 追加します。

xmlns:controls="using:Microsoft.UI.Xaml.Controls"

の MainWindow.xaml コードが次のようになります。

<Window
    x:Class="MyWebView2WinUI3.MainWindow"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:MyWebView2WinUI3"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d">

    <StackPanel Orientation="Horizontal" HorizontalAlignment="Center" VerticalAlignment="Center">
        <Button x:Name="myButton" Click="myButton_Click">Click Me</Button>
    </StackPanel>
</Window>

WebView2 コントロールを追加するには、要素全体 <StackPanel> を次 <Grid> のコードに置き換えます。プロパティは Source 、下部の近くに、WebView2 コントロール (https://www.microsoft.com) に表示される最初の URI を設定します。

<Grid>

    <Grid.RowDefinitions>
        <RowDefinition Height="Auto"/>
        <RowDefinition Height="*"/>
    </Grid.RowDefinitions>
    <Grid.ColumnDefinitions>
        <ColumnDefinition Width="*"/>
        <ColumnDefinition Width="Auto"/>
    </Grid.ColumnDefinitions>

    <controls:WebView2 x:Name="MyWebView"  Grid.Row="1" Grid.ColumnSpan="2"
        Source="https://www.microsoft.com" HorizontalAlignment="Stretch" VerticalAlignment="Stretch"/>

</Grid>

ソリューションエクスプローラーでを展開MainWindow.xamlし、を開きますMainWindow.xaml.cs。
で MainWindow.xaml.cs、次の行をコメントアウトします。
```
    // myButton.Content = "Clicked";
```
[ ファイル>すべて保存] (Ctrl + Shift + S) を選択して、プロジェクトを保存します。
F5 キーを押してプロジェクトをビルドして実行します。
アプリは、WebView2 コントロールを含む WebView2 ホストアプリです。 WebView2 コントロールには、Web サイト https://www.microsoft.comが表示されます。
アプリを閉じます。

WinAppSDK では、カスタム WebView2 環境がサポートされます

WinAppSDK では、WinAppSDK 1.5 (1.5.0-experimental2) 以降のカスタム WebView2 環境がサポートされています。詳細については、「 WinUI3 WebView2 とカスタム CoreWebView2Environment」を参照してください。

カスタム WebView2 環境をインスタンス化するには、(以下に示す) のいずれかのオーバーライド WebView2.EnsureCoreWebView2Async を使用して WebView2 を初期化し、カスタム CoreWebView2Environment (および必要に応じてカスタム CoreWebView2ControllerOptions) を渡します。

public IAsyncAction EnsureCoreWebView2Async (CoreWebView2Environment environment)
public IAsyncAction EnsureCoreWebView2Async (CoreWebView2Environment environment, CoreWebView2ControllerOptions controllerOptions)

以下の「SmartScreen ナビゲーションを無効にする」のコード例も参照してください。

API リファレンス:

ユーザーが WebView2 コントロールに表示される Web ページを制御できるようにするには、次のようにアドレスバーをアプリに追加します。

で MainWindow.xaml、要素を含む要素内に <Grid> 次のコードを <controls:WebView2> 貼り付けます。

   <TextBox Name="addressBar" Grid.Column="0"/>
   <Button x:Name="myButton" Grid.Column="1" Click="myButton_Click">Go</Button>

ファイル内の結果 <Grid> の要素が MainWindow.xaml 次の要素と一致することを確認します。

<Grid>

    <Grid.RowDefinitions>
        <RowDefinition Height="Auto"/>
        <RowDefinition Height="*"/>
    </Grid.RowDefinitions>
    <Grid.ColumnDefinitions>
        <ColumnDefinition Width="*"/>
        <ColumnDefinition Width="Auto"/>
    </Grid.ColumnDefinitions>

    <TextBox Name="addressBar" Grid.Column="0"/>
    <Button x:Name="myButton" Grid.Column="1" Click="myButton_Click">Go</Button>

    <controls:WebView2 x:Name="MyWebView"  Grid.Row="1" Grid.ColumnSpan="2"
    Source="https://www.microsoft.com" HorizontalAlignment="Stretch" VerticalAlignment="Stretch"/>

</Grid>

で MainWindow.xaml.cs、次のコードをに myButton_Click貼り付け、既存 myButton_Click のメソッド (ほぼ空) を上書きします。このコードは、WebView2 コントロールをアドレスバーに入力された URL に移動します。
```
private void myButton_Click(object sender, RoutedEventArgs e)
{
    try
    {
        Uri targetUri = new Uri(addressBar.Text);
        MyWebView.Source = targetUri;
    }
    catch (FormatException ex)
    {
        // Incorrect address entered.
    }
}
```
[ ファイル>すべて保存] (Ctrl + Shift + S) を選択して、プロジェクトを保存します。
F5 キーを押して、プロジェクトをビルドして実行します。
アドレスバーに新しい完全な URL (など https://www.bing.com) を入力し、[ 移動 ] ボタンをクリックします。

アプリの WebView2 コントロールには、Bing Web サイトが表示されます。アドレスバーには、次のような https://www.bing.comURL が表示されます。
などの不完全な URL をアドレスバー bing.comに入力し、[ 移動 ] ボタンをクリックします。

ArgumentException URL がまたは https://でhttp://始まらないため、アプリを閉じると例外がスローされ、表示されます。
アプリを閉じます。

このセクションでは、WebView2 Core ライブラリをインポートするコードを追加します。

で MainWindow.xaml.cs、他 using のステートメントの上の一番上に次の行を追加します。
```
using Microsoft.Web.WebView2.Core;
```
WebView2 コントロールをホストするアプリは、Web ページナビゲーション中に WebView2 コントロールによって発生する次のイベントをリッスンします。
- NavigationStarting
- SourceChanged
- ContentLoading
- HistoryChanged
- NavigationCompleted
HTTP リダイレクトが発生した場合、1 行に複数 NavigationStarting のイベントがあります。

詳細については、「 WebView2 アプリのナビゲーションイベント」を参照してください。

エラーが発生すると、次のイベントが発生し、エラー Web ページが表示される場合があります。
- SourceChanged
- ContentLoading
- HistoryChanged
イベントの使用方法の例として、次のように、HTTPS 以外の要求を取り消すハンドラー NavigationStarting を登録します。
で MainWindow.xaml.cs、コンストラクターに次 NavigationStarting の行を追加して、メソッドを EnsureHttps 登録します。
```
public MainWindow()
{
    this.InitializeComponent();
    MyWebView.NavigationStarting += EnsureHttps;
}
```

コンストラクター MainWindow.xaml.csの下に、次 EnsureHttps のメソッドを追加します。

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

[ ファイル>すべて保存] (Ctrl + Shift + S) を選択して、プロジェクトを保存します。
F5 キーを押して、プロジェクトをビルドして実行します。
アプリの [アドレス] バーに、などの http://bing.comHTTP URL を入力し、[ 移動 ] ボタンをクリックします。

HTTP サイトへのナビゲーションがブロックされており、フィードバックを提供するためのダイアログがまだ追加されていないため、何も起こりません。
などの https://bing.comHTTPS URL を入力し、[ 移動 ] ボタンをクリックします。

HTTPS サイトではナビゲーションが許可されているため、アプリは指定したページに移動します。
アプリを閉じます。

手順 7 - スクリプト

ホストアプリを使用すると、実行時に JavaScript コードを WebView2 コントロールに挿入できます。 WebView2 をタスクして、任意の JavaScript を実行したり、初期化スクリプトを追加したりできます。挿入された JavaScript は、JavaScript が削除されるまで、すべての新しい最上位ドキュメントと子フレームに適用されます。挿入された JavaScript は、次のいずれかのタイミングで実行されます。

グローバルオブジェクトの作成後に、挿入された JavaScript を実行します。
挿入された JavaScript を実行してから、HTML ドキュメントに含まれている他のスクリプトを実行します。

たとえば、次に、ユーザーが HTTPS 以外のサイトを開こうとしたときにアラートを送信するスクリプトを追加します。これを行うには、 ExecuteScriptAsync を使用する Web コンテンツにスクリプトを挿入します。

メソッドで EnsureHttps 、次 ExecuteScriptAsync の行を追加します。

private void EnsureHttps(WebView2 sender, CoreWebView2NavigationStartingEventArgs args)
{
    String uri = args.Uri;
    if (!uri.StartsWith("https://"))
    {
        MyWebView.ExecuteScriptAsync($"alert('{uri} is not safe, try an https link')");
        args.Cancel = true;
    }
    else
    {
        addressBar.Text = uri;
    }
}

[ ファイル>すべて保存] (Ctrl + Shift + S) を選択して、プロジェクトを保存します。
F5 キーを押して、プロジェクトをビルドして実行します。
アプリのアドレスバーに、HTTPS 以外の URL (など http://www.bing.com) を入力し、[ 移動 ] ボタンをクリックします。

アプリの WebView2 コントロールには、HTTPS 以外の Web サイトのアラートダイアログが表示され、HTTPS uri 以外の Web サイトは安全ではないというメッセージが表示されます。
アプリを閉じます。

これで、初めての WebView2 アプリが作成されました。

WinUI 3 WebView2 の特別な考慮事項

WebView2 は、アプリケーション内のに移動した URL を SmartScreen サービスに送信して、顧客のセキュリティを確保します。このナビゲーションを無効にする場合は、次のようにカスタム CoreWebView2Environmentのを使用します。

CoreWebView2EnvironmentOptions environmentOptions = new CoreWebView2EnvironmentOptions();
environmentOptions.AdditionalBrowserArguments = "--disable-features=msSmartScreenProtection";

string browserFolder = null; // Use null to get default browser folder
string userDataFolder = null; // Use null to get default user data folder
CoreWebView2Environment environment = await CoreWebView2Environment.CreateWithOptionsAsync(
    browserFolder, userDataFolder, environmentOptions);

// ...

this.WebView2.EnsureCoreWebView2Async(environment);

環境変数を使用して SmartScreen を無効にする

環境変数の使用は推奨されなくなりました。代わりに、上記の API コードベースのアプローチを使用してください。

Environment.SetEnvironmentVariable("WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS", "--disable-features=msSmartScreenProtection");

この環境変数は、作成前に CoreWebView2 設定する必要があります。これは、 WebView2.Source プロパティが最初に設定されたとき、または WebView2.EnsureCoreWebView2Async メソッドが最初に呼び出されたときに発生します。

DefaultBackgroundColor の設定

WebView2 for WinUI 3 では、設定は DefaultBackgroundColor WebView2 XAML オブジェクトに存在します。以下に例を示します。

public MainWindow()
{
    this.InitializeComponent();
    MyWebView.DefaultBackgroundColor = Colors.LightBlue;
}

Transparency

WinUI 3 では、透明な背景はサポートされていません。 WebView2 の透過的な背景のサポートを参照してください。 ·問題 #2992。

カスタム WebView2 環境に対する WinAppSDK のサポート

上記の「WinAppSDK でカスタム WebView2 環境がサポートされる」を参照してください。

WinUI 3 (Windows アプリ SDK) アプリでの WebView2 の概要

完了したプロジェクト

手順 1 - Visual Studio とWindows アプリ SDKをインストールする

手順 2 - Microsoft Edge のプレビューチャネルをインストールする

手順 3 - 空白の WinUI 3 プロジェクトを作成する

ターゲットバージョン番号の更新

手順 4 - WebView2 コントロールを追加する

WinAppSDK では、カスタム WebView2 環境がサポートされます

手順 5 - ナビゲーションコントロールを追加する

手順 6 - ナビゲーションイベント

手順 7 - スクリプト

WinUI 3 WebView2 の特別な考慮事項

SmartScreen ナビゲーションを無効にする

環境変数を使用して SmartScreen を無効にする

DefaultBackgroundColor の設定

Transparency

カスタム WebView2 環境に対する WinAppSDK のサポート

関連項目

その他のリソース

WinUI 3 (Windows アプリ SDK) アプリでの WebView2 の概要

完了したプロジェクト

手順 1 - Visual Studio とWindows アプリ SDKをインストールする

手順 2 - Microsoft Edge のプレビュー チャネルをインストールする

手順 3 - 空白の WinUI 3 プロジェクトを作成する

ターゲット バージョン番号の更新

手順 4 - WebView2 コントロールを追加する

WinAppSDK では、カスタム WebView2 環境がサポートされます

手順 5 - ナビゲーション コントロールを追加する

手順 6 - ナビゲーション イベント

手順 7 - スクリプト

WinUI 3 WebView2 の特別な考慮事項

SmartScreen ナビゲーションを無効にする

環境変数を使用して SmartScreen を無効にする

DefaultBackgroundColor の設定

Transparency

カスタム WebView2 環境に対する WinAppSDK のサポート

関連項目

その他のリソース

手順 2 - Microsoft Edge のプレビューチャネルをインストールする

ターゲットバージョン番号の更新

手順 5 - ナビゲーションコントロールを追加する

手順 6 - ナビゲーションイベント