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

  • Artikel

Wichtig

In diesem Thema werden Typen aus dem GitHub-Repository CommunityToolkit/Microsoft.Toolkit.Win32 verwendet oder erwähnt. Wichtige Informationen zur Unterstützung von XAML Islands finden Sie in diesem Repository im Hinweis zu 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.

Hinweis

Wenn Sie Feedback zu XAML Islands haben, erstellen Sie ein neues Thema im Microsoft.Toolkit.Win32-Repository, und geben Sie dort Ihre Kommentare ab.

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

Hinweis

Die Verwendung von XAML Islands zum Hosten von WinRT-XAML-Steuerelementen in WPF- und Windows Forms-Apps wird aktuell nur in Apps für die Zielplattform .NET Core 3.x unterstützt. XAML Islands werden in Apps für die Zielplattform .NET oder in Apps für eine beliebige Version von .NET Frameworks noch nicht unterstützt.

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.

Control Unterstützte Mindestversion des Betriebssystems Beschreibung
InkCanvas
InkToolbar		 Windows 10, Version 1903 Stellen Sie eine Oberfläche und zugehörige Symbolleisten für die Windows Ink-basierte Benutzerinteraktion in Ihrer Windows Forms- oder WPF-Desktop Anwendung bereit.
MediaPlayerElement Windows 10, Version 1903 Bettet eine Ansicht ein, die Medieninhalte wie etwa Videoclips in Ihrer Windows Forms- oder WPF-Desktop-Anwendung streamt und rendert.
MapControl Windows 10, Version 1903 Ermöglicht Ihnen das Anzeigen einer symbolischen oder fotorealistischen Karte in Ihrer Windows Forms- oder WPF-Desktop-Anwendung.

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.

Control Unterstützte Mindestversion des Betriebssystems Beschreibung
WindowsXamlHost Windows 10, Version 1903 Kann ein beliebiges WinRT-XAML-Steuerelement hosten, das von Windows.UI.Xaml.UIElement abgeleitet ist, einschließlich der vom Windows SDK bereitgestellten WinRT-XAML-Originalsteuerelemente sowie benutzerdefinierter Steuerelemente.

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.

Steuerelementtyp NuGet-Paket Verwandte Artikel
Umschließende Steuerelemente Version 6.0.0 oder höher dieser Pakete: Verwenden von XAML Islands zum Hosten eines UWP-XAML-Steuerelements in einer C#-WPF-App
Hoststeuerelement Version 6.0.0 oder höher dieser Pakete: Verwenden von XAML Islands zum Hosten eines UWP-XAML-Steuerelements in einer C#-WPF-App
Hosten eines benutzerdefinierten WinRT-XAML-Steuerelements in einer WPF-App

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.

Control Unterstützte Mindestversion des Betriebssystems Beschreibung
WebView Windows 10, Version 1803 Verwendet die Microsoft Edge-Renderingengine zum Anzeigen von Webinhalten.
WebViewCompatible Windows 7 Bietet eine Version von WebView, die mit mehr Betriebssystemversionen kompatibel ist. Dieses Steuerelement verwendet die Microsoft Edge-Renderingengine, um Webinhalte unter Windows 10, Version 1803 und höher, und die Internet Explorer-Renderingengine, um Webinhalte in früheren Windows 10-Versionen sowie Windows 8.x und Windows 7 anzuzeigen.

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

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.

Hinweis

Die umschließenden Steuerelemente und Hoststeuerelemente im Windows Community Toolkit verwenden intern die WinRT-XAML-Hosting-API und implementieren das gesamte Verhalten, einschließlich Tastaturnavigation und Layoutänderungen, um das Sie sich andernfalls, bei direkter Verwendung der WinRT-XAML-Hosting-API, selbst kümmern müssten. Für WPF- und Windows Forms-Anwendungen empfehlen wir dringend, diese Steuerelemente zu nutzen, statt die WinRT-XAML-Hosting-API direkt zu verwenden, da sie Ihnen durch Abstraktion viele der Implementierungsdetails ersparen, die mit der Verwendung der API einhergehen.

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.

Host control Architecture

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.