Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Von Bedeutung
In diesem Thema werden Typen aus dem Repository CommunityToolkit/Microsoft.Toolkit.Win32 GitHub verwendet oder erwähnt. Wichtige Informationen zur Unterstützung von UWP-XAML-Inseln finden Sie im XAML Islands Notice in diesem Repository.
Ab Windows 10 Version 1903 können Sie UWP-XAML-Steuerelemente in Nicht-UWP-Desktopanwendungen hosten, indem Sie ein Feature namens UWP-XAML-Inseln verwenden. Mit diesem Feature können Sie das Aussehen, Verhalten und die Funktionalität Ihrer vorhandenen WPF, Windows Forms und C++-Desktopanwendungen (Win32) mit Windows UI-Features verbessern, die nur über UWP-XAML-Steuerelemente verfügbar sind. Dies bedeutet, dass Sie UWP-Features wie Windows Ink und Steuerelemente verwenden können, die das Fluent Design System in Ihren vorhandenen WPF-, Windows Forms- und C++-Desktopanwendungen unterstützen.
Sie können jedes UWP-XAML-Steuerelement hosten, das von Windows.UI.Xaml.UIElement abgeleitet wird, einschließlich:
- Die meisten UWP-XAML-Steuerelemente von Drittanbietern, die vom Windows SDK oder der WinUI für UWP-Bibliothek bereitgestellt werden (siehe ausnahmen).
- Jedes benutzerdefinierte UWP-XAML-Steuerelement (z. B. ein Benutzersteuerelement, das aus mehreren UWP-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 UWP-XAML-Inseln mithilfe der UWP-XAML-Hosting-API erstellt. Diese API besteht aus mehreren Windows-Runtime Klassen und COM-Schnittstellen, die im Windows 10, Version 1903 SDK, eingeführt wurden. Darüber hinaus stellen wir eine Reihe von XAML Island-.NET-Steuerelementen im Windows Community Toolkit bereit, die die UWP-XAML-Hosting-API intern verwenden und eine komfortablere Entwicklungsumgebung für WPF- und Windows Forms-Apps bieten.
Die Verwendung von UWP-XAML-Inseln hängt vom Anwendungstyp und den Typen von UWP-XAML-Steuerelementen ab, die Sie hosten möchten.
Anforderungen
UWP-XAML-Inseln haben die folgenden Laufzeitanforderungen:
- Windows 10, Version 1903 oder einer höheren Version.
- 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 UWP-XAML-Inseln zum Hosten von UWP-XAML-Steuerelementen in WPF und Windows Forms Apps wird derzeit nur in Apps unterstützt, die auf .NET Core 3.x abzielen. UWP-XAML-Inseln werden in Apps, die auf .NET abzielen, oder in Apps, die eine beliebige Version des .NET Frameworks verwenden, noch nicht unterstützt.
Es wird empfohlen, dass WPF- und Windows Forms-Anwendungen die XAML Island-.NET Steuerelemente verwenden, die im Windows Community Toolkit verfügbar sind. Diese Steuerelemente stellen ein Objektmodell bereit, das die Eigenschaften, Methoden und Ereignisse der entsprechenden UWP-XAML-Steuerelemente nachahmt (oder zugriff darauf bietet). Darüber hinaus verarbeiten sie Verhalten wie Tastaturnavigation und Layoutänderungen.
Es gibt zwei Gruppen von XAML-Insel-Steuerelementen für WPF- und Windows Forms-Anwendungen: umhüllte Steuerelemente und Host-Steuerelemente.
Eingekapselte Steuerelemente
WPF- und Windows Forms-Anwendungen können eine Auswahl von XAML Island-Steuerelementen verwenden, die die Schnittstelle und Funktionalität eines bestimmten UWP-XAML-Steuerelements umschließen. Sie können diese Steuerelemente direkt zur Entwurfsoberfläche Ihrer WPF- oder Windows-Forms-Projekte hinzufügen und dann wie jedes andere WPF- oder Windows-Forms-Steuerelement im Designer verwenden.
Die folgenden umschlossenen UWP-XAML-Steuerelemente sind derzeit im Windows Community Toolkit verfügbar.
| Steuerung | Unterstützte Mindestversion des Betriebssystems | Description |
|---|---|---|
|
InkCanvas InkToolbar |
Windows 10, Version 1903 | Stellen Sie eine Oberfläche und zugehörige Werkzeuge für die Windows Ink-basierte Benutzerinteraktion auf Ihrer Windows Forms- oder WPF-Desktopanwendung bereit. |
| MediaPlayerElement | Windows 10, Version 1903 | Bettet eine Ansicht ein, die Medieninhalte wie Video in Ihrer Windows Forms oder WPF Desktopanwendung streamt und rendert. |
| MapControl | Windows 10, Version 1903 | Ermöglicht ihnen das Anzeigen einer symbolischen oder photorealistischen Karte in Ihrer Windows Forms oder WPF Desktopanwendung. |
Eine exemplarische Vorgehensweise zur Verwendung der umschlossenen UWP-XAML-Steuerelemente finden Sie unter Use XAML Islands to host a UWP XAML control in a C# WPF app.
Hoststeuerungen
Für benutzerdefinierte Steuerelemente und andere Szenarien, die über die verfügbaren umschlossenen Steuerelemente hinausgehen, können WPF und Windows Forms Anwendungen auch das WindowsXamlHost-Steuerelement verwenden, das im Windows Community Toolkit verfügbar ist.
| Steuerung | Unterstützte Mindestversion des Betriebssystems | Description |
|---|---|---|
| WindowsXamlHost | Windows 10, Version 1903 | Kann jedes UWP-XAML-Steuerelement hosten, das von Windows.UI.Xaml.UIElement abgeleitet wird, einschließlich aller UWP-XAML-Steuerelemente von Erstanbietern, die vom Windows SDK bereitgestellt werden, sowie benutzerdefinierter Steuerelemente. |
Für exemplarische Vorgehensweisen, die die Verwendung des Steuerelements WindowsXamlHost veranschaulichen, siehe Verwenden Sie XAML-Inseln, um ein UWP-XAML-Steuerelement in einer C#-WPF-Anwendung zu hosten und Ein benutzerdefiniertes UWP-XAML-Steuerelement in einer WPF-Anwendung mithilfe von XAML-Inseln hosten.
Konfigurieren Sie Ihr Projekt für die Verwendung der XAML-Island-.NET-Steuerelemente
Die XAML Island-.NET-Steuerelemente erfordern Windows 10, Version 1903 oder höher. 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 |
|---|---|---|
| Eingebettete Steuerelemente | Version 6.0.0 oder höher dieser Pakete:
|
Verwenden von XAML-Inseln zum Hosten eines UWP-XAML-Steuerelements in einer C#-WPF-App |
| Hoststeuerung | Version 6.0.0 oder höher dieser Pakete:
|
Verwenden von XAML-Inseln zum Hosten eines UWP-XAML-Steuerelements in einer C#-WPF-App Hosten Sie ein benutzerdefiniertes UWP-XAML-Steuerelement in einer WPF App |
Bitte beachten Sie die folgenden Details:
Die Pakete der Hoststeuerelemente sind auch in den Paketen der umschlossenen Steuerelemente enthalten. Sie können die Pakete mit den umschließenden Steuerelementen installieren, wenn Sie beide Steuerelementsätze verwenden möchten.
Wenn Sie ein benutzerdefiniertes UWP-XAML-Steuerelement hosten, müssen Sie auch einige zusätzliche Schritte ausführen, um auf das benutzerdefinierte Steuerelement zu verweisen. Weitere Informationen finden Sie unter Hosten eines benutzerdefinierten UWP-XAML-Steuerelements in einer WPF App mit XAML-Inseln.
Steuerelemente für die Webansicht
Das Windows Community Toolkit bietet außerdem die folgenden .NET Steuerelemente zum Hosten von Webinhalten in WPF- und Windows Forms-Anwendungen. Diese Steuerelemente werden häufig in ähnlichen Desktop-App-Modernisierungsszenarien wie die XAML Island-Steuerelemente verwendet und werden in demselben Microsoft.Toolkit.Win32-Repository wie die XAML Island-Steuerelemente verwaltet.
| Steuerung | Unterstützte Mindestversion des Betriebssystems | Description |
|---|---|---|
| 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 das Microsoft Edge-Renderingmodul, um Webinhalte in Windows 10 Version 1803 und höher anzuzeigen, und das Internet Explorer-Renderingmodul, um Webinhalte in früheren Versionen von Windows 10, Windows 8.x und Windows 7 anzuzeigen. |
Installieren Sie eins dieser NuGet-Pakete, um diese Steuerelemente zu verwenden:
- de-DE: 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 UWP XAML-Hosting-API verwenden, die vom Windows 10 SDK (Version 1903 und höher) bereitgestellt wird.
Die UWP XAML-Hosting-API besteht aus verschiedenen Windows-Runtime-Klassen und COM-Schnittstellen, mit denen Ihre C++-Desktopanwendung jedes UWP-XAML-Steuerelement hosten kann, das von Windows.UI.Xaml.UIElement abgeleitet ist. Sie können UWP-XAML-Steuerelemente in jedem UI-Element in Ihrer Anwendung hosten, das über ein zugeordnetes Fensterhandle (HWND) verfügt. Weitere Informationen zu dieser API findest du in den folgenden Artikeln.
- Verwenden der UWP-XAML-Hosting-API in einer C++-Desktop-App
- Hosten eines standardmäßigen UWP-XAML-Steuerelements in einer C++-Desktop-App
- Hosten eines benutzerdefinierten UWP-XAML-Steuerelements in einer C++-Desktop-App
Hinweis
Die umschlossenen Steuerelemente und Hoststeuerelemente im Windows Community Toolkit verwenden die UWP-XAML-Hosting-API intern und implementieren das gesamte Verhalten, das Sie andernfalls selbst behandeln müssen, wenn Sie die UWP-XAML-Hosting-API direkt verwendet haben, einschließlich Tastaturnavigation und Layoutänderungen. Für WPF- und Windows-Forms-Anwendungen empfehlen wir dringend, diese Steuerelemente zu verwenden, anstatt die UWP-XAML-Hosting-API direkt zu nutzen, da sie viele der Implementierungsdetails der API verbergen.
Architektur von UWP-XAML-Inseln
Hier sehen Sie sich an, wie die verschiedenen Typen von XAML Island-Steuerelementen architekturmäßig über der UWP-XAML-Hosting-API organisiert werden.
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 in Desktop-Apps erläutert, die UWP-XAML-Inseln verwenden.
Nur mit Problemumgehungen unterstützt
✔️ Das Hosten von Steuerelementen aus der WinUI für UWP-Bibliothek in einer XAML-Insel wird bedingt in der aktuellen Version von UWP-XAML-Inseln 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.
✔️ Wenn Sie auf das Stammelement einer Struktur von XAML-Inhalten in einer XAML-Insel zugreifen und verwandte Informationen zum Kontext abrufen möchten, in dem sie gehostet wird, verwenden Sie die Klassen CoreWindow, ApplicationView und Window nicht. Verwende stattdessen die XamlRoot-Klasse. Weitere Informationen finden Sie in diesem Abschnitt.
✔️ Zur Unterstützung des Freigabe-Vertrags aus einer WPF-, Windows Forms- oder C++-Desktop-App (Win32) muss Ihre App die Schnittstelle IDataTransferManagerInterop verwenden, um das DataTransferManager-Objekt abzurufen und den Freigabevorgang für ein bestimmtes Fenster zu initiieren. Ein Beispiel zur Verwendung dieser Schnittstelle in einer WPF-App finden Sie im Beispiel ShareSource.
✔️ Die Verwendung x:Bind mit gehosteten Steuerelementen in UWP-XAML-Inseln wird nicht unterstützt. Sie müssen das Datenmodell in einer .NET Standardbibliothek deklarieren.
Nicht unterstützt
🚫 Verwenden von UWP XAML Islands in WPF- und Windows Forms-Anwendungen, die das .NET Framework anvisieren. UWP-XAML-Inseln werden nur in Apps unterstützt, die auf .NET Core 3.x abzielen.
🚫 UWP XAML-Inhalt in UWP XAML-Inseln reagiert zur Laufzeit nicht auf Windows-Themenänderungen von dunkel in hell oder umgekehrt. Inhalt reagiert zur Laufzeit auf Änderungen des hohen Kontrasts.
🚫 Hinzufügen eines Windows.UI.Xaml.WebView-Steuerelements. Informationen zu WPF- und WinForms-Apps finden Sie unter these alternatives.
🚫 Das MediaPlayer-Steuerelement und MediaPlayerElement Hoststeuerelement 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.
🚫 UWP-XAML-Inseln unterstützen nicht das Hosten eines ContentDialog, das ein Steuerelement enthält, das Texteingaben akzeptiert, z. B. TextBox, RichEditBox oder AutoSuggestBox. 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.
🚫 UWP XAML-Inseln unterstützen derzeit die Anzeige von SVG-Dateien weder in einem gehosteten Windows.UI.Xaml.Controls.Image-Steuerelement noch durch die 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 UWP-XAML-Inseln in einer Desktop-App hosten, können Sie mehrere Hierarchien von XAML-Inhalten gleichzeitig im selben Thread verwenden. Verwenden Sie die Klasse XamlRoot, um auf das Stammelement einer Struktur von XAML-Inhalten in einer XAML-Insel zuzugreifen und verwandte Informationen über den Kontext abzurufen, in dem sie gehostet wird. Die Klassen "CoreWindow", "ApplicationView" und "Window " enthalten keine korrekten Informationen für UWP-XAML-Inseln. 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 Fenstermanagement-Hosts.
Verwenden Sie beispielsweise die XamlRoot.Size-Eigenschaft des Steuerelements, um das umgebende Rechteck des Fensters abzurufen, das ein UWP-XAML-Steuerelement enthält, das in einer XAML-Insel gehostet wird. Da jedes UWP-XAML-Steuerelement, das in einer XAML-Insel gehostet werden kann, von Windows.UI.Xaml.UIElement abgeleitet ist, können Sie die Eigenschaft XamlRoot 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 UWP 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 UWP-XAML-Inseln und den empfohlenen XamlRoot-Ersetzungen vermeiden sollten, finden Sie in der Tabelle in diesem Abschnitt.
Ein Beispiel zur Verwendung dieser Schnittstelle in einer WPF-App finden Sie im Beispiel ShareSource.
Weitere Ressourcen
Weitere Hintergrundinformationen und Lernprogramme zur Verwendung von UWP-XAML-Inseln finden Sie in den folgenden Artikeln und Ressourcen:
- Codebeispiele für UWP-XAML-Inseln: Dieses Repository enthält Beispiele Windows Forms, WPF und C++-Desktop (Win32), die veranschaulichen, wie UWP-XAML-Inseln verwendet werden.
- UWP-XAML-Inseln v1 – Updates und Roadmap: In diesem Blogbeitrag werden viele häufig gestellte Fragen zu UWP-XAML-Inseln erläutert und eine detaillierte Entwicklungsroadmap bereitgestellt.