Utilisation de l’API d’hébergement 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.

Les applications de bureau non UWP (y compris le bureau C++ (Win32), les WPF et les applications Windows Forms) peuvent utiliser l’API d’hébergement XAML UWP pour héberger des contrôles XAML UWP dans n’importe quel élément d’interface utilisateur associé à un handle de fenêtre (HWND). Pour obtenir une vue d’ensemble de cette fonctionnalité, consultez Héberger des contrôles XAML UWP dans les applications bureautiques (XAML Islands UWP).

L’API d’hébergement XAML UWP est-elle le bon choix pour votre application de bureau ?

L’API d’hébergement XAML UWP fournit l’infrastructure de bas niveau pour l’hébergement de contrôles XAML UWP dans les applications de bureau. Certains types d’applications de bureau ont la possibilité d’utiliser d’autres API plus pratiques pour atteindre cet objectif.

  • Si vous disposez d’une application de bureau C++ et que vous souhaitez héberger des contrôles XAML UWP dans votre application, vous devez utiliser l’API d’hébergement XAML UWP. Il n’existe aucune alternative pour ces types d’applications.

  • Pour les applications WPF et Windows Forms, nous vous recommandons vivement d’utiliser les contrôles XAML Island .NET dans Windows Community Toolkit au lieu d’utiliser directement l’API d’hébergement XAML UWP. Ces contrôles utilisent l’API d’hébergement XAML UWP en interne et implémentent tout le comportement que vous devez gérer autrement si vous avez utilisé directement l’API d’hébergement XAML UWP, y compris la navigation au clavier et les modifications de disposition.

Étant donné que nous vous recommandons de n’utiliser que les applications de bureau C++ utilisent l’API d’hébergement XAML UWP, cet article fournit principalement des instructions et des exemples pour les applications de bureau C++. Toutefois, vous pouvez utiliser l’API d’hébergement XAML UWP dans WPF et les applications Windows Forms si vous le souhaitez. Cet article pointe vers le code source pertinent pour les contrôles host pour les WPF et les Windows Forms dans Windows Community Toolkit afin de voir comment l’API d’hébergement XAML UWP est utilisée par ces contrôles.

Découvrez comment utiliser l’API d’hébergement XAML

Pour suivre des instructions pas à pas avec des exemples de code pour utiliser l’API d’hébergement XAML dans les applications de bureau C++, consultez les articles suivants :

Échantillons

La façon dont vous utilisez l’API d’hébergement XAML UWP dans votre code dépend du type de votre application, de la conception de votre application et d’autres facteurs. Pour vous aider à illustrer l’utilisation de cette API dans le contexte d’une application complète, cet article fait référence au code des exemples suivants.

C++ pour bureau (Win32)

Les exemples suivants montrent comment utiliser l’API d’hébergement XAML UWP dans une application de bureau C++ :

  • Exemple simple de XAML Island. Cet exemple illustre une implémentation de base de l’hébergement d’un contrôle XAML UWP dans une application de bureau C++ non empaquetée.

  • XAML Island avec un exemple de contrôle personnalisé. Cet exemple illustre une implémentation complète de l’hébergement d’un contrôle XAML UWP personnalisé dans une application de bureau C++ empaquetée, ainsi que la gestion d’autres comportements tels que l’entrée du clavier et la navigation de focus.

WPF et Windows Forms

Le contrôle WindowsXamlHost dans Windows Community Toolkit sert d’exemple de référence pour l’utilisation de l’API d’hébergement XAML UWP dans les applications WPF et Windows Forms. Le code source est disponible aux emplacements suivants :

Note

Nous vous recommandons vivement d’utiliser les contrôles XAML Island .NET dans Windows Community Toolkit au lieu d’utiliser l’API d’hébergement XAML UWP directement dans WPF et les applications Windows Forms. Les exemples de liens WPF et Windows Forms dans cet article sont uniquement à des fins d’illustration.

Architecture de l’API

L’API d’hébergement XAML UWP inclut ces principaux types de Windows Runtime et interfaces COM.

Type ou interface Descriptif
WindowsXamlManager Cette classe représente l’infrastructure XAML UWP. Cette classe fournit une méthode InitializeForCurrentThread statique unique qui initialise l’infrastructure XAML UWP sur le thread actuel dans l’application de bureau.
DesktopWindowXamlSource Cette classe représente une instance de contenu XAML UWP que vous hébergez dans votre application de bureau. Le membre le plus important de cette classe est la propriété Content . Vous affectez cette propriété à un élément Windows.UI.Xaml.UIElement que vous souhaitez héberger. Cette classe a également d’autres membres pour acheminer la navigation du focus clavier dans et à partir des îles XAML.
IDesktopWindowXamlSourceNative Cette interface COM fournit la méthode AttachToWindow , que vous utilisez pour attacher un îlot XAML dans votre application à un élément d’interface utilisateur parent. Chaque objet DesktopWindowXamlSource implémente cette interface.
IDesktopWindowXamlSourceNative2 Cette interface COM fournit la méthode PreTranslateMessage , qui permet au framework XAML UWP de traiter correctement certains messages Windows. Chaque objet DesktopWindowXamlSource implémente cette interface.

Le diagramme suivant illustre la hiérarchie des objets d’une île XAML hébergée dans une application de bureau.

  • À la base de votre application se trouve l'élément d'interface utilisateur où vous souhaitez héberger l'île XAML. Cet élément d’interface utilisateur doit avoir un handle de fenêtre (HWND). Les exemples d’éléments d’interface utilisateur dans lesquels vous pouvez héberger un îlot XAML incluent un window pour les applications de bureau C++, un System.Windows.Interop.HwndHost pour les applications WPF et un System.Windows.Forms.Control pour les applications Windows Forms.

  • Au niveau suivant, il s’agit d’un objet DesktopWindowXamlSource . Cet objet fournit l’infrastructure permettant d’héberger l’île XAML. Votre code est chargé de créer cet objet et de l’attacher à l’élément d’interface utilisateur parent.

  • Lorsque vous créez un DesktopWindowXamlSource, cet objet crée automatiquement une fenêtre enfant native pour héberger votre contrôle XAML UWP. Cette fenêtre enfant native est principalement abstraite de votre code, mais vous pouvez accéder à son identifiant (HWND) si nécessaire.

  • Enfin, au niveau supérieur est le contrôle XAML UWP que vous souhaitez héberger dans votre application de bureau. Il peut s’agir de n’importe quel objet UWP qui dérive de Windows. UI. Xaml.UIElement, y compris tout contrôle XAML UWP fourni par le SDK Windows ainsi que les contrôles utilisateur personnalisés.

Architecture de DesktopWindowXamlSource

Note

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 API CoreWindow, ApplicationView et Window ne fournissent pas les informations appropriées pour les îles XAML UWP. Pour plus d’informations, consultez cettesection.

Meilleures pratiques

Lorsque vous utilisez l’API d’hébergement XAML UWP, suivez ces bonnes pratiques pour chaque thread qui héberge les contrôles XAML UWP :

Résolution des problèmes

Erreur lors de l’utilisation de l’API d’hébergement XAML UWP dans une application UWP

Problème Résolution
Votre application reçoit une COMException avec le message suivant : « Impossible d’activer DesktopWindowXamlSource. Ce type ne peut pas être utilisé dans une application UWP. » ou « Impossible d’activer WindowsXamlManager. Ce type ne peut pas être utilisé dans une application UWP. » Cette erreur indique que vous essayez d’utiliser l’API d’hébergement XAML UWP (en particulier, vous essayez d’instancier les types DesktopWindowXamlSource ou WindowsXamlManager ) dans une application UWP. L’API d’hébergement XAML UWP est destinée uniquement à être utilisée dans les applications de bureau non UWP, telles que WPF, Windows Forms et les applications de bureau C++.

Erreur lors de la tentative d’utilisation des types WindowsXamlManager ou DesktopWindowXamlSource

Problème Résolution
Votre application reçoit une exception avec le message suivant : « WindowsXamlManager et DesktopWindowXamlSource sont pris en charge pour les applications ciblant Windows version 10.0.18226.0 et ultérieures. Vérifiez le manifeste de l’application ou le manifeste du package et vérifiez que la propriété MaxTestedVersion est mise à jour. » Cette erreur indique que votre application a essayé d'utiliser les types WindowsXamlManager ou DesktopWindowXamlSource dans l'API d'hébergement XAML UWP, mais le système d'exploitation ne peut pas déterminer si l'application a été créée pour cibler Windows 10, version 1903 ou ultérieure. L’API d’hébergement XAML UWP a d’abord été introduite en préversion dans une version antérieure de Windows 10, mais elle n’est prise en charge qu’à partir de Windows 10, version 1903.

Pour résoudre ce problème, créez un package MSIX pour l’application et exécutez-le à partir du package, ou installez le package Microsoft.Toolkit.Win32.UI.SDK package NuGet dans votre project.

Erreur lors de l’attachement à une fenêtre sur un autre thread

Problème Résolution
Votre application reçoit une exception COMException avec le message suivant : « Échec de la méthode AttachToWindow, car le HWND spécifié a été créé sur un autre thread ». Cette erreur indique que votre application a appelé la méthode IDesktopWindowXamlSourceNative ::AttachToWindow et lui a transmis le HWND d’une fenêtre créée sur un autre thread. Vous devez passer cette méthode le HWND d’une fenêtre créée sur le même thread que le code à partir duquel vous appelez la méthode.

Erreur lors de l’attachement à une fenêtre sur une autre fenêtre de niveau supérieur

Problème Résolution
Votre application reçoit une exception COMException avec le message suivant : « Échec de la méthode AttachToWindow, car le HWND spécifié descend d’une autre fenêtre de niveau supérieur que le HWND passé précédemment à AttachToWindow sur le même thread ». Cette erreur indique que votre application a appelé la méthode IDesktopWindowXamlSourceNative ::AttachToWindow et lui a transmis le HWND d’une fenêtre qui descend d’une autre fenêtre de niveau supérieur qu’une fenêtre que vous avez spécifiée dans un appel précédent à cette méthode sur le même thread.

Une fois que votre application a appelé AttachToWindow sur un thread particulier, tous les autres objets DesktopWindowXamlSource sur le même thread peuvent uniquement s’attacher à des fenêtres qui sont des descendants de la même fenêtre de niveau supérieur qui a été passée dans le premier appel à AttachToWindow. Lorsque tous les objets DesktopWindowXamlSource sont fermés pour un thread particulier, desktopWindowXamlSource suivant est alors libre d’attacher à n’importe quelle fenêtre.

Pour résoudre ce problème, fermez tous les objets DesktopWindowXamlSource liés à d’autres fenêtres de niveau supérieur sur ce thread, ou créez un thread pour ce DesktopWindowXamlSource.
  • Last updated on