Bibliothèque de modèles C++ Windows Runtime (WRL)

  • Article

La bibliothèque de modèles C++ Windows Runtime (WRL) est une bibliothèque de modèles qui fournit un moyen de bas niveau de créer et d’utiliser des composants Windows Runtime.

Remarque

WRL est maintenant remplacé par C++/WinRT, une projection de langage C++17 standard pour les API Windows Runtime. C++/WinRT est disponible dans le Kit de développement logiciel (SDK) Windows à partir de la version 1803 (10.0.17134.0) à partir de la version 1803. C++/WinRT est entièrement implémenté dans les fichiers d’en-tête et conçu pour vous fournir un accès de première classe à l’API Windows moderne.

Avec C++/WinRT, vous pouvez utiliser et créer des API Windows Runtime à l’aide de n’importe quel compilateur C++17 conforme aux normes. C++/WinRT fonctionne généralement mieux et produit des fichiers binaires plus petits que n’importe quelle autre option de langage pour Windows Runtime. Nous continuerons de prendre en charge les langages C++/CX et WRL, mais recommandons vivement l’utilisation du langage C++/WinRT avec des nouvelles applications. Pour plus d’informations, consultez C++/WinRT.

Avantages

La bibliothèque de modèles C++ Windows Runtime vous permet d’implémenter et d’utiliser plus facilement les composants COM (Component Object Model). Il fournit des techniques de nettoyage telles que le comptage de références pour gérer la durée de vie des objets et tester les valeurs HRESULT pour déterminer si une opération a réussi ou échoué. Pour utiliser correctement la bibliothèque de modèles C++ Windows Runtime, vous devez suivre attentivement ces règles et techniques.

C++/CX est un moyen de haut niveau basé sur le langage d’utiliser des composants Windows Runtime. La bibliothèque de modèles C++ Windows Runtime et C++/CX simplifient l’écriture de code pour Windows Runtime en effectuant automatiquement des tâches de nettoyage en votre nom.

La bibliothèque de modèles C++ Windows Runtime et C++/CX offrent différents avantages. Voici quelques raisons pour lesquelles vous souhaiterez peut-être utiliser la bibliothèque de modèles C++ Windows Runtime au lieu de C++/CX :

  • La bibliothèque de modèles C++ Windows Runtime ajoute peu d’abstraction sur l’interface binaire d’application Windows Runtime (ABI), ce qui vous permet de contrôler le code sous-jacent pour mieux créer ou consommer des API Windows Runtime.

  • C++/CX représente les valeurs COM HRESULT en tant qu’exceptions. Si vous avez hérité une base de code qui utilise COM ou une base de code qui n’utilise pas d’exceptions, vous pouvez constater que la bibliothèque de modèles C++ Windows Runtime est un moyen plus naturel d’utiliser Windows Runtime, car vous n’avez pas besoin d’utiliser des exceptions.

    Remarque

    La bibliothèque de modèles C++ Windows Runtime utilise des valeurs HRESULT et ne lève pas d’exceptions. En outre, la bibliothèque de modèles C++ Windows Runtime utilise des pointeurs intelligents et le modèle RAII pour garantir que les objets sont détruits correctement lorsque le code de votre application lève une exception. Pour plus d’informations sur les pointeurs intelligents et RAII, consultez Smart Pointers and Objects Own Resources (RAII).

  • L’objectif et la conception de la bibliothèque de modèles Windows Runtime C++ sont inspirés par la bibliothèque de modèles active (ATL), qui est un ensemble de classes C++ basées sur des modèles qui simplifient la programmation d’objets COM. Étant donné que la bibliothèque de modèles C++ Windows Runtime utilise la bibliothèque de modèles C++ standard pour encapsuler Windows Runtime, vous pouvez plus facilement porter et interagir avec de nombreux composants COM existants écrits dans ATL dans Windows Runtime. Si vous connaissez déjà ATL, vous pouvez constater que la programmation de la bibliothèque de modèles C++ Windows Runtime est plus facile.

Mise en route

Voici quelques ressources qui peuvent vous aider à utiliser immédiatement la bibliothèque de modèles C++ Windows Runtime.

Guide pratique pour activer et utiliser un composant Windows Runtime
Montre comment utiliser la bibliothèque de modèles Windows Runtime C++ pour initialiser Windows Runtime et activer et utiliser un composant Windows Runtime.

Procédure : effectuer des opérations asynchrones
Montre comment utiliser la bibliothèque de modèles C++ Windows Runtime pour démarrer des opérations asynchrones et effectuer des opérations lorsque les opérations se terminent.

Guide pratique pour gérer les événements
Montre comment utiliser la bibliothèque de modèles C++ Windows Runtime pour s’abonner et gérer les événements d’un objet Windows Runtime.

Procédure pas à pas : création d’une application UWP à l’aide de WRL et Media Foundation
Découvrez comment créer une application UWP qui utilise Microsoft Media Foundation.

Guide pratique pour créer un composant COM classique
Montre comment utiliser la bibliothèque de modèles C++ Windows Runtime pour créer un composant COM de base et un moyen de base d’inscrire et d’utiliser le composant COM à partir d’une application de bureau.

Guide pratique pour instancier directement les composants WRL
Découvrez comment utiliser les fonctions Microsoft::WRL::Make et Microsoft::WRL::Details::MakeAndInitialize pour instancier un composant à partir du module qui le définit.

Guide pratique pour utiliser winmdidl.exe et midlrt.exe pour créer les fichiers .h à partir des métadonnées Windows
Montre comment consommer des composants Windows Runtime personnalisées à partir de WRL en créant un fichier IDL à partir des métadonnées .winmd.

Procédure pas à pas : connexion à l’aide de tâches et de requêtes HTTP XML
Montre comment utiliser les interfaces IXMLHTTPRequest2 et IXMLHTTPRequest2Callback avec des tâches pour envoyer des requêtes HTTP GET et POST à un service web dans une application UWP.

Exemple Bing Cartes Trip Optimizer
Utilise la HttpRequest classe définie dans la procédure pas à pas : Connecter ing Using Tasks and XML HTTP Requests in the context of a complete UWP app.

Création d’un composant DLL Windows Runtime avec l’exemple C++
Montre comment utiliser la bibliothèque de modèles Windows Runtime C++ pour créer un composant DLL in-process et l’utiliser à partir de C++/CX, JavaScript et C#.

Exemple de jeu de labyrinthe de marbre DirectX
Montre comment utiliser la bibliothèque de modèles Windows Runtime C++ pour gérer la durée de vie des composants COM tels que DirectX et Media Foundation dans le contexte d’un jeu 3D complet.

Notifications toast à partir d’applications de bureau
Montre comment envoyer des notifications toast à partir d’une application de bureau.

Bibliothèque de modèles C++ Windows Runtime par rapport à ATL

La bibliothèque de modèles C++ Windows Runtime ressemble à la bibliothèque de modèles active (ATL), car vous pouvez l’utiliser pour créer de petits objets COM rapides. La bibliothèque de modèles C++ Windows Runtime et ATL partagent également des concepts tels que la définition d’objets dans les modules, l’inscription explicite des interfaces et la création ouverte d’objets à l’aide de fabriques. Vous êtes peut-être à l’aise avec la bibliothèque de modèles C++ Windows Runtime si vous êtes familiarisé avec ATL.

La bibliothèque de modèles C++ Windows Runtime prend en charge les fonctionnalités COM requises pour les applications UWP. Par conséquent, elle diffère de la bibliothèque ATL car elle omet la prise en charge directe des fonctionnalités COM telles que :

  • agrégation

  • implémentations stock ;

  • interfaces doubles (IDispatch) ;

  • interfaces d'énumérateur standard ;

  • points de connexion ;

  • interfaces détachables ;

  • incorporation OLE ;

  • contrôles ActiveX ;

  • COM+

Concepts

La bibliothèque de modèles C++ Windows Runtime fournit des types qui représentent quelques concepts de base. Les sections suivantes décrivent ces types.

ComPtr

ComPtr est un type de pointeur intelligent qui représente l'interface spécifiée par le paramètre de modèle. Utilisez ComPtr pour déclarer une variable pouvant accéder aux membres d'un objet dérivé de l'interface. ComPtr met à jour automatiquement un décompte de références pour le pointeur d'interface sous-jacent et libère l'interface lorsque le décompte de références atteint zéro.

RuntimeClass

RuntimeClass représente une classe instanciée qui hérite d'un ensemble d'interfaces spécifiées. Un RuntimeClass objet peut fournir une combinaison de prise en charge d’une ou plusieurs interfaces COM Windows Runtime ou d’une référence faible à un composant.

Module

Module représente une collection d'objets connexes. Un objet Module gère les fabriques de classe, qui créent des objets, et l'inscription, qui permet à d'autres applications d'utiliser un objet.

Rappel

La fonction Callback crée un objet dont la fonction membre est un gestionnaire d'événements (une méthode de rappel). Utilisez la fonction Callback pour écrire des opérations asynchrones.

EventSource

EventSource sert à gérer des gestionnaires d'événements délégués . Utilisez la bibliothèque de modèles C++ Windows Runtime pour implémenter un délégué et l’utiliser EventSource pour ajouter, supprimer et appeler des délégués.

AsyncBase

AsyncBase fournit des méthodes virtuelles qui représentent le modèle de programmation asynchrone Windows Runtime. Redéfinissez les membres de cette classe pour créer une classe personnalisée capable de démarrer, arrêter ou contrôler la progression d'une opération asynchrone.

FtmBase

FtmBase représente un objet marshaler libre de threads. FtmBase crée un tableau global d'interface (GIT) et vous permet de gérer le marshaling et les objets proxy.

WeakRef

WeakRef est un type de pointeur intelligent qui représente une référence faible, qui fait référence à un objet qui peut être accessible ou non. Un WeakRef objet peut être utilisé uniquement par Windows Runtime, et non par COM classique.

Un objet WeakRef représente généralement un objet dont l'existence est contrôlée par un thread ou une application externe. Par exemple, un objet WeakRef peut faire référence à un objet fichier. Lorsque le fichier est ouvert, WeakRef est valide et le fichier référencé est accessible. En revanche, quand le fichier est fermé, WeakRef est incorrect et le fichier n'est pas accessible.

API clés par catégorie
Met en surbrillance les principaux types, fonctions et macros de bibliothèque de modèles Windows Runtime C++.

Référence
Contient des informations de référence pour la bibliothèque de modèles C++ Windows Runtime.

Aide-mémoire (C++/CX)
Décrit brièvement les fonctionnalités C++/CX qui prennent en charge Windows Runtime.

Utilisation des composants Windows Runtime dans Visual C++
Montre comment utiliser C++/CX pour créer un composant Windows Runtime de base.