Utilisation de l’API d’hébergement XAML UWP dans une application Win32 C++Using the UWP XAML hosting API in a C++ Win32 app

Depuis Windows 10 version 1903, les applications de bureau non UWP (à savoir, les applications WPF, Windows Forms et Win32 C++) peuvent utiliser l’API d’hébergement XAML UWP pour héberger des contrôles UWP dans tout élément d’interface utilisateur associé à un identificateur de fenêtre (HWND).Starting in Windows 10, version 1903, non-UWP desktop apps (including C++ Win32, WPF, and Windows Forms apps) can use the UWP XAML hosting API to host UWP controls in any UI element that is associated with a window handle (HWND). Cette API permet aux applications de bureau non UWP d’utiliser les dernières fonctionnalités de l’interface utilisateur Windows 10 qui sont disponibles uniquement via des contrôles UWP.This API enables non-UWP desktop apps to use the latest Windows 10 UI features that are only available via UWP controls. Par exemple, des applications de bureau non UWP peuvent utiliser cette API pour héberger des contrôles UWP qui utilisent le Système de conception Fluent et prennent en charge Windows Ink.For example, non-UWP desktop apps can use this API to host UWP controls that use the Fluent Design System and support Windows Ink.

L’API d’hébergement XAML UWP constitue le fondement d’un ensemble plus large de contrôles que nous fournissons pour permettre aux développeurs d’intégrer l’interface utilisateur Fluent dans des applications de bureau non UWP.The UWP XAML hosting API provides the foundation for a broader set of controls that we are providing to enable developers to bring Fluent UI to non-UWP desktop apps. Cette fonctionnalité est nommée îlots XAML.This feature is called XAML Islands. Pour en obtenir une vue d’ensemble, consultez Héberger des contrôles XAML UWP dans des applications de bureau (îlots XAML).For an overview of this feature, see Host UWP XAML controls in desktop apps (XAML Islands).

Notes

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.If you have feedback about XAML Islands, create a new issue in the Microsoft.Toolkit.Win32 repo and leave your comments there. Si vous préférez que vos commentaires restent privés, envoyez-les à XamlIslandsFeedback@microsoft.com.If you prefer to submit your feedback privately, you can send it to XamlIslandsFeedback@microsoft.com. Vos insights et vos scénarios sont très importants pour nous.Your insights and scenarios are critically important to us.

L’API d’hébergement XAML UWP est-elle le bon choix pour votre application de bureau ?Is the UWP XAML hosting API the right choice for your desktop app?

L’API d’hébergement XAML UWP fournit l’infrastructure de bas niveau pour l’hébergement de contrôles UWP dans des applications de bureau.The UWP XAML hosting API provides the low-level infrastructure for hosting UWP controls in desktop apps. Certains types d’applications de bureau ont la possibilité d’utiliser d’autres API plus pratiques pour atteindre cet objectif.Some types of desktop apps have the option of using alternative, more convenient APIs to accomplish this goal.

  • Si vous avez une application de bureau Win32 C++ dans laquelle vous souhaitez héberger des contrôles UWP, vous devez utiliser l’API d’hébergement XAML UWP.If you have a C++ Win32 desktop app and you want to host UWP controls in your app, you must use the UWP XAML hosting API. Il n’existe aucune alternative pour ces types d’applications.There are no alternatives for these types of apps.

  • Pour des applications WPF et Windows Forms, nous vous recommandons vivement d’utiliser les contrôles .NET d’îlots XAML disponibles dans le Kit de ressources Communauté Windows au lieu d’utiliser directement l’API d’hébergement XAML UWP.For WPF and Windows Forms apps, we strongly recommend that you use the XAML Island .NET controls in the Windows Community Toolkit instead of using the UWP XAML hosting API directly. Ces contrôles utilisent l’API d’hébergement XAML UWP 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.These controls use the UWP XAML hosting API internally and implement all of the behavior you would otherwise need to handle yourself if you used the UWP XAML hosting API directly, including keyboard navigation and layout changes.

Étant donné que nous recommandons que seules les applications Win32 C++ utilisent l’API d’hébergement XAML UWP, cet article fournit principalement des instructions et des exemples pour les applications Win32 C++.Because we recommend that only C++ Win32 apps use the UWP XAML hosting API, this article primarily provides instructions and examples for C++ Win32 apps. Vous pouvez cependant utiliser l’API d’hébergement XAML UWP dans des applications WPF et Windows Forms si vous le souhaitez.However, you can use the UWP XAML hosting API in WPF and Windows Forms apps if you choose. Cet article pointe vers du code source pertinent pour les contrôles hôtes pour WPF et Windows Forms figurant dans le Kit de ressources Communauté Windows. Vous pouvez ainsi voir comment ces contrôles utilisent l’API d’hébergement XAML UWP.This article points to relevant source code for the host controls for WPF and Windows Forms in the Windows Community Toolkit so you can see how the UWP XAML hosting API is used by those controls.

Découvrez comment utiliser l’API d’hébergement XAMLLearn how to use the XAML Hosting API

Pour suivre des instructions pas à pas avec des exemples de code pour l’utilisation de l’API d’hébergement XAML dans des applications Win32 C++, consultez les articles suivants :To follow step-by-step instructions with code examples for using the XAML Hosting API in C++ Win32 apps, see these articles:

exemplesSamples

La façon dont vous utilisez l’API d’hébergement XAML UWP dans votre code dépend de votre type d’application, de la conception de votre application et d’autres facteurs.The way you use the UWP XAML hosting API in your code depends on your app type, the design of your app, and other factors. Pour 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.To help illustrate how to use this API in the context of a complete app, this article refers to code from the following samples.

Win32 C++C++ Win32

Les exemples suivants montrent comment utiliser l’API d’hébergement XAML UWP dans une application Win32 C++ :The following samples demonstrate how to use the UWP XAML hosting API in a C++ Win32 app:

  • Exemple d’îlot XAML simple.Simple XAML Island sample. Cet exemple illustre une implémentation de base de l’hébergement d’un contrôle UWP dans une application Win32 C++ non empaquetée (non intégrée dans un package MSIX).This sample demonstrates a basic implementation of hosting a UWP control in an unpackaged C++ Win32 app (that is, an app that is not built into an MSIX package).

  • Exemples d’îlot XAML avec contrôle personnalisé.XAML Island with custom control sample. Cet exemple illustre une implémentation complète de l’hébergement d’un contrôle UWP personnalisé dans une application Win32 C++ empaquetée, ainsi que la gestion d’autres comportements tels que la saisie au clavier et la navigation dans le focus.This sample demonstrates a complete implementation of hosting a custom UWP control in a packaged C++ Win32 app, as well as handling other behavior such as keyboard input and focus navigation.

WPF et Windows FormsWPF and Windows Forms

Le contrôle WindowsXamlHost dans le Kit de ressources Communauté Windows fait référence pour l’utilisation de l’API d’hébergement UWP dans des applications WPF et Windows Forms.The WindowsXamlHost control in the Windows Community Toolkit serves as a reference sample for using the UWP hosting API in WPF and Windows Forms apps. Le code source est disponible aux emplacements suivants :The source code is available at the following locations:

Notes

Nous vous recommandons vivement d’utiliser les contrôles .NET d’îlots XAML disponibles dans le Kit de ressources Communauté Windows au lieu d’utiliser l’API d’hébergement XAML UWP directement dans des applications WPF et Windows Forms.We strongly recommend that you use the XAML Island .NET controls in the Windows Community Toolkit instead of using the UWP XAML hosting API directly in WPF and Windows Forms apps. Les exemples de liens WPF et Windows Forms dans cet article sont fournis uniquement à titre d’illustration.The WPF and Windows Forms sample links in this article are for illustrative purposes only.

Architecture de l’APIArchitecture of the API

L’API d’hébergement XAML UWP comprend les principaux types de Windows Runtime et interfaces COM suivants.The UWP XAML hosting API includes these main Windows Runtime types and COM interfaces.

Type ou interfaceType or interface DescriptionDescription
WindowsXamlManagerWindowsXamlManager Cette classe représente l’infrastructure XAML UWP.This class represents the UWP XAML framework. Cette classe fournit une méthode statique InitializeForCurrentThread unique qui initialise l’infrastructure XAML UWP sur le thread actuel de l’application de bureau.This class provides a single static InitializeForCurrentThread method that initializes the UWP XAML framework on the current thread in the desktop app.
DesktopWindowXamlSourceDesktopWindowXamlSource Cette classe représente une instance du contenu XAML UWP que vous hébergez dans votre application de bureau.This class represents an instance of UWP XAML content that you are hosting in your desktop app. Le membre le plus important de cette classe est la propriété Content.The most important member of this class is the Content property. Vous attribuez cette propriété à un objet Windows.UI.Xaml.UIElement que vous souhaitez héberger.You assign this property to a Windows.UI.Xaml.UIElement that you want to host. Cette classe comprend également d’autres membres pour le routage de la navigation en mode focus au clavier à destination et à partir des îlots XAML.This class also has other members for routing keyboard focus navigation into and out of the XAML Islands.
IDesktopWindowXamlSourceNativeIDesktopWindowXamlSourceNative 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.This COM interface provides the AttachToWindow method, which you use to attach a XAML Island in your app to a parent UI element. Chaque objet DesktopWindowXamlSource implémente cette interface.Every DesktopWindowXamlSource object implements this interface. Cette interface est déclarée dans windows.ui.xaml.hosting.desktopwindowxamlsource.h.This interface is declared in windows.ui.xaml.hosting.desktopwindowxamlsource.h.
IDesktopWindowXamlSourceNative2IDesktopWindowXamlSourceNative2 Cette interface COM fournit la méthode PreTranslateMessage qui permet à l’infrastructure XAML UWP de traiter correctement certains messages Windows.This COM interface provides the PreTranslateMessage method, which enables the UWP XAML framework to process certain Windows messages correctly. Chaque objet DesktopWindowXamlSource implémente cette interface.Every DesktopWindowXamlSource object implements this interface. Cette interface est déclarée dans windows.ui.xaml.hosting.desktopwindowxamlsource.h.This interface is declared in windows.ui.xaml.hosting.desktopwindowxamlsource.h.

Le diagramme suivant illustre la hiérarchie d’objets dans un îlot XAML hébergé dans une application de bureau.The following diagram illustrates the hierarchy of objects in a XAML Island that is hosted in a desktop app.

  • Au niveau de base se trouve l’élément d’interface utilisateur dans votre application où vous souhaitez héberger l’îlot XAML.At the base level is the UI element in your app where you want to host the XAML Island. Cet élément d’interface utilisateur doit avoir un identificateur de fenêtre (HWND).This UI element must have a window handle (HWND). Les exemples d’éléments d’interface utilisateur dans lesquels vous pouvez héberger un îlot XAML incluent une fenêtre pour les applications Win32 C++, un System.Windows.Interop.HwndHost pour les applications WPF, et un System.Windows.Interop.HwndHost pour les applications Windows Forms.Examples of UI elements in which you can host a XAML Island include a window for C++ Win32 apps, a System.Windows.Interop.HwndHost for WPF apps, and a System.Windows.Forms.Control for Windows Forms apps.

  • Au niveau suivant se trouve un objet DesktopWindowXamlSource.At the next level is a DesktopWindowXamlSource object. Cet objet fournit l’infrastructure pour l’hébergement de l’îlot XAML.This object provides the infrastructure for hosting the XAML Island. Votre code est chargé de créer cet objet et de l’attacher à l’élément d’interface utilisateur parent.Your code is responsible for creating this object and attaching it to the parent UI element.

  • Lorsque vous créez un objet DesktopWindowXamlSource, celui-ci crée automatiquement une fenêtre enfant native pour héberger votre contrôle UWP.When you create a DesktopWindowXamlSource, this object automatically creates a native child window to host your UWP control. Cette fenêtre enfant native est principalement abstraite de votre code, mais vous pouvez accéder à son identificateur (HWND) si nécessaire.This native child window is mostly abstracted away from your code, but you can access its handle (HWND) if necessary.

  • Enfin, au niveau supérieur figure le contrôle UWP que vous souhaitez héberger dans votre application de bureau.Finally, at the top level is the UWP control you want to host in your desktop app. Il peut s’agir de n’importe quel objet UWP dérivant de Windows.UI.Xaml.UIElement, notamment de tout contrôle UWP fourni par le SDK Windows, ainsi que de contrôles utilisateur personnalisés.This can be any UWP object that derives from Windows.UI.Xaml.UIElement, including any UWP control provided by the Windows SDK as well as custom user controls.

Architecture de DesktopWindowXamlSource

Notes

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.When you host XAML Islands in a desktop app, you can have multiple trees of XAML content running on the same thread at the same time. 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.To access the root element of a tree of XAML content in a XAML Island and get related information about the context in which it is hosted, use the XamlRoot class. Les classes CoreWindow, ApplicationView et Window ne fournissent pas les informations correctes pour les îlots XAML.The CoreWindow, ApplicationView, and Window APIs won't provide the correct information for XAML Islands. Pour plus d’informations, consultez cette section.For more information, see this section.

Résolution des problèmesTroubleshooting

Erreur lors de l’utilisation de l’API d’hébergement XAML UWP dans une application UWPError using UWP XAML hosting API in a UWP app

ProblèmeIssue SolutionResolution
Votre application reçoit une COMException avec le message suivant : « Impossible d’activer DesktopWindowXamlSource.Your app receives a COMException with the following message: "Cannot activate DesktopWindowXamlSource. Ce type ne peut pas être utilisé dans une application UWP. »This type cannot be used in a UWP app." Ou « impossible d’activer WindowsXamlManager.or "Cannot activate WindowsXamlManager. Ce type ne peut pas être utilisé dans une application UWP. »This type cannot be used in a UWP app." 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.This error indicates you are trying to use the UWP XAML hosting API (specifically, you are trying to instantiate the DesktopWindowXamlSource or WindowsXamlManager types) in a UWP app. L’API d’hébergement XAML UWP est destinée à être utilisée uniquement dans les applications de bureau non UWP, telles que les applications WPF, Windows Forms et Win32 C++.The UWP XAML hosting API is only intended to be used in non-UWP desktop apps, such as WPF, Windows Forms, and C++ Win32 applications.

Erreur lors de la tentative d’utilisation des types WindowsXamlManager ou DesktopWindowXamlSourceError trying to use the WindowsXamlManager or DesktopWindowXamlSource types

ProblèmeIssue SolutionResolution
Votre application reçoit une exception avec le message suivant : «WindowsXamlManager et DesktopWindowXamlSource sont pris en charge pour les applications ciblant Windows, versions 10.0.18226.0 et ultérieures.Your app receives an exception with the following message: "WindowsXamlManager and DesktopWindowXamlSource are supported for apps targeting Windows version 10.0.18226.0 and later. Vérifiez le manifeste de l’application ou le manifeste du package et assurez-vous que la propriété MaxTestedVersion est à jour. »Please check either the application manifest or package manifest and ensure the MaxTestedVersion property is updated." Cette erreur indique que votre application a tenté d’utiliser les types WindowsXamlManager ou DesktopWindowXamlSource dans l’API d’hébergement XAML UWP, mais que 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.This error indicates that your application tried to use the WindowsXamlManager or DesktopWindowXamlSource types in the UWP XAML hosting API, but the OS can't determine whether the app was built to target Windows 10, version 1903 or later. L’API d’hébergement XAML UWP a été introduite pour la première fois en préversion dans une version antérieure de Windows 10, mais elle n’est prise en charge qu’à partir Windows 10, version 1903.The UWP XAML hosting API was first introduced as a preview in an earlier version of Windows 10, but it is only supported starting in Windows 10, version 1903.

Pour résoudre ce problème, créez un package MSIX pour l’application et exécutez-la à partir du package, ou installez le package NuGet Microsoft.Toolkit.Win32.UI.SDK dans votre projet.To resolve this issue, either create an MSIX package for the app and run it from the package, or install the Microsoft.Toolkit.Win32.UI.SDK NuGet package in your project.

Erreur lors de l’attachement à une fenêtre sur un autre threadError attaching to a window on a different thread

ProblèmeIssue SolutionResolution
Votre application reçoit une COMException avec le message suivant : « La méthode AttachToWindow a échoué parce que le HWND spécifié a été créé sur un autre thread. »Your app receives a COMException with the following message: "AttachToWindow method failed because the specified HWND was created on a different thread." Cette erreur indique que votre application a appelé la méthode IDesktopWindowXamlSourceNative::AttachToWindow et lui a passé le HWND d’une fenêtre qui a été créée sur un autre thread.This error indicates that your application called the IDesktopWindowXamlSourceNative::AttachToWindow method and passed it the HWND of a window that was created on a different 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.You must pass this method the HWND of a window that was created on the same thread as the code from which you are calling the method.

Erreur lors de l’attachement à une fenêtre dans une fenêtre de niveau supérieur différenteError attaching to a window on a different top-level window

ProblèmeIssue SolutionResolution
Votre application reçoit une COMException avec le message suivant : « La méthode AttachToWindow a échoué parce que le HWND spécifié descend d’une fenêtre de niveau supérieur différente du HWND qui était précédemment passé à la méthode AttachToWindow sur le même thread. »Your app receives a COMException with the following message: "AttachToWindow method failed because the specified HWND descends from a different top-level window than the HWND that was previously passed to AttachToWindow on the same thread." Cette erreur indique que votre application a appelé la méthode IDesktopWindowXamlSourceNative::AttachToWindow et lui a passé le HWND d’une fenêtre qui descend d’une fenêtre de niveau supérieur différente d’une fenêtre que vous avez spécifiée dans un appel précédent à cette méthode sur le même thread.This error indicates that your application called the IDesktopWindowXamlSourceNative::AttachToWindow method and passed it the HWND of a window that descends from a different top-level window than a window you specified in a previous call to this method on the same thread.

Après que votre application appelle la méthode AttachToWindow sur un thread particulier, tous les autres objets DesktopWindowXamlSource sur le même thread peuvent être attachés uniquement à des fenêtres qui descendent de la fenêtre de niveau supérieur qui a été passée dans le premier appel à la méthode AttachToWindow.After your application calls AttachToWindow on a particular thread, all other DesktopWindowXamlSource objects on the same thread can only attach to windows that are descendants of the same top-level window that was passed in the first call to AttachToWindow. Lorsque tous les objets DesktopWindowXamlSource sont fermés pour un thread particulier, l’objet DesktopWindowXamlSource suivant est libre de s’attacher à nouveau à toute fenêtre.When all the DesktopWindowXamlSource objects are closed for a particular thread, the next DesktopWindowXamlSource is then free to attach to any window again.

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 cet objet DesktopWindowXamlSource.To resolve this issue, either close all DesktopWindowXamlSource objects that are bound to other top-level windows on this thread, or create a new thread for this DesktopWindowXamlSource.