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

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.The Windows Runtime C++ Template Library (WRL) is a template library that provides a low-level way to author and use Windows Runtime components.

Note

WRL est désormais remplacée par C / c++ / WinRT, une standard C ++ 17 projection de langage pour Windows Runtime APIs.WRL is now superceded by C++/WinRT, a standard C++17 language projection for Windows Runtime APIs. C++ / c++ / WinRT est disponible dans le SDK Windows 10 à partir de la version 1803 qui interviennent.C++/WinRT is available in the Windows 10 SDK from version 1803 onward. C++ / c++ / WinRT est entièrement implémentée dans les fichiers d’en-tête et conçu pour vous permettre d’accès idéal à l’API Windows moderne.C++/WinRT is implemented entirely in header files, and designed to provide you with first-class access to the modern Windows API.

Avec C / c++ / WinRT, vous pouvez consommer et créer le Windows Runtime APIs à l’aide de n’importe quel conformes aux normes C ++ 17 du compilateur.With C++/WinRT, you can both consume and author Windows Runtime APIs using any standards-compliant C++17 compiler. C++ / c++ / WinRT généralement plus performant et produit des binaires plus petits que toute autre option de langage pour le Windows Runtime.C++/WinRT typically performs better and produces smaller binaries than any other language option for the Windows Runtime. Nous continuerons à prendre en charge de C++ / c++ / CX et WRL, mais vous recommandons vivement que les nouvelles applications utiliser C++ / c++ / WinRT.We will continue to support C++/CX and WRL, but highly recommend that new applications use C++/WinRT. Pour plus d’informations, consultez C++ / c++ / WinRT.For more information, see C++/WinRT.

AvantagesBenefits

La bibliothèque de modèles Windows Runtime C++ vous permet plus facilement implémenter et consommer des composants de composant COM (Object Model).The Windows Runtime C++ Template Library enables you to more easily implement and consume Component Object Model (COM) components. Il fournit des techniques de gestion interne comme comptage de références pour gérer la durée de vie des objets et de tester des valeurs HRESULT pour déterminer si une opération a réussi ou échoué.It provides housekeeping techniques like reference-counting to manage the lifetime of objects and testing HRESULT values to determine whether an operation succeeded or failed. Pour pouvoir utiliser la bibliothèque de modèles Windows Runtime C++, vous devez respecter soigneusement ces règles et techniques.To successfully use the Windows Runtime C++ Template Library, you must carefully follow these rules and techniques.

C++ / c++ / CX est un moyen de haut niveau, en fonction de langage à utiliser des composants Windows Runtime.The C++/CX is a high-level, language-based way to use Windows Runtime components. À la fois la bibliothèque de modèles Windows Runtime C++ et C++ / c++ / CX simplifient l’écriture de code pour le Windows Runtime en exécutant automatiquement les tâches de gestion interne à votre place.Both the Windows Runtime C++ Template Library and C++/CX simplify the writing of code for the Windows Runtime by automatically performing housekeeping tasks on your behalf.

La bibliothèque de modèles Windows Runtime C++ et C / c++ / CX offrent des avantages différents.The Windows Runtime C++ Template Library and C++/CX provide different benefits. Voici quelques raisons pour lesquelles vous souhaiterez peut-être utiliser la bibliothèque de modèles Windows Runtime C++ au lieu de C++ / c++ / CX :Here are some reasons you might want to use the Windows Runtime C++ Template Library instead of C++/CX:

  • Bibliothèque de modèles Windows Runtime C++ ajoute peu d’abstraction sur le Windows Runtime binaire Interface Application (ABI), ce qui vous donne la possibilité de contrôler le code sous-jacent pour mieux créer ou consommer Windows APIs Runtime.Windows Runtime C++ Template Library adds little abstraction over the Windows Runtime Application Binary Interface (ABI), giving you the ability to control the underlying code to better create or consume Windows Runtime APIs.

  • C++ / c++ / CX représente les valeurs HRESULT de COM en tant qu’exceptions.C++/CX represents COM HRESULT values as exceptions. Si vous avez hérité d’une base de code qui utilise COM, ou qui n’utilise pas les exceptions, vous constaterez peut-être que la bibliothèque de modèles C++ Windows Runtime est une façon plus naturelle pour travailler avec le Runtime de Windows, car vous n’êtes pas obligé d’utiliser des exceptions.If you’ve inherited a code base that uses COM, or one that doesn’t use exceptions, you might find that the Windows Runtime C++ Template Library is a more natural way to work with the Windows Runtime because you don't have to use exceptions.

    Note

    La bibliothèque de modèles Windows Runtime C++ utilise les valeurs HRESULT et ne lève pas d’exceptions.The Windows Runtime C++ Template Library uses HRESULT values and does not throw exceptions. En outre, la bibliothèque de modèles Windows Runtime C++ utilise des pointeurs intelligents et le modèle RAII pour contribuer à garantir que les objets sont détruits correctement lorsque votre code d’application lève une exception.In addition, the Windows Runtime C++ Template Library uses smart pointers and the RAII pattern to help guarantee that objects are destroyed correctly when your application code throws an exception. Pour plus d’informations sur les pointeurs intelligents et le modèle RAII, consultez pointeurs intelligents et ressources propre des objets (RAII).For more info about smart pointers and RAII, see Smart Pointers and Objects Own Resources (RAII).

  • L’objectif et la conception de la bibliothèque de modèles C++ Windows Runtime est inspirée par la bibliothèque ATL (Active Template), qui est un ensemble de classes C++ basées sur modèle qui simplifie la programmation d’objets COM.The purpose and design of the Windows Runtime C++ Template Library is inspired by the Active Template Library (ATL), which is a set of template-based C++ classes that simplify the programming of COM objects. Étant donné que la bibliothèque de modèles Windows Runtime C++ utilise C++ standard pour encapsuler le Runtime de Windows, vous pouvez plus facilement le port et interagir avec de nombreux composants COM existants écrits en ATL à l’exécution de Windows.Because Windows Runtime C++ Template Library uses standard C++ to wrap the Windows Runtime, you can more easily port and interact with many existing COM components written in ATL to the Windows Runtime. Si vous connaissez déjà ATL, vous constaterez peut-être que la programmation de la bibliothèque de modèles C++ Windows Runtime est plus facile.If you already know ATL, you might find that Windows Runtime C++ Template Library programming is easier.

Prise en mainGetting Started

Voici quelques ressources qui peuvent vous aider à commencer à travailler avec la bibliothèque de modèles Windows Runtime C++ tout de suite.Here are some resources that can help you get working with the Windows Runtime C++ Template Library right away.

Le Windows Runtime Library (WRL)The Windows Runtime Library (WRL)
Dans cette vidéo de Channel 9, en savoir plus sur comment la bibliothèque de modèles Windows Runtime C++ vous aide à que écrire des applications Universal Windows Platform (UWP) et comment créer et consommer des composants Windows Runtime.In this Channel 9 video, learn more about how the Windows Runtime C++ Template Library helps you write Universal Windows Platform (UWP) apps and how to author and consume Windows Runtime components.

Comment : activer et utiliser un composant d’exécution de WindowsHow to: Activate and Use a Windows Runtime Component
Montre comment utiliser la bibliothèque de modèles Windows Runtime C++ pour initialiser le Runtime Windows et activer et utiliser un composant Windows Runtime.Shows how to use the Windows Runtime C++ Template Library to initialize the Windows Runtime and activate and use a Windows Runtime component.

Comment : effectuer des opérations asynchronesHow to: Complete Asynchronous Operations
Montre comment utiliser la bibliothèque de modèles Windows Runtime C++ pour démarrer des opérations asynchrones et effectuer des actions lorsque les opérations se terminent.Shows how to use the Windows Runtime C++ Template Library to start asynchronous operations and perform work when the operations complete.

Comment : gérer les événementsHow to: Handle Events
Montre comment utiliser la bibliothèque de modèles Windows Runtime C++ pour vous abonner à et gérer les événements d’un objet Windows Runtime.Shows how to use the Windows Runtime C++ Template Library to subscribe to and handle the events of a Windows Runtime object.

Procédure pas à pas : création d’une application UWP à l’aide de WRL et Media FoundationWalkthrough: Creating a UWP app using WRL and Media Foundation
Découvrez comment créer une application UWP qui utilise Microsoft Media Foundation.Learn how to create a UWP app that uses Microsoft Media Foundation.

Comment : créer un composant COM classiqueHow to: Create a Classic COM Component
Montre comment utiliser la bibliothèque de modèles Windows Runtime C++ pour créer un composant COM de base et une méthode simple pour vous inscrire et utiliser le composant COM à partir d’une application de bureau.Shows how to use the Windows Runtime C++ Template Library to create a basic COM component and a basic way to register and consume the COM component from a desktop app.

Guide pratique pour instancier directement les composants WRLHow to: Instantiate WRL Components Directly
Découvrez comment utiliser le Microsoft::wrl :: Make et Microsoft::WRL::Details::MakeAndInitialize pour instancier un composant à partir du module qui le définit.Learn how to use the Microsoft::WRL::Make and Microsoft::WRL::Details::MakeAndInitialize functions to instantiate a component from the module that defines it.

Guide pratique pour utiliser winmdidl.exe et midlrt.exe pour créer les fichiers .h à partir des métadonnées WindowsHow to: Use winmdidl.exe and midlrt.exe to create .h files from windows metadata
Montre comment consommer des composants Windows Runtime personnalisées à partir de WRL en créant un fichier IDL à partir des métadonnées .winmd.Shows how to consume custom Windows Runtime components from WRL by creating an IDL file from the .winmd metadata.

Procédure pas à pas : connexion à l’aide de tâches et de requêtes HTTP XMLWalkthrough: Connecting Using Tasks and XML HTTP Requests
Montre comment utiliser le IXMLHTTPRequest2 et IXMLHTTPRequest2Callback interfaces avec des tâches pour envoyer des demandes HTTP GET et POST à un service web dans une application UWP.Shows how to use the IXMLHTTPRequest2 and IXMLHTTPRequest2Callback interfaces together with tasks to send HTTP GET and POST requests to a web service in a UWP app.

Exemple optimiseur de voyage Bing MapsBing Maps Trip Optimizer sample
Utilise le HttpRequest classe qui est définie dans procédure pas à pas : connexion à l’aide de tâches et les requêtes HTTP XML dans le contexte d’une application UWP complète.Uses the HttpRequest class that's defined in Walkthrough: Connecting Using Tasks and XML HTTP Requests in the context of a complete UWP app.

Création d’un composant Windows DLL d’exécution avec l’exemple C++Creating a Windows Runtime DLL component with C++ sample
Montre comment utiliser la bibliothèque de modèles Windows Runtime C++ pour créer un composant DLL in-process et le consommer à partir de C++ / c++ / CX, JavaScript et c#.Shows how to use the Windows Runtime C++ Template Library to create an in-process DLL component and consume it from C++/CX, JavaScript, and C#.

Exemple de jeu marble maze DirectXDirectX marble maze game sample
Montre comment utiliser la bibliothèque de modèles C++ Windows Runtime 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.Demonstrates how to use the Windows Runtime C++ Template Library to manage the lifetime of COM components such as DirectX and Media Foundation in the context of a complete 3-D game.

Envoi de notifications toast à partir d’exemples d’applications de bureauSending toast notifications from desktop apps sample
Montre comment utiliser la bibliothèque de modèles Windows Runtime C++ pour travailler avec des notifications de toast à partir d’une application de bureau.Demonstrates how to use the Windows Runtime C++ Template Library to work with toast notifications from a desktop app.

Windows Runtime bibliothèque de modèles C++ comparé à ATLWindows Runtime C++ Template Library Compared to ATL

Bibliothèque de modèles Windows Runtime C++ ressemble à la bibliothèque ATL (Active Template), car vous pouvez l’utiliser pour créer des objets COM rapides de petites.Windows Runtime C++ Template Library resembles the Active Template Library (ATL) because you can use it to create small, fast COM objects. Bibliothèque de modèles Windows Runtime C++ et ATL partagent également des concepts tels que la définition d’objets dans des modules, l’inscription explicite d’interfaces et la création d’objets à l’aide de fabriques.Windows Runtime C++ Template Library and ATL also share concepts such as definition of objects in modules, explicit registration of interfaces, and open creation of objects by using factories. Vous pouvez être à l’aise avec la bibliothèque de modèles Windows Runtime C++ si vous êtes familiarisé avec ATL.You might be comfortable with Windows Runtime C++ Template Library if you're familiar with ATL.

Bibliothèque de modèles Windows Runtime C++ prend en charge la fonctionnalité COM requise pour les applications UWP.Windows Runtime C++ Template Library supports the COM functionality that is required for UWP apps. 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 :Therefore, it differs from the ATL because it omits direct support for COM features such as:

  • agrégation ;aggregation

  • implémentations stock ;stock implementations

  • interfaces doubles (IDispatch) ;dual interfaces (IDispatch)

  • interfaces d'énumérateur standard ;standard enumerator interfaces

  • points de connexion ;connection points

  • interfaces détachables ;tear-off interfaces

  • incorporation OLE ;OLE embedding

  • contrôles ActiveX ;ActiveX controls

  • COM+.COM+

ConceptsConcepts

Bibliothèque de modèles Windows Runtime C++ fournit des types représentant quelques concepts de base.Windows Runtime C++ Template Library provides types that represent a few basic concepts. Les sections suivantes décrivent ces types.The following sections describe those types.

ComPtrComPtr

ComPtr est un pointeur intelligent type qui représente l’interface spécifiée par le paramètre de modèle.ComPtr is a smart pointer type that represents the interface that's specified by the template parameter. Utilisez ComPtr pour déclarer une variable pouvant accéder aux membres d'un objet dérivé de l'interface.Use ComPtr to declare a variable that can access the members of an object that's derived from the 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.ComPtr automatically maintains a reference count for the underlying interface pointer and releases the interface when the reference count goes to zero.

RuntimeClassRuntimeClass

RuntimeClass représente une classe instanciée qui hérite d’un ensemble d’interfaces spécifiées.RuntimeClass represents an instantiated class that inherits a set of specified interfaces. Un RuntimeClass objet peut fournir une combinaison de prise en charge pour une ou plusieurs interfaces Windows Runtime COM, ou une référence faible à un composant.A RuntimeClass object can provide a combination of support for one or more Windows Runtime COM interfaces, or a weak reference to a component.

ModuleModule

Module représente une collection d’objets connexes.Module represents a collection of related objects. 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.A Module object manages class factories, which create objects, and registration, which enables other applications to use an object.

RappelCallback

Le rappel fonction crée un objet dont la fonction membre est un gestionnaire d’événements (une méthode de rappel).The Callback function creates an object whose member function is an event handler (a callback method). Utilisez la fonction Callback pour écrire des opérations asynchrones.Use the Callback function to write asynchronous operations.

EventSourceEventSource

EventSource sert à gérer déléguer gestionnaires d’événements.EventSource is used to manage delegate event handlers. Utiliser la bibliothèque de modèles Windows Runtime C++ pour implémenter un délégué et utilisez EventSource pour ajouter, supprimer et appeler des délégués.Use Windows Runtime C++ Template Library to implement a delegate, and use EventSource to add, remove, and invoke delegates.

AsyncBaseAsyncBase

AsyncBase fournit des méthodes virtuelles qui représentent le modèle de programmation asynchrone Windows Runtime.AsyncBase provides virtual methods that represent the Windows Runtime asynchronous programming model. 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.Override the members in this class to create a custom class that can start, stop, or check the progress of an asynchronous operation.

FtmBaseFtmBase

FtmBase représente un objet marshaler libre de threads.FtmBase represents a free-threaded marshaler object. FtmBase crée un tableau global d'interface (GIT) et vous permet de gérer le marshaling et les objets proxy.FtmBase creates a global interface table (GIT), and helps manage marshaling and proxy objects.

WeakRefWeakRef

WeakRef est un type pointeur intelligent qui représente un référence faible, qui fait référence à un objet qui peut ou ne peut pas accessible.WeakRef is a smart-pointer type that represents a weak reference, which references an object that might or might not be accessible. Un WeakRef objet peut être utilisé uniquement par le Windows Runtime et non par le COM classique.A WeakRef object can be used by only the Windows Runtime, and not by classic COM.

Un objet WeakRef représente généralement un objet dont l'existence est contrôlée par un thread ou une application externe.A WeakRef object typically represents an object whose existence is controlled by an external thread or application. Par exemple, un objet WeakRef peut faire référence à un objet fichier.For example, a WeakRef object can reference a file object. Lorsque le fichier est ouvert, WeakRef est valide et le fichier référencé est accessible.When the file is open, the WeakRef is valid and the referenced file is accessible. En revanche, quand le fichier est fermé, WeakRef est incorrect et le fichier n'est pas accessible.But when the file is closed, the WeakRef is invalid and the file is not accessible.

API principales par catégorieKey APIs by Category Met en évidence la principale bibliothèque de modèles Windows Runtime C++ types, fonctions et les macros.Highlights the primary Windows Runtime C++ Template Library types, functions, and macros.
RéférenceReference Contient des informations de référence pour la bibliothèque de modèles C++ Windows Runtime.Contains reference information for the Windows Runtime C++ Template Library.
Référence rapide (Windows Runtime et Visual C++)Quick Reference (Windows Runtime and Visual C++) Décrit brièvement le C + c++ / fonctionnalités CX qui prennent en charge l’exécution de Windows.Briefly describes the C++/CX features that support the Windows Runtime.
À l’aide de composants Windows Runtime en Visual C++Using Windows Runtime Components in Visual C++ Montre comment utiliser C++ / c++ / CX pour créer un composant Windows Runtime de base.Shows how to use C++/CX to create a basic Windows Runtime component.