Héberger des contrôles XAML UWP dans les applications de bureau (îles XAML UWP)

Important

Cette rubrique utilise ou mentionne les types du dépôt CommunityToolkit/Microsoft.Toolkit.Win32 GitHub. Pour plus d’informations sur la prise en charge des îles XAML UWP, consultez l'XaML Islands Notice dans ce référentiel.

À partir de Windows 10, version 1903, vous pouvez héberger des contrôles XAML UWP dans des applications de bureau non UWP à l’aide d’une fonctionnalité appelée UWP XAML Islands. Cette fonctionnalité vous permet d’améliorer l’apparence et les fonctionnalités de vos applications de bureau WPF, de Windows Forms et de bureau C++ (Win32) avec des fonctionnalités d’interface utilisateur Windows disponibles uniquement via des contrôles XAML UWP. Cela signifie que vous pouvez utiliser des fonctionnalités UWP telles que Windows Ink et des contrôles qui prennent en charge le système de conception Fluent Design System dans vos applications de bureau existantes WPF, Windows Forms et C++.

Vous pouvez héberger n’importe quel contrôle XAML UWP qui dérive de Windows. UI. Xaml.UIElement, notamment :

  • La plupart des contrôles XAML UWP tiers fournis par le SDK Windows ou la bibliothèque WinUI pour UWP (voir exceptions).
  • Tout contrôle XAML UWP personnalisé (par exemple, un contrôle utilisateur qui se compose de plusieurs contrôles XAML UWP qui fonctionnent ensemble). Vous devez disposer du code source du contrôle personnalisé pour pouvoir le compiler avec votre application.

Fondamentalement, les îles XAML UWP sont créées à l’aide de l’API d’hébergement XAML UWP. Cette API se compose de plusieurs classes Windows Runtime et interfaces COM introduites dans le kit SDK Windows 10, version 1903. Nous fournissons également un ensemble de contrôles .NET XAML Island dans le kit de ressources communauté Windows Community Toolkit qui utilisent l’API d’hébergement XAML UWP en interne et offrent une expérience de développement plus pratique pour les applications WPF et Windows Forms.

La façon dont vous utilisez UWP XAML Islands dépend de votre type d’application et des types de contrôles XAML UWP que vous souhaitez héberger.

Spécifications

Les îles XAML UWP ont les exigences d’exécution suivantes :

  • Windows 10, version 1903 ou ultérieure.
  • Si votre application n’est pas empaquetée dans un package MSIX pour la déployer, Visual C++ Runtime doit être installé sur l’ordinateur.

applications WPF et Windows Forms

Note

L’utilisation des îles XAML UWP pour héberger des contrôles XAML UWP dans WPF et les applications Windows Forms est actuellement prise en charge uniquement dans les applications qui ciblent .NET Core 3.x. Les îles XAML UWP ne sont pas encore prises en charge dans les applications qui ciblent .NET, ni dans les applications qui ciblent une version quelconque du .NET Framework.

Nous recommandons que les applications WPF et Windows Forms utilisent les contrôles XAML Island .NET disponibles dans le Windows Community Toolkit. Ces contrôles fournissent un modèle objet qui imite (ou fournit l’accès à) les propriétés, méthodes et événements des contrôles XAML UWP correspondants. Ils gèrent également des comportements tels que la navigation au clavier et les changements de disposition.

Il existe deux ensembles de contrôles XAML Island pour les applications WPF et Windows Forms : les contrôles wrapped et les contrôles host.

Contrôles enveloppés

WPF et les applications Windows Forms peuvent utiliser une sélection de contrôles XAML Island qui encapsulent l’interface et les fonctionnalités d’un contrôle XAML UWP spécifique. Vous pouvez ajouter ces contrôles directement à la surface de conception de votre projet WPF ou Windows Forms, puis les utiliser comme n'importe quel autre contrôle WPF ou Windows Forms dans le concepteur.

Les contrôles XAML UWP encapsulés suivants sont actuellement disponibles dans Windows Community Toolkit.

Contrôle Système d’exploitation minimal pris en charge Descriptif
InkCanvas
InkToolbar		 Windows 10, version 1903 Fournissez une surface et des barres d’outils associées pour une interaction utilisateur basée sur Windows Ink dans votre application de bureau Windows Forms ou WPF.
MediaPlayerElement Windows 10, version 1903 Incorpore une vue qui diffuse et restitue du contenu multimédia tel que la vidéo dans votre application de bureau Windows Forms ou WPF.
MapControl Windows 10, version 1903 Vous permet d’afficher une carte symbolique ou photoréaliste dans votre application de bureau Windows Forms ou WPF.

Pour obtenir une procédure pas à pas qui montre comment utiliser les contrôles XAML UWP encapsulés, consultez Use XAML Islands pour héberger un contrôle XAML UWP dans une application C# WPF.

Contrôles de l'hôte

Pour les contrôles personnalisés et d’autres scénarios au-delà de ceux couverts par les contrôles encapsulés disponibles, WPF et les applications Windows Forms peuvent également utiliser le contrôle WindowsXamlHost disponible dans le Kit de ressources de la communauté Windows.

Contrôle Système d’exploitation minimal pris en charge Descriptif
WindowsXamlHost Windows 10, version 1903 Peut héberger n’importe quel contrôle XAML UWP qui dérive de Windows. UI. Xaml.UIElement, y compris tout contrôle XAML UWP tiers fourni par le SDK Windows ainsi que les contrôles personnalisés.

Pour les procédures pas à pas qui montrent comment utiliser le contrôle WindowsXamlHost, voir Use XAML Islands pour héberger un contrôle XAML UWP dans une application C# WPF et Hoster un contrôle XAML UWP personnalisé dans une application WPF à l’aide de XAML Islands.

Configurer votre projet pour utiliser les contrôles .NET XAML Island

Les contrôles xaml Island .NET nécessitent Windows 10, version 1903 ou une version ultérieure. Pour utiliser ces contrôles, installez l’un des packages NuGet listés ci-dessous. Ces packages fournissent tout ce dont vous avez besoin pour utiliser les contrôles hôtes et les contrôles wrappés XAML Island, ainsi que d’autres packages NuGet connexes obligatoires.

Type de contrôle Paquet NuGet Articles connexes
Contrôles encapsulés Version 6.0.0 ou ultérieure de ces packages : Use XAML Islands pour héberger un contrôle XAML UWP dans une application C# WPF
Contrôle de l'hôte Version 6.0.0 ou ultérieure de ces packages : Use XAML Islands pour héberger un contrôle XAML UWP dans une application C# WPF
Hoster un contrôle XAML UWP personnalisé dans une application WPF

Tenez compte des points suivants :

  • Les packages de contrôles hôtes sont également inclus dans les packages de contrôles wrappés. Vous pouvez installer les packages de contrôles wrappés si vous souhaitez utiliser les deux ensembles de contrôles.

  • Si vous hébergez un contrôle XAML UWP personnalisé, vous devez également effectuer certaines étapes supplémentaires pour référencer le contrôle personnalisé. Pour plus d’informations, consultez Hoster un contrôle XAML UWP personnalisé dans une application WPF à l’aide de XAML Islands.

Contrôles de vue web

Windows Community Toolkit fournit également les contrôles de .NET suivants pour héberger du contenu web dans des applications WPF et Windows Forms. Ces contrôles sont souvent utilisés dans des scénarios de modernisation d’applications de bureau similaires en tant que contrôles XAML Island, et ils sont conservés dans le même Microsoft.Toolkit.Win32 repo que les contrôles XAML Island.

Contrôle Système d’exploitation minimal pris en charge Descriptif
WebView Windows 10, version 1803 Utilise le moteur de rendu Microsoft Edge pour afficher le contenu web.
WebViewCompatible Windows 7 Fournit une version de WebView compatible avec d’autres versions de système d’exploitation. Ce contrôle utilise le moteur de rendu Microsoft Edge pour afficher le contenu web sur Windows 10 version 1803 et ultérieure, et le moteur de rendu Internet Explorer pour afficher le contenu web sur les versions antérieures de Windows 10, Windows 8.x et Windows 7.

Pour utiliser ces contrôles, installez l’un des packages NuGet suivants :

Applications de bureau C++ (Win32)

Les contrôles .NET XAML Island ne sont pas pris en charge dans les applications de bureau C++. Ces applications doivent utiliser plutôt l’API d’hébergement XAML UWP fournie par le kit sdk Windows 10 (version 1903 et ultérieure).

L’API d’hébergement XAML UWP se compose de plusieurs classes Windows Runtime et interfaces COM que votre application de bureau C++ peut utiliser pour héberger n’importe quel contrôle XAML UWP qui dérive de Windows. UI. Xaml.UIElement. Vous pouvez héberger des contrôles XAML UWP dans n’importe quel élément d’interface utilisateur de votre application qui a un handle de fenêtre associé (HWND). Pour plus d’informations sur cette API, consultez les articles suivants.

Note

Les contrôles encapsulés et les contrôles hôtes dans le kit de ressources communauté Windows utilisent l’API d’hébergement XAML UWP en interne et implémentent tout le comportement que vous devez gérer vous-même si vous avez utilisé directement l’API d’hébergement XAML UWP, y compris la navigation au clavier et les modifications de disposition. Pour les applications WPF et Windows Forms, nous vous recommandons vivement d’utiliser ces contrôles au lieu de l’API d’hébergement XAML UWP directement, car ils éliminent de nombreux détails d’implémentation de l’utilisation de l’API.

Architecture des XAML Isles UWP

Voici un aperçu rapide de la façon dont les différents types de contrôles XAML Island sont organisés de manière architecturale en plus de l’API d’hébergement XAML UWP.

Architecture de contrôle à l'hôte

Les API présentes en bas de ce diagramme sont fournies avec le SDK Windows. Les contrôles encapsulés et les contrôles hôtes sont disponibles via des packages NuGet dans Windows Community Toolkit.

Limitations et solutions de contournement

Les sections suivantes décrivent les limitations et les solutions de contournement pour certains scénarios de développement UWP dans les applications de bureau qui utilisent des îles XAML UWP.

Prise en charge uniquement avec des solutions de contournement

✔️ L’hébergement de contrôles à partir de la bibliothèque WinUI pour UWP dans une île XAML est pris en charge sous certaines conditions dans la version actuelle des îles XAML UWP. Si votre application de bureau utilise un package MSIX pour le déploiement, vous pouvez héberger les contrôles WinUI des versions prépubliées et publiées du package NuGet Microsoft.UI.Xaml. Si votre application de bureau n’est pas empaquetée avec MSIX, vous pouvez héberger les contrôles WinUI uniquement si vous installez une préversion du package NuGet Microsoft.UI.Xaml ou si vous utilisez l’API de dépendances dynamiques.

✔️ Pour access l’élément racine d’une arborescence de contenu XAML dans une île XAML et obtenir des informations connexes sur le contexte dans lequel il est hébergé, n’utilisez pas les classes CoreWindow, ApplicationView et Window. Utilisez plutôt la classe XamlRoot. Pour plus d’informations, consultez cettesection.

✔️ Pour prendre en charge le contrat Partage à partir d’un WPF, Windows Forms ou l’application de bureau C++ (Win32), votre application doit utiliser l’interface IDataTransferManagerInterop pour obtenir l’objet DataTransferManager pour lancer l’opération de partage pour une fenêtre spécifique. Pour obtenir un exemple qui montre comment utiliser cette interface dans une application WPF, consultez l’exemple ShareSource.

✔️ L’utilisation de x:Bind avec des contrôles hébergés dans UWP XAML Islands n’est pas prise en charge. Vous devez déclarer le modèle de données dans une bibliothèque .NET Standard.

Non prise en charge

🚫 Utilisation des îles XAML UWP dans les applications WPF et Windows Forms ciblant le .NET Framework. Les îles XAML UWP sont prises en charge uniquement dans les applications qui ciblent .NET Core 3.x.

🚫 Le contenu XAML UWP des îles XAML ne répond pas aux changements de thème Windows du mode sombre au mode clair ou inversement pendant l'exécution. Le contenu répond aux modifications de contraste élevé au moment de l’exécution.

🚫 Ajout d’un contrôle Windows.UI.Xaml.WebView. Pour les applications WPF et WinForms, consultez ces alternatives.

🚫 Le contrôle MediaPlayer et MediaPlayerElement le contrôle hôte ne sont pas pris en charge en mode plein écran.

🚫 Entrée de texte avec le mode écriture manuscrite. Pour en savoir plus sur cette fonctionnalité, consultez cet article.

🚫 Contrôles de texte qui utilisent des liens de contenu @Places et @People. Pour en savoir plus sur cette fonctionnalité, consultez cet article.

🚫 îles XAML UWP ne prennent pas en charge l’hébergement d’un ContentDialog qui contient un contrôle qui accepte l’entrée de texte, comme un TextBox, RichEditBox ou AutoSuggestBox. Si vous procédez ainsi, le contrôle d’entrée ne répond pas correctement aux pressions sur les touches. Pour obtenir des fonctionnalités similaires à l’aide d’une île XAML, nous vous recommandons d’héberger un Popup contenant le contrôle d’entrée.

🚫 Les îles XAML de l'UWP ne prennent pas actuellement en charge l'affichage des fichiers SVG dans un Windows.UI.Xaml.Controls.Image ou en utilisant un objet Windows.UI.Xaml.Media.Imaging.SvgImageSource. Pour contourner ce problème, convertissez les fichiers image que vous souhaitez afficher au format raster, comme JPG ou PNG.

Contexte de l'hôte de fenêtre pour XAML Islands

Lorsque vous hébergez des îles XAML UWP dans une application de bureau, vous pouvez avoir plusieurs arborescences de contenu XAML s’exécutant sur le même thread en même temps. Pour access l’élément racine d’une arborescence de contenu XAML dans une île XAML et obtenir des informations connexes sur le contexte dans lequel il est hébergé, utilisez la classe XamlRoot. Les classes CoreWindow, ApplicationView et Window ne fournissent pas les informations appropriées pour les îles XAML UWP. Les objets CoreWindow et Window existent sur le thread et sont accessibles à votre application, mais ils ne retournent pas de limites ou de visibilité significatives (ils restent toujours invisibles et ont une taille de 1x1). Pour plus d’informations, consultez Hôtes de gestion de fenêtres.

Par exemple, pour obtenir le rectangle englobant de la fenêtre qui contient un contrôle XAML UWP hébergé dans un îlot XAML, utilisez la propriété XamlRoot.Size du contrôle. Étant donné que chaque contrôle XAML UWP qui peut être hébergé dans une île XAML dérive de Windows. UI. Xaml.UIElement, vous pouvez utiliser la propriété XamlRoot du contrôle pour accéder à l’objet XamlRoot.

Size windowSize = myUWPControl.XamlRoot.Size;

N’utilisez pas la propriété CoreWindows.Bounds pour obtenir le rectangle englobant.

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

Pour obtenir une table des API courantes liées au fenêtrage que vous devez éviter dans le contexte des îles XAML UWP et des remplacements XamlRoot recommandés, consultez le tableau de cette section.

Pour obtenir un exemple qui montre comment utiliser cette interface dans une application WPF, consultez l’exemple ShareSource.

Ressources supplémentaires

Pour plus d’informations et de didacticiels sur l’utilisation des îles XAML UWP, consultez les articles et ressources suivants :

  • exemples de code XAML Islands UWP : ce référentiel contient des exemples de bureau Windows Forms, de WPF et de bureau C++ (Win32) qui montrent comment utiliser des îles XAML UWP.
  • UWP XAML Islands v1 - Mises à jour et feuille de route : ce billet de blog traite de nombreuses questions courantes sur les îles XAML UWP et fournit une feuille de route de développement détaillée.
  • Last updated on