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

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

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

完了したプロジェクト

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

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

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

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

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

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

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

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

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

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

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

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

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

   開発者モードを有効にする: 現在の記事の手順中のある時点で Visual Studio が開くと、コンピューターの開発者モードをオンにするように求められる場合があります。 詳細については、必要に応じて、「Windows 用デスクトップ アプリをビルドする」の「デバイスを開発用に有効にする」を参照してください。

2. [ 新しいプロジェクトの作成 ] ダイアログの [ テンプレートの検索 ] フィールドに、「 デスクトップ」に「WinUI 3」と入力します。

   

3. [ 空のアプリ、パッケージ化された (デスクトップの WinUI)] カードをクリックして選択し、[ 次へ ] ボタンをクリックします。

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

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

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

   [ 新しいプロジェクトの構成 ] ダイアログが表示されます。

4. [ プロジェクト名 ] テキスト ボックスに、 MyWebView2WinUI3 などのプロジェクト名を入力します。

   

5. [ 場所 ] テキスト ボックスに「」と入力するか、 C:\Users\username\Documents\WebView2などの場所に移動します。

6. [作成] ボタンをクリックします。

   Visual Studio のソリューション エクスプローラーで新しい WinUI 3 プロジェクトが開きます。

   

   • App.xaml.cs ファイルは、アプリ インスタンスを表す Application クラスを定義します。

   • MainWindow.xaml.cs ファイルは、アプリ インスタンスによって表示されるメイン ウィンドウを表す MainWindow クラスを定義します。 クラスは、WinUI の Microsoft.UI.Xaml 名前空間の型から派生します。

7. [ ソリューション構成] ドロップダウン リスト (ウィンドウの上部の中央) で、[デバッグ] を選択 します。

8. [ ソリューション プラットフォーム ] ドロップダウン リストで、 x64 などのプラットフォームを選択します。

9. [ ファイル>すべて保存 (Ctrl + Shift + S) を選択してプロジェクトを保存します。

10. F5 キーを押して、プロジェクトをビルドして実行します。 空白の WinUI Desktop アプリが開き、WebView2 コントロールはまだ追加されていません。

    

11. アプリを閉じます。

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

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

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

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

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

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

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

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

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

2. 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>
   

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

   <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>
   

4. ソリューション エクスプローラーで、[ MainWindow.xaml ] を展開し、[ MainWindow.xaml.cs] を開きます。

5. MainWindow.xaml.csで、次の行をコメントアウトします。

       // myButton.Content = "Clicked";
   

6. [ ファイル>すべて保存 (Ctrl + Shift + S) を選択してプロジェクトを保存します。

7. F5 キーを押してプロジェクトをビルドして実行します。

8. アプリは、WebView2 コントロールを含む WebView2 ホスト アプリです。 WebView2 コントロールには、Web サイトの https://www.microsoft.comが表示されます。

   

9. アプリを閉じます。

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.EnsureCoreWebView2Async
• CoreWebView2ControllerOptions
• CoreWebView2Environment
• CoreWebView2EnvironmentOptions

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

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

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

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

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

   <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>
   

2. 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.
       }
   }
   

3. [ ファイル>すべて保存 (Ctrl + Shift + S) を選択してプロジェクトを保存します。

4. F5 キーを押して、プロジェクトをビルドして実行します。

5. https://www.bing.comなど、アドレス バーに新しい完全な URL を入力し、[移動] ボタンをクリックします。

   アプリの WebView2 コントロールには、Bing Web サイトが表示されます。 アドレス バーには、 https://www.bing.comなどの URL が表示されます。

   

6. bing.comなど、アドレス バーに不完全な URL を入力し、[移動] ボタンをクリックします。

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

7. アプリを閉じます。

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

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

1. 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 のハンドラーを次のように登録します。

2. MainWindow.xaml.csのコンストラクターで、次のNavigationStarting行を追加して、EnsureHttps メソッドを登録します。

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

3. 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;
       }
   }
   

4. [ ファイル>すべて保存 (Ctrl + Shift + S) を選択してプロジェクトを保存します。

5. F5 キーを押して、プロジェクトをビルドして実行します。

6. アプリの [アドレス] バーに、 http://bing.comなどの HTTP URL を入力し、[ 移動 ] ボタンをクリックします。

   HTTP サイトへのナビゲーションがブロックされており、フィードバックを提供するためのダイアログがまだ追加されていないため、何も起こりません。

7. https://bing.comなどの HTTPS URL を入力し、[Go] ボタンをクリックします。

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

8. アプリを閉じます。

手順 6 - スクリプト

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

• グローバル オブジェクトの作成後に、挿入された JavaScript を実行します。

• 挿入された JavaScript を実行してから、HTML ドキュメントに含まれている他のスクリプトを実行します。

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

1. 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;
       }
   }
   

2. [ ファイル>すべて保存 (Ctrl + Shift + S) を選択してプロジェクトを保存します。

3. F5 キーを押して、プロジェクトをビルドして実行します。

4. アプリのアドレス バーに、 http://www.bing.comなどの HTTPS 以外の URL を入力し、[ 移動 ] ボタンをクリックします。

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

   

5. アプリを閉じます。

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

WinUI 3 WebView2 の特別な考慮事項

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

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 では、webView2 XAML オブジェクトに DefaultBackgroundColor 設定が存在します。 例:

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

Transparency

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

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

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

関連項目

• WebView2 API リファレンス
• Microsoft Edge WebView2 の概要 - 機能の概要。
• ユーザー データ フォルダーを管理する
• WebView2 のサンプル コード - WebView2Samples リポジトリのガイド。
• WebView2 アプリの開発のベスト プラクティス開発のベスト プラクティス

developer.microsoft.com:

• Microsoft Edge WebView2 - developer.microsoft.com での WebView2 機能の初期概要。

GitHub:

• WinUI3 での WebView2 の概要
• 仕様: WebView2 Xaml コントロール - WinUI 3.0 バージョンの WebView2 コントロール。
• microsoft-ui-xaml リポジトリ > 問題 - WinUI 固有の機能要求またはバグを入力します。