Windows Runtime C++ Template Library (WRL)

The Windows Runtime C++ Template Library (WRL) is a template library that provides a low-level way to author and use Windows Runtime components.

Benefits

The WRL enables you to more easily implement and consume Component Object Model (COM) components. 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. To successfully use the WRL, you must carefully follow these rules and techniques.

The Visual C++ component extensions (C++/CX) is a high-level, language-based way to use Windows Runtime components. Both the WRL and C++/CX simplify the writing of code for the Windows Runtime by automatically performing housekeeping tasks on your behalf.

The WRL and C++/CX provide different benefits. Here are some reasons you might want to use the WRL instead of C++/CX:

• WRL 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 represents COM HRESULT values as exceptions. If you’ve inherited a code base that uses COM, or one that doesn’t use exceptions, you might find that the WRL is a more natural way to work with the Windows Runtime because you don't have to use exceptions.

  Note

  The WRL uses HRESULT values and does not throw exceptions. In addition, the WRL uses smart pointers and the RAII pattern to help guarantee that objects are destroyed correctly when your application code throws an exception. For more info about smart pointers and RAII, see Smart Pointers (Modern C++) and Objects Own Resources (RAII).

• The purpose and design of the WRL is inspired by the Active Template Library (ATL), which is a set of template-based C++ classes that simplify the programming of COM objects. Because WRL 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. If you already know ATL, you might find that WRL programming is easier.

Getting Started

Here are some resources that can help you get working with the WRL right away.

• The Windows Runtime Library (WRL)
  In this Channel 9 video, learn more about how the WRL helps you write Windows Store apps and how to author and consume Windows Runtime components.

• How to: Activate and Use a Windows Runtime Component Using WRL
  Shows how to use the WRL to initialize the Windows Runtime and activate and use a Windows Runtime component.

• How to: Complete Asynchronous Operations Using WRL
  Shows how to use the WRL to start asynchronous operations and perform work when the operations complete.

• How to: Handle Events Using WRL
  Shows how to use the WRL to subscribe to and handle the events of a Windows Runtime object.

• Walkthrough: Creating a Basic Windows Runtime Component Using WRL
  Shows how to use the WRL to create a basic Windows Runtime component that adds two numbers. Also demonstrates how to raise events and use the component from a Windows Store app that uses JavaScript.

• Walkthrough: Creating a Windows Store app using WRL and Media Foundation
  Learn how to create a Windows Store app that uses Microsoft Media Foundation.

• How to: Create a Classic COM Component Using WRL
  Shows how to use the WRL to create a basic COM component and a basic way to register and consume the COM component from a desktop app.

• How to: Instantiate WRL Components Directly
  Learn how to use the Microsoft::WRL::Make and Microsoft::WRL::Details::MakeAndInitialize functions to instantiate a component from the module that defines it.

• How to: Use winmdidl.exe and midlrt.exe to create .h files from windows metadata
  Shows how to consume custom Windows Runtime components from WRL by creating an IDL file from the .winmd metadata.

• Walkthrough: Connecting Using Tasks and XML HTTP Requests
  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 Windows Store app.

• Bing Maps Trip Optimizer sample
  Uses the HttpRequest class that's defined in Walkthrough: Connecting Using Tasks and XML HTTP Requests in the context of a complete Windows Store app.

• Creating a Windows Runtime DLL component with C++ sample
  Shows how to use the WRL to create an in-process DLL component and consume it from C++/CX, JavaScript, and C#.

• DirectX marble maze game sample
  Demonstrates how to use the WRL to manage the lifetime of COM components such as DirectX and Media Foundation in the context of a complete 3-D game.

• Sending toast notifications from desktop apps sample
  Demonstrates how to use the WRL to work with toast notifications from a desktop app.

WRL Compared to ATL

WRL resembles the Active Template Library (ATL) because you can use it to create small, fast COM objects. WRL and ATL also share concepts such as definition of objects in modules, explicit registration of interfaces, and open creation of objects by using factories. You might be comfortable with WRL if you're familiar with ATL.

WRL supports the COM functionality that is required for Windows Store apps. Therefore, it differs from the ATL because it omits direct support for COM features such as:

• aggregation

• stock implementations

• dual interfaces (IDispatch)

• standard enumerator interfaces

• connection points

• tear-off interfaces

• OLE embedding

• ActiveX controls

• COM+

Concepts

WRL provides types that represent a few basic concepts. The following sections describe those types.

ComPtr

ComPtr is a smart pointer type that represents the interface that's specified by the template parameter. Use ComPtr to declare a variable that can access the members of an object that's derived from the interface. ComPtr automatically maintains a reference count for the underlying interface pointer and releases the interface when the reference count goes to zero.

RuntimeClass

RuntimeClass represents an instantiated class that inherits a set of specified interfaces. A RuntimeClass object can provide a combination of support for one or more Windows Runtime COM interfaces, or a weak reference to a component.

Module

Module represents a collection of related objects. A Module object manages class factories, which create objects, and registration, which enables other applications to use an object.

Callback

The Callback function creates an object whose member function is an event handler (a callback method). Use the Callback function to write asynchronous operations.

EventSource

EventSource is used to manage delegate event handlers. Use WRL to implement a delegate, and use EventSource to add, remove, and invoke delegates.

AsyncBase

AsyncBase provides virtual methods that represent the Windows Runtime asynchronous programming model. Override the members in this class to create a custom class that can start, stop, or check the progress of an asynchronous operation.

FtmBase

FtmBase represents a free-threaded marshaler object. FtmBase creates a global interface table (GIT), and helps manage marshaling and proxy objects.

WeakRef

WeakRef is a smart-pointer type that represents a weak reference, which references an object that might or might not be accessible. A WeakRef object can be used by only the Windows Runtime, and not by classic COM.

A WeakRef object typically represents an object whose existence is controlled by an external thread or application. For example, a WeakRef object can reference a file object. When the file is open, the WeakRef is valid and the referenced file is accessible. But when the file is closed, the WeakRef is invalid and the file is not accessible.

Related Topics

WRL Class Library Project Template	Describes how to access the WRL Class Library project template. This template helps simplify the task of using Visual Studio to create Windows Runtime components.
Key WRL APIs by Category	Highlights the primary WRL types, functions, and macros.
WRL Reference	Contains reference information for the WRL.
Quick Reference (Windows Runtime and Visual C++)	Briefly describes the C++/CX features that support the Windows Runtime.
Using Windows Runtime Components in Visual C++	Shows how to use C++/CX to create a basic Windows Runtime component.