Hosten von WinRT-XAML-Steuerelementen in Desktop-Apps (XAML Islands)

Ab Windows 10, Version 1903, können Sie mithilfe eines Features namens XAML Islands WinRT-XAML-Steuerelemente auch in anderen als UWP-Desktop-Anwendungen hosten. Mit diesem Feature können Sie Aussehen, Handhabung und Funktionalität Ihrer vorhandenen WPF-, Windows Forms- und C++-Desktopanwendungen (Win32) mit den aktuellen Features der Windows-Benutzeroberfläche verbessern, die nur in Form von WinRT-XAML-Steuerelementen verfügbar sind. Dies bedeutet, dass Sie UWP-Features, wie etwa Windows Ink, und Steuerelemente, die das Fluent Design-System unterstützen, in Ihren vorhandenen WPF-, Windows Forms- und C++-Desktopanwendungen nutzen können.

Sie können beliebige WinRT-XAML-Steuerelemente hosten, die von Windows.UI.Xaml.UIElement abgeleitet sind, darunter:

• Die meisten vom Originalhersteller stammenden WinRT-XAML-Steuerelemente, die im Windows SDK oder der WinUI 2-Bibliothek bereitstehen (siehe Ausnahmen).
• Alle benutzerdefinierten WinRT-XAML-Steuerelemente (beispielsweise ein Benutzersteuerelement, das aus mehreren WinRT-XAML-Steuerelementen besteht, die zusammenarbeiten). Sie müssen über den Quellcode für das benutzerdefinierte Steuerelement verfügen, damit Sie es mit Ihrer Anwendung kompilieren können.

Grundsätzlich werden XAML Islands mithilfe der WinRT-XAML-Hosting-API erstellt. Diese API besteht aus mehreren Windows-Runtime Klassen und COM-Schnittstellen, die im SDK für Windows 10, Version 1903, eingeführt wurden. Wir stellen darüber hinaus eine Reihe von XAML Island-.NET-Steuerelementen im Windows Community Toolkit zur Verfügung, die die WinRT-XAML-Hosting-API intern verwenden und für WPF- und Windows Forms-Apps ein komfortableres Entwicklungserlebnis bieten.

Die Art, wie Sie XAML Islands verwenden, hängt von Ihrem Anwendungstyp und den Typen der WinRT-XAML-Steuerelemente ab, die Sie hosten möchten.

Anforderungen

XAML Islands hat folgende Runtimeanforderungen:

• Windows 10, Version 1903 oder höher.
• Wenn deine Anwendung für die Bereitstellung nicht in einem MSIX-Paket gepackt ist, muss auf dem Computer die Visual C++-Runtime installiert sein.

WPF- und Windows Forms-Anwendungen

Wir empfehlen, für WPF- und Windows Forms-Anwendungen die XAML Island-.NET-Steuerelemente zu verwenden, die im Windows Community Toolkit verfügbar sind. Diese Steuerelemente bieten ein Objektmodell, das die Eigenschaften, Methoden und Ereignisse der entsprechenden WinRT-XAML-Steuerelemente nachahmt (oder Zugriff auf sie bietet). Darüber hinaus verarbeiten sie Verhalten wie Tastaturnavigation und Layoutänderungen.

Es gibt zwei Sätze von XAML Island-Steuerelementen für WPF- und Windows Forms-Anwendungen: umschließende Steuerelemente und Hoststeuerelemente.

Umschließende Steuerelemente

WPF- und Windows Forms-Anwendungen können eine Reihe von XAML Island-Steuerelementen verwenden, die die Schnittstelle und die Funktionalität eines bestimmten WinRT-XAML-Steuerelements umschließen. Sie können diese Steuerelemente direkt der Entwurfsoberfläche Ihres WPF- oder Windows Forms-Projekts hinzufügen und sie dann wie jedes andere WPF- oder Windows Forms-Steuerelement im Designer verwenden.

Aktuell stehen die folgenden umschließenden WinRT-XAML-Steuerelemente im Windows Community Toolkit zur Verfügung.

Eine exemplarische Vorgehensweise, die die Verwendung der umschließenden WinRT-XAML-Steuerelemente veranschaulicht, finden Sie unter Verwenden von XAML Islands zum Hosten eines UWP-XAML-Steuerelements in einer C#-WPF-App.

Hoststeuerelemente

Für benutzerdefinierte Steuerelemente und andere Szenarien, die über die mit den verfügbaren umschließenden Steuerelementen gegebenen Möglichkeiten hinausgehen, kann in WPF- und Windows Forms-Anwendungen auch das WindowsXamlHost-Steuerelement eingesetzt werden, das im Windows Community Toolkit zur Verfügung steht.

Exemplarische Vorgehensweisen, in denen die Verwendung des WindowsXamlHost-Steuerelements veranschaulicht wird, finden Sie unter Verwenden von XAML Islands zum Hosten eines UWP-XAML-Steuerelements in einer C#-WPF-App und Hosten eines benutzerdefinierten WinRT-XAML-Steuerelements in einer WPF-App mithilfe von XAML Islands.

Konfigurieren des Projekts zum Verwenden der XAML Island-.NET-Steuerelemente

Für die XAML Island-.NET-Steuerelemente ist Windows 10, Version 1903, oder eine höhere Version erforderlich. Installieren Sie eins der unten aufgeführten NuGet-Pakete, um diese Steuerelemente zu verwenden. Diese Pakete bieten alles, was Sie benötigen, um die umschließenden XAML Island-Steuerelemente und die XAML Island-Hoststeuerelemente zu verwenden, und sie enthalten weitere verwandte NuGet-Pakete, die ebenfalls benötigt werden.

Bitte beachten Sie die folgenden Details:

• Die Pakete mit den umschließenden Steuerelementen enthalten außerdem die Pakete mit den Hoststeuerelementen. Sie können die Pakete mit den umschließenden Steuerelementen installieren, wenn Sie beide Steuerelementsätze verwenden möchten.

• Wenn Sie ein benutzerdefiniertes WinRT-XAML-Steuerelement hosten, müssen Sie außerdem einige weitere Schritte ausführen, um auf das benutzerdefinierte Steuerelement zu verweisen. Weitere Informationen finden Sie unter Hosten eines benutzerdefinierten WinRT-XAML-Steuerelements in einer WPF-App mithilfe von XAML Islands.

Webansicht-Steuerelemente

Das Windows Community Toolkit stellt außerdem die folgenden .NET-Steuerelemente für das Hosten von Webinhalten in WPF- und Windows Forms-Anwendungen zur Verfügung. Diese Steuerelemente werden häufig in ähnlichen Szenarien zur Modernisierung von Desktop-Apps verwendet wie die XAML Island-Steuerelemente. Zudem werden sie im gleichen Microsoft.Toolkit.Win32-Repository wie die XAML Island-Steuerelemente verwaltet.

Installieren Sie eins dieser NuGet-Pakete, um diese Steuerelemente zu verwenden:

• WPF: Microsoft.Toolkit.Wpf.UI.Controls.WebView
• Windows Forms: Microsoft.Toolkit.Forms.UI.Controls.WebView

C++-Desktopanwendungen (Win32)

Die XAML Island-.NET-Steuerelemente werden in C++-Desktopanwendungen nicht unterstützt. Diese Anwendungen müssen stattdessen die WinRT-XAML-Hosting-API verwenden, die vom Windows 10 SDK bereitgestellt wird (Version 1903 und höher).

Die WinRT-XAML-Hosting-API besteht aus verschiedenen Windows-Runtime-Klassen und COM-Schnittstellen, die von Ihrer C++-Desktopanwendungen zum Hosten beliebiger WinRT-XAML-Steuerelemente verwendet werden können, die von Windows.UI.Xaml.UIElement abgeleitet sind. WinRT-XAML-Steuerelemente lassen sich in jedem beliebigen Element der Benutzeroberfläche hosten, dem ein Fensterhandle (HWND) zugeordnet ist. Weitere Informationen zu dieser API findest du in den folgenden Artikeln.

• Verwenden der WinRT-XAML-Hosting-API in einer C++-Desktop-App
• Hosten eines WinRT-XAML-Standardsteuerelements in einer C++-Desktop-App
• Hosten eines benutzerdefinierten WinRT-XAML-Steuerelements in einer C++-Desktop-App

Architektur von XAML Islands

Hier geben wir einen kurzen Überblick zur architektonischen Gliederung der XAML Island-Steuerelemente auf dem Fundament der WinRT-XAML-Hosting-API.

Die am Diagrammende aufgeführten APIs sind im Lieferumfang des Windows SDK enthalten. Die umschließenden Steuerelemente und die Hoststeuerelemente stehen im Windows Community Toolkit in Form von NuGet-Paketen zur Verfügung.

Einschränkungen und Problemumgehungen

In den folgenden Abschnitten werden Einschränkungen und Problemumgehungen für bestimmte UWP-Entwicklungsszenarien bei Desktop-Apps mit XAML Islands erläutert.

Nur mit Problemumgehungen unterstützt

✔️ Das Hosting von Steuerelementen aus der WinUI 2-Bibliothek in einer XAML Islands-Instanz wird im aktuellen Release von XAML Islands bedingt unterstützt. Wenn Ihre Desktop-App ein MSIX-Paket für die Bereitstellung verwendet, können Sie WinUI-Steuerelemente aus einer Vorabversion oder Releaseversion des Microsoft.UI.Xaml-NuGet-Pakets hosten. Wenn Ihre Desktop-App nicht unter Verwendung von MSIX gepackt ist, können Sie WinUI-Steuerelemente nur dann hosten, wenn Sie eine Vorabversion des Microsoft.UI.Xaml-NuGet-Pakets installieren oder die API für dynamische Abhängigkeiten verwenden. Unterstützung für das Hosten von Steuerelementen aus der WinUI 3.0-Bibliothek wird in einem späteren Release geboten werden.

✔️ Um auf das Stammelement einer Struktur von XAML-Inhalten in einer XAML Islands-Instanz zuzugreifen und verwandte Informationen zum Kontext abzurufen, in dem dieser gehostet wird, sollten Sie nicht die Klassen CoreWindow, ApplicationView oder Window verwenden. Verwende stattdessen die XamlRoot-Klasse. Weitere Informationen finden Sie in diesem Abschnitt.

✔️ Um den Freigabe-Vertrag einer WPF-, Windows Forms- oder C++-Desktop-App (Win32) zu unterstützen, muss Ihre App über Schnittstelle IDataTransferManagerInterop das DataTransferManager-Objekt abrufen, um den Freigabevorgang für ein bestimmtes Fenster zu initiieren. Ein Beispiel, das veranschaulicht, wie diese Schnittstelle in einer WPF-App verwendet wird, findest du im ShareSource-Beispiel.

✔️ Die Verwendung von x:Bind mit gehosteten Steuerelementen in XAML Islands wird nicht unterstützt. Du musst das Datenmodell in einer .NET Standard-Bibliothek deklarieren.

Nicht unterstützt

 Verwenden von XAML Islands in WPF- und Windows Forms-Apps mit .NET Framework als Ziel. XAML Islands wird nur in Apps unterstützt, die auf .NET Core 3.x abzielen.

 UWP-XAML-Inhalt in XAML Islands reagiert nicht auf Windows-Designänderungen von dunkel zu hell oder umgekehrt zur Laufzeit. Der Inhalt reagiert jedoch zur Laufzeit auf Änderungen zu hohem Kontrast.

 Hinzufügen eines Windows.UI.Xaml.WebView-Steuerelements. Schauen Sie sich für WPF- und WinForms-Apps diese Alternativen an.

 Das Steuerelement MediaPlayer und das Hoststeuerelement MediaPlayerElement werden im Vollbildmodus nicht unterstützt.

 Texteingabe in der Handschriftansicht. Weitere Informationen zu diesem Feature findest du in diesem Artikel.

 Textsteuerelemente, die die Inhaltslinks @Places und @People verwenden. Weitere Informationen zu diesem Feature findest du in diesem Artikel.

 XAML-Inseln unterstützen nicht das Hosting eines ContentDialog-Elements, das ein Steuerelement enthält, das Texteingaben annimmt, z. B. ein TextBox-, RichEditBox- oder AutoSuggestBox-Element. Wenn Sie dies verwenden, reagiert das Eingabesteuerelement auf Tastenanschläge nicht ordnungsgemäß. Um eine ähnliche Funktionalität mit einer XAML-Insel zu erreichen, empfiehlt es sich, ein Popup-Element zu hosten, das das Eingabesteuerelement enthält.

 XAML Islands-Instanzen unterstützen derzeit nicht das Anzeigen von SVG-Dateien in einem gehosteten Windows.UI.Xaml.Controls.Image-Steuerelement oder unter Verwendung eines Windows.UI.Xaml.Media.Imaging.SvgImageSource-Objekts. Um dieses Problem zu umgehen, konvertieren Sie die Bilddateien, die Sie anzeigen möchten, in rasterbasierten Formaten wie JPG oder PNG.

Fensterhostkontext für XAML Islands

Wenn Sie XAML Islands in einer Desktop-App hosten, können Sie mehrere Strukturen mit XAML-Inhalten gleichzeitig im selben Thread ausführen. Um auf das Stammelement eine Struktur von XAML-Inhalten in einer XAML Island zuzugreifen und verwandte Informationen über den Kontext abzurufen, in dem dieser gehostet wird, verwenden Sie die Klasse XamlRoot. Die Klassen CoreWindow, ApplicationView und Window liefern nicht die richtigen Informationen für XAML Islands. CoreWindow- und Window-Objekte existieren zwar im Thread und sind für Ihre App zugänglich, aber sie geben keine sinnvollen Begrenzungen oder Sichtbarkeiten zurück (sie sind immer unsichtbar und haben eine Größe von 1x1). Weitere Informationen finden Sie unter Fensterhosts.

Um beispielsweise das Begrenzungsrechteck des Fensters abzurufen, das ein WinRT-XAML-Steuerelement enthält, das in einer XAML Island gehostet wird, verwenden Sie die Eigenschaft XamlRoot.Size des Steuerelements. Da jedes WinRT-XAML-Steuerelement, das in einer XAML Island gehostet werden kann, von Windows.UI.Xaml.UIElement abgeleitet wird, können Sie die XamlRoot-Eigenschaft des Steuerelements verwenden, um auf das XamlRoot-Objekt zuzugreifen.

Size windowSize = myUWPControl.XamlRoot.Size;

Verwenden Sie nicht die Eigenschaft CoreWindows.Bounds, um das Begrenzungsrechteck abzurufen.

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

Eine Tabelle mit allgemeinen fensterbezogenen APIs, die Sie im Kontext von XAML Islands vermeiden sollten, und die empfohlenen XamlRoot-Ersetzungen finden Sie in der Tabelle in diesem Abschnitt.

Ein Beispiel, das veranschaulicht, wie diese Schnittstelle in einer WPF-App verwendet wird, findest du im ShareSource-Beispiel.

Zusätzliche Ressourcen

Weitere Hintergrundinformationen und Tutorials zur Verwendung von XAML Islands finden Sie in den folgenden Artikeln und Ressourcen:

• Tutorial Modernisieren einer WPF-App: Dieses Tutorial enthält schrittweise Anleitungen zum Verwenden der umschließenden Steuerelemente und Hoststeuerelemente im Windows Community Toolkit zum Hinzufügen von WinRT-XAML-Steuerelementen zu einer vorhandenen WPF-Branchenanwendung. Dieses Tutorial enthält den vollständigen Code für die WPF-Anwendung sowie ausführliche Anweisungen zu den einzelnen Schritten in diesem Prozess.
• Codebeispiele für XAML-Inseln: Dieses Repository enthält Beispiele für Windows Forms, WPF und C++-Desktop (Win32), die die Verwendung von XAML-Inseln demonstrieren.
• XAML Islands v1 – Updates and Roadmap: In diesem Blogbeitrag werden viele häufig gestellte Fragen zu XAML Islands erläutert und eine ausführliche Entwicklungsroadmap zur Verfügung gestellt.