Windows Runtime C++ Template Library (WRL)Windows Runtime C++ Template Library (WRL)

Die C++-Vorlagenbibliothek für Windows-Runtime(WRL) ist eine Vorlagenbibliothek, die eine niederschwelligen Zugang zur Erstellung und Verwendung von Windows-Runtime-Komponenten bietet.The Windows Runtime C++ Template Library (WRL) is a template library that provides a low-level way to author and use Windows Runtime components.

Hinweis

WRL ist nun durch C++/WinRT ersetzt, eine standardmäßige c++ 17-sprach Projektion für Windows-Runtime-APIs.WRL is now superseded by C++/WinRT, a standard C++17 language projection for Windows Runtime APIs. C++/WinRT ist im Windows 10 SDK ab Version 1803 verfügbar.C++/WinRT is available in the Windows 10 SDK from version 1803 onward. C++/WinRT wird vollständig in Header Dateien implementiert und wurde entwickelt, um Ihnen erstklassigen Zugriff auf die moderne Windows-API zu ermöglichen.C++/WinRT is implemented entirely in header files, and designed to provide you with first-class access to the modern Windows API.

Mit C++/WinRT können Sie Windows-Runtime APIs mithilfe eines beliebigen Standard kompatiblen c++ 17-Compilers nutzen und erstellen.With C++/WinRT, you can both consume and author Windows Runtime APIs using any standards-compliant C++17 compiler. C++/WinRT führt in der Regel zu einer besseren Leistung und erzeugt kleinere Binärdateien als jede andere Sprachoption für die Windows-Runtime.C++/WinRT typically performs better and produces smaller binaries than any other language option for the Windows Runtime. Wir unterstützen C++/CX und WRL weiterhin, empfehlen jedoch dringend die Verwendung von C++/WinRT für neue Anwendungen.We will continue to support C++/CX and WRL, but highly recommend that new applications use C++/WinRT. Weitere Informationen finden Sie unter C++/WinRT.For more information, see C++/WinRT.

VorteileBenefits

Die Windows-Runtime C++ Vorlagen Bibliothek ermöglicht es Ihnen, Component Object Model (com)-Komponenten leichter zu implementieren und zu nutzen.The Windows Runtime C++ Template Library enables you to more easily implement and consume Component Object Model (COM) components. Er bietet Techniken zum Verwalten von Daten wie Verweis Zählung, um die Lebensdauer von Objekten zu verwalten und HRESULT-Werte zu testen, um zu bestimmen, ob ein Vorgang erfolgreich warIt provides housekeeping techniques like reference-counting to manage the lifetime of objects and testing HRESULT values to determine whether an operation succeeded or failed. Um die Windows-Runtime C++ Vorlagen Bibliothek erfolgreich verwenden zu können, müssen Sie diese Regeln und Verfahren sorgfältig befolgen.To successfully use the Windows Runtime C++ Template Library, you must carefully follow these rules and techniques.

Der C++/CX ist eine sprachbasierte sprachbasierte Methode auf hoher Ebene, um Windows-Runtime Komponenten zu verwenden.The C++/CX is a high-level, language-based way to use Windows Runtime components. Sowohl die Windows-Runtime C++ Vorlagen Bibliothek als C++auch/CX vereinfachen das Schreiben von Code für die Windows-Runtime, indem Sie automatisch Aufgaben in Ihrem Namen ausführen.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.

Die Windows-Runtime C++ Vorlagen Bibliothek und C++/CX bieten unterschiedliche Vorteile.The Windows Runtime C++ Template Library and C++/CX provide different benefits. Hier sind einige Gründe, warum Sie möglicherweise die Windows-Runtime C++ Vorlagen Bibliothek anstelle von C++/CX verwenden möchten:Here are some reasons you might want to use the Windows Runtime C++ Template Library instead of C++/CX:

  • Windows-Runtime C++ Vorlagen Bibliothek fügt der Windows-Runtime Application Binary Interface (ABI) wenig Abstraktion hinzu, sodass Sie den zugrunde liegenden Code steuern können, um Windows-Runtime APIs besser erstellen oder nutzen zu können.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++/CX stellt com HRESULT-Werte als Ausnahmen dar.C++/CX represents COM HRESULT values as exceptions. Wenn Sie eine CodeBase geerbt haben, die com verwendet, oder eine CodeBase, die keine Ausnahmen verwendet, C++ stellen Sie möglicherweise fest, dass die Windows-Runtime Vorlagen Bibliothek eine natürlichere Möglichkeit zum Arbeiten mit der Windows-Runtime ist, da Sie keine Ausnahmen verwenden müssen.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.

    Hinweis

    Die Windows-Runtime C++ Vorlagen Bibliothek verwendet HRESULT-Werte und löst keine Ausnahmen aus.The Windows Runtime C++ Template Library uses HRESULT values and does not throw exceptions. Außerdem verwendet die Windows-Runtime C++ Vorlagen Bibliothek intelligente Zeiger und das RAII-Muster, um sicherzustellen, dass Objekte ordnungsgemäß zerstört werden, wenn der Anwendungscode eine Ausnahme auslöst.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. Weitere Informationen zu intelligenten Zeigern und RAII finden Sie unter intelligente Zeiger und Objekt eigene Ressourcen (RAII).For more info about smart pointers and RAII, see Smart Pointers and Objects Own Resources (RAII).

  • Der Zweck und das Design der Windows-Runtime C++ Vorlagen Bibliothek sind von der Active Template Library (ATL) inspiriert, bei der es sich um eine Reihe von C++ Vorlagen basierten Klassen handelt, die die Programmierung von COM-Objekten vereinfachen.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. Da Windows-Runtime C++ Vorlagen Bibliothek Standard C++ verwendet, um die Windows-Runtime zu umschließen, können Sie viele vorhandene COM-Komponenten, die in ATL geschrieben sind, leichter in den Windows-Runtime portieren und damit interagieren.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. Wenn Sie ATL bereits kennen, werden Sie möglicherweise fest C++ stellen, dass die Programmierung Windows-Runtime Vorlagen Bibliothek einfacher ist.If you already know ATL, you might find that Windows Runtime C++ Template Library programming is easier.

Erste SchritteGetting Started

Hier finden Sie einige Ressourcen, mit denen Sie sofort mit der Windows-Runtime C++ Vorlagen Bibliothek arbeiten können.Here are some resources that can help you get working with the Windows Runtime C++ Template Library right away.

Die Windows-Runtime-Bibliothek (WRL)The Windows Runtime Library (WRL)
In diesem Channel 9-Video erfahren Sie mehr darüber, wie C++ die Windows-Runtime Vorlagen Bibliothek Ihnen hilft, universelle Windows-Plattform (UWP)-apps zu schreiben und Windows-Runtime Komponenten zu erstellen und zu nutzen.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.

Vorgehensweise: Aktivieren und Verwenden einer Windows-Runtime KomponenteHow to: Activate and Use a Windows Runtime Component
Zeigt, wie die Windows-Runtime C++ Vorlagen Bibliothek verwendet wird, um die Windows-Runtime zu initialisieren und eine Windows-Runtime Komponente zu aktivieren und zu verwenden.Shows how to use the Windows Runtime C++ Template Library to initialize the Windows Runtime and activate and use a Windows Runtime component.

Vorgehensweise: vervollständigen von asynchronen VorgängenHow to: Complete Asynchronous Operations
Zeigt, wie die Windows-Runtime C++ Vorlagen Bibliothek verwendet wird, um asynchrone Vorgänge zu starten und Aufgaben auszuführen, wenn der Vorgang beendet wird.Shows how to use the Windows Runtime C++ Template Library to start asynchronous operations and perform work when the operations complete.

Gewusst wie: Behandeln von EreignissenHow to: Handle Events
Zeigt, wie die Windows-Runtime C++ Vorlagen Bibliothek verwendet wird, um die Ereignisse eines Windows-Runtime Objekts zu abonnieren und zu behandeln.Shows how to use the Windows Runtime C++ Template Library to subscribe to and handle the events of a Windows Runtime object.

Exemplarische Vorgehensweise: Erstellen einer UWP-App mithilfe von WRL und Media FoundationWalkthrough: Creating a UWP app using WRL and Media Foundation
Erfahren Sie, wie Sie eine UWP-app erstellen, die Microsoft Media Foundationverwendet.Learn how to create a UWP app that uses Microsoft Media Foundation.

Gewusst wie: Erstellen einer klassischen COM-KomponenteHow to: Create a Classic COM Component
Zeigt, wie die Windows-Runtime C++ Vorlagen Bibliothek zum Erstellen einer grundlegenden COM-Komponente und eine einfache Methode zum Registrieren und Verwenden der COM-Komponente aus einer Desktop-App verwendet wird.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.

Vorgehensweise: Direktes Instanziieren von WRL-KomponentenHow to: Instantiate WRL Components Directly
Erfahren Sie, wie Sie mit den Funktionen Microsoft::WRL::Make und Microsoft::WRL::Details::MakeAndInitialize eine Komponente aus dem Modul instanziieren, das sie definiert.Learn how to use the Microsoft::WRL::Make and Microsoft::WRL::Details::MakeAndInitialize functions to instantiate a component from the module that defines it.

Vorgehensweise: Verwenden von winmdidl.exe und midlrt.exe zum Erstellen von .h-Dateien aus Windows-MetadatenHow to: Use winmdidl.exe and midlrt.exe to create .h files from windows metadata
Zeigt, wie benutzerdefinierte Komponenten für Windows-Runtime von WRL durch Erstellen einer IDL-Datei von den WINMD-Metadaten verarbeitet werden.Shows how to consume custom Windows Runtime components from WRL by creating an IDL file from the .winmd metadata.

Exemplarische Vorgehensweise: Verbinden von Verwendungsaufgaben und XML-HTTP-AnforderungenWalkthrough: Connecting Using Tasks and XML HTTP Requests
Zeigt, wie die IXMLHTTPRequest2 -und IXMLHTTPRequest2Callback -Schnittstellen in Verbindung mit Aufgaben verwendet werden, um HTTP Get-und Post-Anforderungen an einen Webdienst in einer UWP-APP zu senden.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.

Beispiel für den Reise-Optimierer von Beispiel KartenBing Maps Trip Optimizer sample
Verwendet die HttpRequest Klasse, die in Exemplarische Vorgehensweise : Herstellen einer Verbindung mithilfe von Aufgaben und XML-HTTP-Anforderungen im Kontext einer kompletten UWP-App definiert ist.Uses the HttpRequest class that's defined in Walkthrough: Connecting Using Tasks and XML HTTP Requests in the context of a complete UWP app.

Erstellen einer Windows-Runtime DLL-Komponente C++ mit SampleCreating a Windows Runtime DLL component with C++ sample
Zeigt, wie Sie mithilfe der C++ Windows-Runtime Vorlagen Bibliothek eine Prozess interne dll-Komponente erstellen und Sie aus C++/CX, JavaScript und C#nutzen können.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#.

DirectX Marble Maze-SpielbeispielDirectX marble maze game sample
Veranschaulicht, wie die Windows-Runtime C++ Vorlagen Bibliothek verwendet wird, um die Lebensdauer von COM-Komponenten wie DirectX und Media Foundation im Kontext eines kompletten 3D-Spiels zu verwalten.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.

Beispiel für das Senden von Popup Benachrichtigungen aus Desktop-AppsSending toast notifications from desktop apps sample
Veranschaulicht, wie die Windows-Runtime C++ Vorlagen Bibliothek verwendet wird, um mit Popup Benachrichtigungen aus einer Desktop-App zu arbeiten.Demonstrates how to use the Windows Runtime C++ Template Library to work with toast notifications from a desktop app.

Windows-Runtime C++ Vorlagen Bibliothek im Vergleich zu ATLWindows Runtime C++ Template Library Compared to ATL

Windows-Runtime C++ Vorlagen Bibliothek ähnelt der Active Template Library (ATL), da Sie Sie zum Erstellen kleiner, schneller COM-Objekte verwenden können.Windows Runtime C++ Template Library resembles the Active Template Library (ATL) because you can use it to create small, fast COM objects. Windows-Runtime C++ Vorlagen Bibliothek und ATL teilen sich auch Konzepte wie die Definition von Objekten in Modulen, die explizite Registrierung von Schnittstellen und die offene Erstellung von Objekten mithilfe von Factorys.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. Wenn Sie mit ATL vertraut C++ sind, können Sie mit Windows-Runtime Vorlagen Bibliothek vertraut sein.You might be comfortable with Windows Runtime C++ Template Library if you're familiar with ATL.

Windows-Runtime C++ Vorlagen Bibliothek unterstützt die für UWP-apps erforderliche com-Funktionalität.Windows Runtime C++ Template Library supports the COM functionality that is required for UWP apps. Daher unterscheidet sie sich von ATL, da die direkte Unterstützung für COM-Funktionen wie Folgende fehlt:Therefore, it differs from the ATL because it omits direct support for COM features such as:

  • Aggregationaggregation

  • vordefinierte Implementierungenstock implementations

  • duale Schnittstellen (IDispatch)dual interfaces (IDispatch)

  • Standardenumeratorschnittstellenstandard enumerator interfaces

  • Verbindungspunkteconnection points

  • abtrennbare Schnittstellentear-off interfaces

  • OLE-EinbettungOLE embedding

  • ActiveX-SteuerelementeActiveX controls

  • COM+COM+

KonzepteConcepts

Windows-Runtime C++ Vorlagen Bibliothek stellt Typen bereit, die einige grundlegende Konzepte darstellen.Windows Runtime C++ Template Library provides types that represent a few basic concepts. Im folgenden Abschnitt werden diese Typen beschrieben.The following sections describe those types.

ComPtrComPtr

ComPtr ist ein Typ des intelligenten Zeigermechanismus , der die Schnittstelle darstellt, die vom Vorlagenparameter angegeben wird.ComPtr is a smart pointer type that represents the interface that's specified by the template parameter. Mit ComPtr deklarieren Sie eine Variable, die auf die Member eines Objekts zugreifen kann, das von der Schnittstelle abgeleitet wird.Use ComPtr to declare a variable that can access the members of an object that's derived from the interface. ComPtr verwaltet automatisch einen Verweiszähler für den zugrunde liegenden Schnittstellenzeiger und gibt die Schnittstelle frei, wenn der Verweiszähler auf null geht.ComPtr automatically maintains a reference count for the underlying interface pointer and releases the interface when the reference count goes to zero.

RuntimeClassRuntimeClass

RuntimeClass stellt eine instanziierte Klasse dar, die einen Satz angegebener Schnittstellen erbt.RuntimeClass represents an instantiated class that inherits a set of specified interfaces. Ein RuntimeClass-Objekt kann eine Kombination der Unterstützung für eine oder mehrere Windows-Runtime com-Schnittstellen oder einen schwachen Verweis auf eine Komponente bereitstellen.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 stellt eine Auflistung von zugehörigen Objekten dar.Module represents a collection of related objects. Ein Module -Objekt verwaltet Klassenfactorys, die Objekte erstellen, und die Registrierung, die anderen Anwendungen die Verwendung eines Objekts ermöglicht.A Module object manages class factories, which create objects, and registration, which enables other applications to use an object.

RückrufCallback

Die Rückruf -Funktion erstellt ein Objekt, dessen Memberfunktion ein Ereignishandler ist (eine Rückrufmethode).The Callback function creates an object whose member function is an event handler (a callback method). Mit der Callback -Funktion schreiben Sie asynchrone Operationen.Use the Callback function to write asynchronous operations.

EventSourceEventSource

MitEventSource verwalten Sie Delegat -Ereignishandler.EventSource is used to manage delegate event handlers. Verwenden Sie C++ Windows-Runtime Vorlagen Bibliothek zum Implementieren eines Delegaten, und verwenden Sie EventSource, um Delegaten hinzuzufügen, zu entfernen und aufzurufen.Use Windows Runtime C++ Template Library to implement a delegate, and use EventSource to add, remove, and invoke delegates.

AsyncBaseAsyncBase

Asyncbase stellt virtuelle Methoden bereit, die das Windows-Runtime asynchrone Programmiermodell darstellen.AsyncBase provides virtual methods that represent the Windows Runtime asynchronous programming model. Überschreiben Sie die Member in dieser Klasse, um eine benutzerdefinierte Klasse zu erstellen, die einen asynchronen Vorgang starten, beenden oder seinen Fortschritt überprüfen kann.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 stellt ein Freethread-Marshaller-Objekt dar.FtmBase represents a free-threaded marshaler object. FtmBase erstellt eine globale Schnittstellentabelle (GIT) und hilft bei der Verwaltung von Marshalling- und Proxyobjekten.FtmBase creates a global interface table (GIT), and helps manage marshaling and proxy objects.

WeakRefWeakRef

WeakRef ist ein Typ des intelligenten Zeigermechanismus, der einen schwachen Verweisauf ein Objekt darstellt, das möglicherweise zugänglich ist.WeakRef is a smart-pointer type that represents a weak reference, which references an object that might or might not be accessible. Ein WeakRef-Objekt kann nur von der Windows-Runtime und nicht vom klassischen com verwendet werden.A WeakRef object can be used by only the Windows Runtime, and not by classic COM.

Ein WeakRef -Objekt stellt in der Regel ein Objekt dar, dessen Vorhandensein von einem externen Thread oder einer externen Anwendung gesteuert wird.A WeakRef object typically represents an object whose existence is controlled by an external thread or application. Beispielsweise kann ein WeakRef -Objekt auf ein Dateiobjekt verweisen.For example, a WeakRef object can reference a file object. Wenn die Datei geöffnet ist, so ist WeakRef gültig, und die referenzierte Datei ist zugänglich.When the file is open, the WeakRef is valid and the referenced file is accessible. Wenn die Datei hingegen geschlossen ist, so ist WeakRef ungültig, und die Datei ist nicht zugänglich.But when the file is closed, the WeakRef is invalid and the file is not accessible.

Schlüssel-APIs nach KategorieKey APIs by Category Hebt die primären Windows-Runtime C++ Vorlagen Bibliothekstypen,-Funktionen und-Makros hervor.Highlights the primary Windows Runtime C++ Template Library types, functions, and macros.
VerweisReference Enthält Referenzinformationen für die Windows-Runtime C++ Vorlagen Bibliothek.Contains reference information for the Windows Runtime C++ Template Library.
Kurzreferenz (C++-CX)Quick Reference (C++/CX) Beschreibt kurz die C++/CX-Funktionen, die die Windows-Runtime unterstützen.Briefly describes the C++/CX features that support the Windows Runtime.
Verwenden von Windows-Runtime Komponenten in VisualC++Using Windows Runtime Components in Visual C++ Zeigt, wie/CX C++verwendet wird, um eine grundlegende Windows-Runtime-Komponente zu erstellen.Shows how to use C++/CX to create a basic Windows Runtime component.