デスクトップ アプリで UWP XAML コントロールをホストする (UWP XAML Islands)

Windows 10 バージョン 1903 以降では、UWP XAML Islands という機能を使用して、UWP 以外のデスクトップ アプリケーションで UWP XAML コントロールをホストできます。 この機能を使用すると、既存のWPF、Windows フォーム、C++ デスクトップ (Win32) アプリケーションの外観、操作性、機能を、UWP XAML コントロールでのみ使用できるWindows UI 機能を使用して強化できます。 つまり、既存のWPF、Windows フォーム、C++ デスクトップ アプリケーションで、Windows Ink などの UWP 機能と、Fluent Design System をサポートするコントロールを使用できます。

Windows.UI.Xaml.UIElement から派生する任意の UWP XAML コントロールをホストできます。

• Windows SDK または WinUI for UWP ライブラリによって提供されるほとんどのファースト パーティの UWP XAML コントロール (exceptions を参照)。
• 任意のカスタム UWP XAML コントロール (たとえば、連携する複数の UWP XAML コントロールで構成されるユーザー コントロール)。 アプリケーションと共にコンパイルできるように、カスタム コントロールのソース コードを用意する必要があります。

基本的に、UWP XAML Islands は 、UWP XAML ホスティング API を使用して作成されます。 この API は、Windows 10 バージョン 1903 SDK で導入されたいくつかのWindows ランタイム クラスと COM インターフェイスで構成されています。 また、Windows Community Toolkit では、UWP XAML ホスティング API を内部的に使用し、WPFアプリとWindows フォーム アプリに便利な開発エクスペリエンスを提供する XAML Island .NET コントロールのセットも提供します。

UWP XAML Islands の使用方法は、アプリケーションの種類と、ホストする UWP XAML コントロールの種類によって異なります。

Requirements

UWP XAML Islands には、次の実行時要件があります。

• Windows 10バージョン 1903 以降のリリース。
• 展開用に MSIX パッケージにアプリケーションをパッケージ化しない場合は、コンピューターに Visual C++ ランタイムがインストールされている必要があります。

WPFおよびWindows フォームアプリケーション

WPFアプリケーションとWindows フォーム アプリケーションでは、Windows Community Toolkit で使用できる XAML Island .NET コントロールを使用することをお勧めします。 これらのコントロールは、対応する UWP XAML コントロールのプロパティ、メソッド、およびイベントを模倣 (またはアクセスを提供) するオブジェクト モデルを提供します。 また、キーボード ナビゲーションやレイアウトの変更などの動作も処理されます。

WPFアプリケーションとWindows フォームアプリケーションには、ラップされたコントロールとホスト コントロールの2つのXAML Islandコントロールセットがあります。

ラッピングされたコントロール

WPFアプリケーションとWindows フォーム アプリケーションでは、特定の UWP XAML コントロールのインターフェイスと機能をラップする XAML Island コントロールの選択を使用できます。 これらのコントロールは、WPFまたはWindows フォーム projectのデザイン surfaceに直接追加し、デザイナーの他のWPFやWindows フォーム コントロールと同様に使用できます。

Windows Community Toolkit では、次のラップされた UWP XAML コントロールを現在使用できます。

ラップされた UWP XAML コントロールの使用方法を示すチュートリアルについては、「 XAML Islands を使用して C# WPF アプリで UWP XAML コントロールをホストするを参照してください。

ホスト コントロール

使用可能なラップされたコントロール以外のカスタム コントロールやその他のシナリオでは、WPFアプリケーションとWindows フォーム アプリケーションでは、Windows Community Toolkit で使用できる WindowsXamlHost コントロールを使用することもできます。

WindowsXamlHost コントロールの使用方法を示すチュートリアルでは、 「 XAML Islands を使用して、C# WPF アプリで UWP XAML コントロールをホストします および XAML Islands を使用してWPF アプリでカスタム UWP XAML コントロールをホストする。

XAML Island .NET コントロールを使用するようにprojectを構成する

XAML Island .NET コントロールには、Windows 10バージョン 1903 以降のバージョンが必要です。 これらのコントロールを使用するには、次に示す NuGet パッケージのいずれかをインストールします。 これらのパッケージには、XAML Island のラップされたコントロールとホスト コントロールを使用するために必要なすべてのものが用意され、必要な他の関連する NuGet パッケージも含まれています。

次の詳細に注意してください。

• ホスト コントロール パッケージは、ラップされたコントロール パッケージにも含まれています。 ラップされたコントロール パッケージをインストールすると、両方のコントロール セットを使用できます。

• カスタム UWP XAML コントロールをホストしている場合は、カスタム コントロールを参照するための追加の手順も実行する必要があります。 詳細については、「 XAML Islands を使用してWPF アプリでカスタム UWP XAML コントロールをホストするを参照してください。

Web ビュー コントロール

Windows Community Toolkit には、WPFおよびWindows フォーム アプリケーションで Web コンテンツをホストするための次の.NET コントロールも用意されています。 これらのコントロールは、XAML Island コントロールと同様のデスクトップ アプリモダン化シナリオでよく使用され、XAML Island コントロールと同じMicrosoft.Toolkit.Win32 リポジトリに保持されます。

これらのコントロールを使用するには、次のいずれかの 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 以降) によって提供される UWP XAML ホスティング API を使用する必要があります。

UWP XAML ホスティング API は、C++ デスクトップ アプリケーションが Windows から派生した任意の UWP XAML コントロールをホストするために使用できる、いくつかのWindows ランタイム クラスと COM インターフェイスで構成されます。Ui。Xaml.UIElement。 関連付けられたウィンドウ ハンドル (HWND) を持つアプリケーション内の任意の UI 要素で UWP XAML コントロールをホストできます。 この API の詳細については、次の記事を参照してください。

• C++ デスクトップ アプリでの UWP XAML ホスティング API の使用
• C++ デスクトップ アプリで標準の UWP XAML コントロールをホストする
• C++ デスクトップ アプリでカスタム UWP XAML コントロールをホストする

UWP XAML Islands のアーキテクチャ

ここでは、UWP XAML ホスティング API の上に、さまざまな種類の XAML アイランド コントロールがどのようにアーキテクチャ的に編成されているかを簡単に説明します。

この図の下部に表示されている API は、Windows SDK に付属しています。 ラップされたコントロールとホスト コントロールは、Windows Community Toolkit の NuGet パッケージを介して使用できます。

制限事項と回避策

次のセクションでは、UWP XAML Islands を使用するデスクトップ アプリの特定の UWP 開発シナリオの制限事項と回避策について説明します。

回避策を使用した場合にのみサポートされる

✔️ XAML アイランドでの WinUI for UWP ライブラリ からのコントロールのホストは、UWP XAML Islands の現在のリリースで条件付きでサポートされています。 デスクトップ アプリで MSIX パッケージを使用して展開している場合は、Microsoft.UI.Xaml NuGet パッケージのプレリリースまたはリリース バージョンからの WinUI コントロールをホスティングできます。 お使いのデスクトップ アプリが MSIX を使用してパッケージ化されていない場合は、プレリリース バージョンの Microsoft.UI.Xaml NuGet パッケージをインストールしているか、Dynamic Dependencies API を使用している場合にのみ、WinUI コントロールをホスティングできます。

✔️ XAML アイランド内の XAML コンテンツのツリーのルート要素をaccessし、それがホストされているコンテキストに関する関連情報を取得するには、CoreWindow、ApplicationView、および Window クラスを使用しないでください。 代わりに、XamlRoot クラスを使用します。 詳細については、こちらのセクションをご覧ください。

✔️ WPFから Share コントラクトをサポートするには、 Windows フォーム、または C++ デスクトップ (Win32) アプリでは、アプリで IDataTransferManagerInterop インターフェイスを使用してDataTransferManager オブジェクトを取得し、特定のウィンドウの共有操作を開始する必要があります。 WPF アプリでこのインターフェイスを使用する方法を示すサンプルについては、ShareSource サンプルを参照してください。

✔️ UWP XAML Islands でホストされているコントロールで x:Bind を使用することはサポートされていません。 .NET Standard ライブラリでデータ モデルを宣言する必要があります。

サポートされていません

🚫 .NET Framework を対象とする WPF および Windows フォーム アプリでの UWP XAML Islands の使用。 UWP XAML Islands は、.NET Core 3.x を対象とするアプリでのみサポートされます。

🚫 UWP XAML Islands の UWP XAML コンテンツは、実行時に Windows のテーマを濃色から明色に、またはその逆に変更しても応答しません。 コンテンツは実行時にハイ コントラストの変更に対応します。

🚫 Windows.UI.Xaml.WebView コントロールの追加。 WPFアプリと WinForms アプリについては、これらの代替手段を参照してください。

🚫 MediaPlayer コントロールと MediaPlayerElement ホスト コントロールは、全画面表示モードではサポートされていません。

🚫 手書きビューでのテキスト入力。 この機能について詳しくは、この記事をご覧ください。

🚫 @Places および @People コンテンツ リンクを使用するテキスト コントロール。 この機能について詳しくは、この記事をご覧ください。

🚫 UWP XAML Islands では、テキスト入力を受け入れるコントロールを含む ContentDialog のホストはサポートされていません。 TextBox、RichEditBox、または AutoSuggestBox など。 これを行うと、入力コントロールはキーが押されても適切に応答しません。 XAML Island を使用して同様の機能を実現するには、入力コントロールを含む Popup をホストすることをお勧めします。

🚫 UWP XAML Islands では、現在、ホストされている Windows.UI.Xaml.Controls.Image コントロールや Windows.UI.Xaml.Media.Imaging.SvgImageSource オブジェクトを使用してSVGファイルを表示することはサポートされていません。 回避策として、表示したい画像ファイルを、JPG や PNG などのラスターベース形式に変換してください。

XAML Islands のウィンドウ ホスト コンテキスト

デスクトップ アプリで UWP XAML Islands をホストする場合、同じスレッドで同時に複数の XAML コンテンツ ツリーを実行できます。 XAML アイランド内の XAML コンテンツのツリーのルート要素をaccessし、それがホストされているコンテキストに関する関連情報を取得するには、XamlRoot クラスを使用します。 CoreWindow、ApplicationView、および Window クラスは、UWP XAML Islands の正しい情報を提供しません。 CoreWindow オブジェクトおよび Window オブジェクトはスレッドに存在し、アプリからアクセスできますが、意味のある境界と表示は返されません (常に非表示で、サイズは 1x1 です)。 詳細については、ウィンドウホストをご覧ください。

たとえば、XAML アイランドでホストされている UWP XAML コントロールを含むウィンドウの外接する四角形を取得するには、コントロールの XamlRoot.Size プロパティを使用します。 XAML Island でホストできるすべての UWP XAML コントロールは、Windows から派生するためです。Ui。Xaml.UIElement、コントロールの XamlRoot プロパティを使用して、XamlRoot オブジェクトにアクセスできます。

Size windowSize = myUWPControl.XamlRoot.Size;

境界を示す四角形を取得するために CoreWindows.Bounds プロパティを使用しないでください。

// This will return incorrect information for a UWP XAML control that is hosted in a XAML Island.
Rect windowSize = CoreWindow.GetForCurrentThread().Bounds;

UWP XAML Islands と推奨される XamlRoot 置換のコンテキストで回避する必要がある、ウィンドウ関連の一般的な API の表については、 このセクションの表を参照してください。

WPF アプリでこのインターフェイスを使用する方法を示すサンプルについては、ShareSource サンプルを参照してください。

その他のリソース

UWP XAML Islands の使用に関する背景情報とチュートリアルの詳細については、次の記事とリソースを参照してください。

• UWP XAML Islands のコード サンプル: このリポジトリには、UWP XAML Islands の使用方法を示すWindows フォーム、WPF、C++ デスクトップ (Win32) のサンプルが含まれています。
• UWP XAML Islands v1 - 更新プログラムとロードマップ: このブログ記事では、UWP XAML Islands に関する多くの一般的な質問について説明し、詳細な開発ロードマップを提供します。