Héberger des contrôles XAML WinRT dans des applications de bureau (XAML Islands)

  • Article

Important

Cette rubrique utilise ou mentionne des types du dépôt GitHub CommunityToolkit/Microsoft.Toolkit.Win32. Pour obtenir des informations importantes sur la prise en charge de XAML Islands, consultez l’avis XAML Islands dans ce dépôt.

À compter de Windows 10 version 1903, vous pouvez héberger des contrôles XAML WinRT dans des applications de bureau non conçues pour UWP à l’aide d’une fonctionnalité appelée XAML Islands. Vous pouvez ainsi améliorer l’apparence, le comportement et les fonctionnalités de vos applications WPF, Windows Forms et C++ (Win32) existantes, mais aussi bénéficier des dernières nouveautés de l’interface utilisateur Windows qui sont uniquement disponibles par le biais de contrôles XAML WinRT. Cela signifie que vous pouvez utiliser des fonctionnalités UWP telles que Windows Ink et des contrôles prenant en charge le système Fluent Design dans vos applications WPF, vos applications Windows Forms et vos applications de bureau C++ existantes.

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

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

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

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

Note

Si vous avez des choses à nous dire sur XAML Islands, ouvrez un nouveau problème dans le dépôt Microsoft.Toolkit.Win32 et laissez-y vos commentaires.

Configuration requise

Les conditions requises du runtime pour XAML Islands sont les 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 de XAML Islands pour héberger des contrôles XAML WinRT dans des applications WPF et Windows Forms est pris en charge seulement dans les applications ciblant .NET Core 3.x. XAML Islands n’est pas encore pris en charge dans les applications ciblant .NET ou n’importe quelle version du .NET Framework.

Nous recommandons que les applications WPF et Windows Forms utilisent les contrôles .NET XAML Island disponibles dans le Windows Community Toolkit. Ces contrôles fournissent un modèle objet qui imite les propriétés, méthodes et événements des contrôles XAML WinRT correspondants ou qui vous donne accès à ces éléments. 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 wrappés et les contrôles hôtes.

Contrôles wrappés

Les applications WPF et Windows Forms peuvent utiliser une sélection de contrôles XAML Islands qui wrappent l’interface et les fonctionnalités d’un contrôle XAML WinRT spécifique. Vous pouvez ajouter ces contrôles directement à l’aire de conception de votre projet WPF ou Windows Forms, puis les utiliser comme tout autre contrôle WPF ou Windows Forms dans le concepteur.

Les contrôles XAML WinRT wrappés suivants sont actuellement disponibles dans le Windows Community Toolkit.

Control Système d’exploitation minimal pris en charge Description
InkCanvas
InkToolbar		 Windows 10, version 1903 Fournissent une surface et les barres d’outils associées pour l’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 en streaming du contenu multimédia tel que des vidéos dans votre application de bureau Windows Forms ou WPF.
MapControl Windows 10, version 1903 Permet d’afficher une carte symbolique ou photoréaliste dans votre application de bureau Windows Forms ou WPF.

Pour découvrir pas à pas comment utiliser les contrôles XAML WinRT wrappés, consultez Utiliser XAML Islands pour héberger un contrôle XAML UWP dans une application WPF C#.

Contrôles hôtes

Pour les contrôles personnalisés et des scénarios autres que ceux couverts par les contrôles wrappés disponibles, les applications WPF et Windows Forms peuvent également utiliser le contrôle WindowsXamlHost proposé dans le Windows Community Toolkit.

Control Système d’exploitation minimal pris en charge Description
WindowsXamlHost Windows 10, version 1903 Peut héberger n’importe quel contrôle XAML WinRT dérivé de Windows.UI.Xaml.UIElement, notamment tout contrôle XAML WinRT interne fourni par le SDK Windows, ainsi que des contrôles personnalisés.

Pour découvrir pas à pas comment utiliser le contrôle WindowsXamlHost, consultez Utiliser XAML Islands pour héberger un contrôle XAML UWP dans une application WPF C# et Héberger un contrôle XAML WinRT personnalisé dans une application WPF avec XAML Islands.

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

Les contrôles .NET XAML Island nécessitent Windows 10 version 1903 ou 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 Package NuGet Articles associés
Contrôles wrappés Version 6.0.0 ou ultérieure de ces packages : Utiliser XAML Islands pour héberger un contrôle XAML UWP dans une application WPF C#
Contrôle hôte Version 6.0.0 ou ultérieure de ces packages : Utiliser XAML Islands pour héberger un contrôle XAML UWP dans une application WPF C#
Héberger un contrôle XAML WinRT 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 WinRT personnalisé, vous devrez également effectuer quelques étapes supplémentaires pour référencer le contrôle personnalisé. Pour plus d’informations, consultez Héberger un contrôle XAML WinRT personnalisé dans une application WPF avec XAML Islands.

Contrôles de vue web

Le Windows Community Toolkit fournit également les contrôles .NET suivants pour héberger du contenu web dans les applications WPF et Windows Forms. Ces contrôles sont souvent utilisés dans des scénarios de modernisation d’applications bureautiques similaires à ceux des contrôles XAML Island. Ils sont conservés dans le même référentiel Microsoft.Toolkit.Win32 que les contrôles XAML Island.

Control Système d’exploitation minimal pris en charge Description
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 versions 1803 et ultérieures, 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 Islands ne sont pas pris en charge dans les applications de bureau C++. Ces applications doivent utiliser à la place l’API d’hébergement XAML WinRT fournie par le SDK Windows 10 (versions 1903 et ultérieures).

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

Note

Les contrôles wrappés et hôtes dans le Windows Community Toolkit utilisent l’API d’hébergement XAML WinRT en interne et implémentent tous les comportements que vous devriez gérer vous-même si vous utilisiez cette API directement, comme la navigation au clavier et les changements 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 WinRT directement, car ils éliminent un grand nombre des détails d’implémentation associés à l’utilisation de l’API.

Architecture des contrôles XAML Islands

Voici un bref aperçu de l’organisation architecturale des différents types de contrôles XAML Island au-dessus de l’API d’hébergement XAML WinRT.

Host control Architecture

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

Limitations et solutions de contournement

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

Prise en charge uniquement avec des solutions de contournement

✔️ L’hébergement de contrôles de la bibliothèque WinUI 2 dans un îlot XAML est pris en charge de manière conditionnelle dans la version actuelle de XAML Islands. 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. La prise en charge de l’hébergement des contrôles de la bibliothèque WinUI 3.0 sera disponible dans une version ultérieure.

✔️ Pour accéder à l’élément racine d’une arborescence de contenu XAML dans un îlot XAML et obtenir des informations connexes sur le contexte de son hébergement, 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 de partage d’une application de bureau WPF, Windows Forms ou Win32 C++, votre application doit utiliser l’interface IDataTransferManagerInterop pour obtenir l’objet DataTransferManager afin de lancer l’opération de partage pour une fenêtre spécifique. Pour obtenir un exemple qui illustre l’utilisation de cette interface dans une application WPF, consultez l’exemple ShareSource.

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

Non prise en charge

🚫 Utilisation de XAML Islands dans les applications WPF et Windows Forms qui ciblent le .NET Framework. XAML Islands est pris en charge uniquement dans les applications qui ciblent .NET Core 3.x.

🚫 Le contenu XAML UWP dans XAML Islands ne répond pas aux modifications de thème Windows du mode sombre au mode clair, ou vice versa, au moment de 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 le contrôle hôte MediaPlayerElement ne sont pas pris en charge en mode plein écran.

🚫 Entrée de texte avec la vue de l’é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 îles XAML ne prennent pas en charge l’hébergement d’un ContentDialog contenant un contrôle qui accepte une entrée de texte, comme 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.

🚫 Actuellement, les îles XAML ne prennent pas en charge l’affichage des fichiers SVG dans un contrôle Windows.UI.Xaml.Controls.Image hébergé 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êtrage pour XAML Islands

Quand vous hébergez XAML Islands dans une application de bureau, plusieurs arborescences de contenu XAML peuvent s’exécuter simultanément sur le même thread. Pour accéder à l’élément racine d’une arborescence de contenu XAML dans un XAML Islands et obtenir des informations connexes sur le contexte de son hébergement, utilisez la classe XamlRoot. Les classes CoreWindow, ApplicationView et Window ne fournissent pas les informations correctes pour XAML Islands. 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 fenêtrage.

Par exemple, pour obtenir le rectangle englobant de la fenêtre qui contient un contrôle XAML WinRT hébergé dans XAML Islands, utilisez la propriété XamlRoot.Size du contrôle. Étant donné que chaque contrôle XAML WinRT qui peut être hébergé dans XAML Islands est dérivé 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 WinRT XAML control that is hosted in a XAML Island.
Rect windowSize = CoreWindow.GetForCurrentThread().Bounds;

Pour avoir la liste des API de fenêtrage courantes à proscrire dans le contexte de XAML Islands et connaître le code de remplacement XamlRoot recommandé, consultez le tableau dans cette section.

Pour obtenir un exemple qui illustre l’utilisation de cette interface dans une application WPF, consultez l’exemple ShareSource.

Ressources supplémentaires

Pour obtenir plus d’informations générales et des tutoriels sur l’utilisation de XAML Islands, consultez les articles et ressources suivants :

  • Moderniser un didacticiel d'application WPF : Ce didacticiel fournit des instructions étape par étape pour utiliser les contrôles encapsulés et les contrôles hôtes dans le Kit de ressources de la communauté Windows afin d'ajouter des contrôles WinRT XAML à une application métier WPF existante. Ce tutoriel comprend le code complet de l’application WPF ainsi que des instructions détaillées pour chaque étape du processus.
  • Exemples de code XAML Islands : Ce dépôt contient des exemples Windows Forms, WPF et C++ (Win32) qui montrent comment utiliser XAML Islands.
  • XAML Islands v1 – Mises à jour et feuille de route : Ce billet de blog aborde de nombreuses questions courantes sur les îles XAML et fournit une feuille de route de développement détaillée.