デスクトップ アプリで WinRT XAML コントロールをホストする (XAML Islands)
重要
このトピックでは、CommunityToolkit/Microsoft.Toolkit.Win32 GitHub リポジトリの型について使用または言及します。 XAML Islands のサポートに関する重要な情報については、そのリポジトリの XAML Islands に関する通知を参照してください。
Windows 10 バージョン 1903 以降では、"XAML Islands" という機能を使用して、UWP 以外のデスクトップ アプリケーションで WinRT XAML コントロールをホストできるようになりました。 この機能を使用すると、既存の WPF、Windows フォーム、および C++ デスクトップ (Win32) アプリケーションの外観、操作性、および機能を、WinRT XAML コントロールでのみ使用できる最新の Windows UI 機能を使用して強化することができます。 つまり、既存の WPF、Windows フォーム、C++ デスクトップ アプリケーションで Fluent Design System をサポートする Windows Ink やコントロールなどの UWP 機能を使用できます。
次のような Windows.UI.Xaml.UIElement から派生した任意の WinRT XAML コントロールをホストできます。
- Windows SDK または WinUI 2 ライブラリで提供される任意のファーストパーティ WinRT XAML コントロール (例外に関するセクションを参照)。
- 任意のカスタム WinRT XAML コントロール (たとえば、連携して動作する複数の WinRT XAML コントロールで構成されるユーザー コントロール)。 アプリケーションと共にコンパイルできるように、カスタム コントロールのソース コードを用意する必要があります。
基本的に、XAML Islands は "WinRT XAML ホスティング API" を使用して作成されています。 この API は、Windows 10 バージョン 1903 SDK で導入されたいくつかの Windows ランタイム クラスと COM インターフェイスで構成されています。 また、Windows Community Toolkit には、WinRT XAML ホスティング API を内部的に使用する一連の XAML Island .NET コントロールも用意されており、WPF と Windows フォーム アプリの開発エクスペリエンスがより便利になります。
XAML Islands の使用方法は、アプリケーションの種類と、ホストする WinRT XAML コントロールの種類によって異なります。
注意
XAML Islands に関するフィードバックがある場合は、Microsoft.Toolkit.Win32 リポジトリに新しい問題を作成し、そこにコメントを残してください。
要件
XAML Islands には、次のような実行時の要件があります。
- Windows 10 バージョン 1903 以降のリリース。
- 展開用に MSIX パッケージにアプリケーションをパッケージ化しない場合は、コンピューターに Visual C++ ランタイムがインストールされている必要があります。
WPF と Windows フォーム アプリケーション
注意
WPF および Windows フォーム アプリでの XAML Islands を使用した WinRT XAML コントロールのホストは、現在、.NET Core 3.x をターゲットとするアプリでのみサポートされています。 XAML Islands は、.NET をターゲットとするアプリ、または .NET Framework のすべてのバージョンのアプリでは、まだサポートされていません。
WPF および Windows フォーム アプリケーションでは、Windows Community Toolkit で利用できる XAML Island .NET コントロールを使用することをお勧めします。 これらのコントロールには、対応する WinRT XAML コントロールのプロパティ、メソッド、およびイベントを模倣する (またはそれにアクセスできるようになる) オブジェクト モデルが用意されています。 また、キーボード ナビゲーションやレイアウトの変更などの動作も処理されます。
WPF および Windows フォーム アプリケーション用の XAML Island コントロールには、"ラップされたコントロール" と"ホスト コントロール" という 2 つのセットがあります。
ラップされたコントロール
WPF および Windows フォーム アプリケーションには、特定の WinRT XAML コントロールのインターフェイスと機能をラップする XAML Island コントロールの一部を使用できます。 これらのコントロールを WPF または Windows フォーム プロジェクトのデザイン サーフェイスに直接追加し、デザイナーの他の WPF や Windows フォーム コントロールと同様に使用できます。
現在、次のラップされた WinRT XAML コントロールを Windows Community Toolkit で使用できます。
| コントロール | サポートされる最小 OS | 説明 |
|---|---|---|
| InkCanvas InkToolbar |
Windows 10 Version 1903 | Windows フォームまたは WPF デスクトップ アプリケーションで Windows Ink ベースのユーザーとの対話に使用する、画面と関連するツールバーを提供します。 |
| MediaPlayerElement | Windows 10 Version 1903 | Windows フォームまたは WPF デスクトップ アプリケーションでビデオなどのメディア コンテンツをストリーミングおよびレンダリングするビューを埋め込みます。 |
| MapControl | Windows 10 Version 1903 | Windows フォームまたは WPF デスクトップ アプリケーションで、シンボリックまたはフォト マップを表示できるようにします。 |
ラップされた WinRT XAML コントロールの使用方法を示すチュートリアルについては、「XAML Islands を使用して、C# WPF アプリで UWP XAML コントロールをホストする」を参照してください。
ホスト コントロール
使用できるラップされたコントロールに含まれていないカスタム コントロールやその他のシナリオでは、Windows Community Toolkit で使用できる WindowsXamlHost コントロールを WPF および Windows フォーム アプリケーションに使用することもできます。
| コントロール | サポートされる最小 OS | 説明 |
|---|---|---|
| WindowsXamlHost | Windows 10 Version 1903 | Windows.UI.Xaml.UIElement から派生した WinRT XAML コントロールをホストできます。たとえば、Windows SDK で提供されるファーストパーティ WinRT XAML コントロールや、カスタム コントロールなどです。 |
WindowsXamlHost コントロールの使用方法を示すチュートリアルについては、「XAML Islands を使用して、C# WPF アプリで UWP XAML コントロールをホストする」と「XAML Islands を使用して WPF アプリでカスタム WinRT XAML コントロールをホストする」を参照してください。
XAML Island .NET コントロールを使用するようにプロジェクトを構成する
XAML Island .NET コントロールには、Windows 10 バージョン 1903 以降が必要です。 これらのコントロールを使用するには、次に示す NuGet パッケージのいずれかをインストールします。 これらのパッケージには、XAML Island のラップされたコントロールとホスト コントロールを使用するために必要なすべてのものが用意され、必要な他の関連する NuGet パッケージも含まれています。
| コントロールの種類 | NuGet パッケージ | 関連記事 |
|---|---|---|
| ラップされたコントロール | バージョン 6.0.0 以降のパッケージ:
|
XAML Islands を使用して、C# WPF アプリで UWP XAML コントロールをホストする |
| ホスト コントロール | バージョン 6.0.0 以降のパッケージ:
|
XAML Islands を使用して、C# WPF アプリで UWP XAML コントロールをホストする WPF アプリでカスタム WinRT XAML コントロールをホストする |
次の詳細に注意してください。
ホスト コントロール パッケージは、ラップされたコントロール パッケージにも含まれています。 ラップされたコントロール パッケージをインストールすると、両方のコントロール セットを使用できます。
また、カスタム WinRT XAML コントロールをホストするには、カスタム コントロールを参照するためにいくつかの追加の手順を実行する必要もあります。 詳細については、「XAML Islands を使用して WPF アプリでカスタム WinRT XAML コントロールをホストする」を参照してください。
Web ビュー コントロール
Windows Community Toolkit には、WPF および Windows フォーム アプリケーションで Web コンテンツをホストするための次の .NET コントロールも用意されています。 これらのコントロールは、XAML Island コントロールと同様のデスクトップ アプリの最新化シナリオでよく使用され、XAML Island コントロールと同じ Microsoft.Toolkit.Win32 リポジトリで保守されています。
| コントロール | サポートされる最小 OS | 説明 |
|---|---|---|
| WebView | Windows 10 Version 1803 | Microsoft Edge レンダリング エンジンを使用して、Web コンテンツを表示します。 |
| WebViewCompatible | Windows 7 | より多くの OS バージョンと互換性がある WebView のバージョンが用意されています。 このコントロールには、Windows 10 バージョン 1803 以降で Web コンテンツを表示するために Microsoft Edge レンダリング エンジンが使用され、Windows 10、Windows 8.x、および Windows 7 の以前のバージョンで Web コンテンツを表示するために Internet Explorer レンダリング エンジンが使用されます。 |
これらのコントロールを使用するには、次のいずれかの NuGet パッケージをインストールします。
- WPF: Microsoft.Toolkit.Wpf.UI.Controls.WebView
- Windows フォーム: Microsoft.Toolkit.Forms.UI.Controls.WebView
C++ デスクトップ (Win32) アプリケーション
XAML Island .NET コントロールは、C++ デスクトップ アプリケーションではサポートされていません。 これらのアプリケーションでは、Windows 10 SDK (バージョン 1903 以降) で提供される "WinRT XAML ホスティング API" を代わりに使用する必要があります。
WinRT XAML ホスティング API は、いくつかの Windows ランタイム クラスと COM インターフェイスで構成されています。C++ デスクトップ アプリケーションではこれらを使用して Windows.UI.Xaml.UIElement から派生した任意の WinRT XAML コントロールをホストできます。 関連付けられたウィンドウ ハンドル (HWND) を持つアプリケーションの任意の UI 要素で WinRT XAML コントロールをホストできます。 この API の詳細については、次の記事を参照してください。
- C++ デスクトップ アプリでの WinRT XAML ホスティング API の使用
- C++ デスクトップ アプリで標準 WinRT XAML コントロールをホストする
- C++ デスクトップ アプリでカスタム WinRT XAML コントロールをホストする
注意
Windows Community Toolkit のラップされたコントロールとホスト コントロールには、WinRT XAML ホスティング API が内部的に使用され、キーボード ナビゲーションやレイアウトの変更など、WinRT XAML ホスティング API を直接使用した場合には独自に処理する必要があるすべての動作が実装されています。 WPF および Windows フォーム アプリケーションの場合、WinRT XAML ホスティング API ではなく、これらのコントロールを使用することを強くお勧めします。これは、API に関する実装の詳細の多くを抽象化できるためです。
XAML Islands のアーキテクチャ
ここでは、WinRT XAML ホスティング API の上に、どのような種類の XAML Islands コントロールが構造的に編成されているかを簡単に説明します。
この図の下部に表示されている API は、Windows SDK に付属しています。 ラップされたコントロールとホスト コントロールは、Windows Community Toolkit の NuGet パッケージを介して使用できます。
制限事項と回避策
以下のセクションでは、XAML Islands を使用するデスクトップ アプリでの特定の UWP 開発シナリオにおける制限事項と回避策について説明します。
回避策を使用した場合にのみサポートされる
✔️ XAML Island の WinUI 2.x ライブラリのコントロールをホストすることは、XAML Island の現在のリリースで条件付きでサポートされています。 デスクトップ アプリで MSIX パッケージを使用して展開している場合は、Microsoft.UI.Xaml NuGet パッケージのプレリリースまたはリリース バージョンからの WinUI コントロールをホスティングできます。 お使いのデスクトップ アプリが MSIX を使用してパッケージ化されていない場合は、プレリリース バージョンの Microsoft.UI.Xaml NuGet パッケージをインストールしているか、Dynamic Dependencies API を使用している場合にのみ、WinUI コントロールをホスティングできます。 WinUI 3.0 ライブラリのコントロールのホストは、今後のリリースでサポートされる予定です。
✔️ XAML Island で XAML コンテンツのツリーのルート要素にアクセスし、それがホストされているコンテキストに関する関連情報を取得するために、CoreWindow、ApplicationView、Window クラスを使用しないでください。 代わりに、XamlRoot クラスを使用します。 詳細については、こちらのセクションをご覧ください。
✔️ WPF、Windows フォーム、または C++ デスクトップ (Win32) アプリからの共有コントラクトをサポートするには、アプリで IDataTransferManagerInterop インターフェイスを使用して、特定のウィンドウの共有操作を開始するために DataTransferManager オブジェクトを取得する必要があります。 このインターフェイスを WPF アプリで使用する方法を示すサンプルについては、ShareSource サンプルを参照してください。
✔️ XAML Islands でホストされたコントロールと共に x:Bind を使用することは、サポートされていません。 .NET Standard ライブラリ内でデータ モデルを宣言する必要があります。
サポートされていません
🚫 .NET Framework を対象とする WPF および Windows フォーム アプリで XAML Islands を使用すること。 XAML Islands は、.NET Core 3.x を対象とするアプリでのみサポートされています。
🚫 XAML Islands の UWP XAML コンテンツは、実行時のダークからライト、またはその逆の Windows テーマの変更には対応していません。 コンテンツは実行時にハイ コントラストの変更に対応します。
🚫 Windows.UI.Xaml.WebView コントロールの追加。 WPF アプリと WinForms アプリについては、こちらの代替手段を参照してください。
🚫 MediaPlayer コントロールと MediaPlayerElement ホスト コントロールは、全画面表示モードではサポートされていません。
🚫 手書きビューでのテキスト入力。 この機能について詳しくは、この記事をご覧ください。
🚫 @Places および @People コンテンツ リンクを使用するテキスト コントロール。 この機能について詳しくは、この記事をご覧ください。
🚫 XAML Islands では、TextBox、RichEditBox、AutoSuggestBox などのテキスト入力を受け入れるコントロールを含む ContentDialog のホストはサポートされていません。 これを行うと、入力コントロールはキーが押されても適切に応答しません。 XAML Island を使用して同様の機能を実現するには、入力コントロールを含む Popup をホストすることをお勧めします。
🚫 現在、XAML Island では、ホストされた Windows.UI.Xaml.Controls.Image コントロール内、または Windows.UI.Xaml.Media.Imaging.SvgImageSource オブジェクトを使用した SVG ファイルの表示はサポートされていません。 回避策として、表示したい画像ファイルを、JPG や PNG などのラスターベース形式に変換してください。
XAML Islands のウィンドウ ホスト コンテキスト
デスクトップ アプリで XAML Islands をホストすると、XAML コンテンツの複数のツリーを同じスレッド上で同時に実行できます。 XAML Island で XAML コンテンツのツリーのルート要素にアクセスし、それがホストされているコンテキストに関する関連情報を取得するには、XamlRoot クラスを使用します。 CoreWindow、ApplicationView、および Window クラスでは、XAML Islands に関する正しい情報が提供されません。 CoreWindow オブジェクトおよび Window オブジェクトはスレッドに存在し、アプリからアクセスできますが、意味のある境界と表示は返されません (常に非表示で、サイズは 1x1 です)。 詳細については、ウィンドウ化ホストに関するページを参照してください。
たとえば、XAML Island でホストされている WinRT XAML コントロールが含まれるウィンドウの境界を示す四角形を取得するには、コントロールの XamlRoot.Size プロパティを使用します。 XAML Island でホストできるすべての WinRT XAML コントロールは Windows.UI.Xaml.UIElement から派生するため、コントロールの XamlRoot プロパティを使用して XamlRoot オブジェクトにアクセスできます。
Size windowSize = myUWPControl.XamlRoot.Size;
境界を示す四角形を取得するために CoreWindows.Bounds プロパティを使用しないでください。
// This will return incorrect information for a WinRT XAML control that is hosted in a XAML Island.
Rect windowSize = CoreWindow.GetForCurrentThread().Bounds;
XAML Islands のコンテキストで避ける必要がある一般的なウィンドウ関連 API の表と、推奨される XamlRoot の置換については、こちらのセクションの表を参照してください。
このインターフェイスを WPF アプリで使用する方法を示すサンプルについては、ShareSource サンプルを参照してください。
その他のリソース
XAML Islands の使用に関する背景情報とチュートリアルの詳細については、次の記事とリソースを参照してください。
- WPF アプリの最新化のチュートリアル: このチュートリアルでは、Windows Community Toolkit でラップされたコントロールとホスト コントロールを使用して、WinRT XAML コントロールを既存の WPF 基幹業務アプリケーションに追加する手順が説明されています。 このチュートリアルには、WPF アプリケーションの完全なコードと、プロセスの各手順の詳細な手順も含まれています。
- XAML Islands コード サンプル: このリポジトリには、XAML Islands の使用方法を示す Windows フォーム、WPF、C++ デスクトップ (Win32) のサンプルが含まれています。
- XAML Islands v1 - 更新とロードマップ: このブログ投稿では、XAML Islands についてよく寄せられる質問が説明され、詳細な開発ロードマップが掲載されています。
Windows developer