Windows 运行时 C++ 模板库 (WRL)Windows Runtime C++ Template Library (WRL)

Windows 运行时 C++ 模板库 (WRL) 是一个提供低级别方式来创作和使用 Windows 运行时组件的模板库。The Windows Runtime C++ Template Library (WRL) is a template library that provides a low-level way to author and use Windows Runtime components.

备注

WRL 现已由C++/WinRT (Windows 运行时 api 的标准 c + + 17 语言投影)取代。WRL is now superseded by C++/WinRT, a standard C++17 language projection for Windows Runtime APIs. C++/WinRT 从版本1803开始,在 Windows 10 SDK 中提供。C++/WinRT is available in the Windows 10 SDK from version 1803 onward. C++/WinRT 完全在标头文件中实现,旨在向您提供对新式 Windows API 的第一类访问。C++/WinRT is implemented entirely in header files, and designed to provide you with first-class access to the modern Windows API.

使用C++/WinRT,可以使用任何符合标准的 c + + 17 编译器来使用和创作 Windows 运行时 api。With C++/WinRT, you can both consume and author Windows Runtime APIs using any standards-compliant C++17 compiler. C++与 Windows 运行时的任何其他语言选项相比,/WinRT 通常性能更好,生成的二进制文件更小。C++/WinRT typically performs better and produces smaller binaries than any other language option for the Windows Runtime. 我们将继续支持 C++/CX 和 WRL,但强烈建议新应用程序使用 C++/WinRT。We will continue to support C++/CX and WRL, but highly recommend that new applications use C++/WinRT. 有关详细信息,请参阅 C++/WinRTFor more information, see C++/WinRT.

优点Benefits

Windows 运行时C++模板库使您能够更轻松地实现和使用组件对象模型(COM)组件。The Windows Runtime C++ Template Library enables you to more easily implement and consume Component Object Model (COM) components. 它提供了一些管理技术(如引用计数)来管理对象的生存期和测试 HRESULT 值,以确定操作是成功还是失败。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. 若要成功使用 Windows 运行时C++模板库,必须认真遵循这些规则和技术。To successfully use the Windows Runtime C++ Template Library, you must carefully follow these rules and techniques.

C++/Cx 是一种使用 Windows 运行时组件的基于语言的高级方法。The C++/CX is a high-level, language-based way to use Windows Runtime components. Windows 运行时C++模板库和C++/cx 都通过代表您自动执行自动维护任务来简化 Windows 运行时的代码编写。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.

Windows 运行时C++模板库和C++/cx 提供了不同的优点。The Windows Runtime C++ Template Library and C++/CX provide different benefits. 下面是你可能想要使用 Windows 运行时C++模板库而不是/cx 的C++一些原因:Here are some reasons you might want to use the Windows Runtime C++ Template Library instead of C++/CX:

  • Windows 运行时C++模板库在 Windows 运行时应用程序二进制接口(ABI)上添加了少量抽象,使你能够控制基础代码,以便更好地创建或使用 Windows 运行时 api。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 将 COM HRESULT 值表示为异常。C++/CX represents COM HRESULT values as exceptions. 如果继承了使用 COM 或不使用异常的基本代码,你可能会发现 Windows 运行时C++模板库是使用 Windows 运行时的更自然的方式,因为你不必使用异常。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.

    备注

    Windows 运行时C++模板库使用 HRESULT 值,不会引发异常。The Windows Runtime C++ Template Library uses HRESULT values and does not throw exceptions. 此外,Windows 运行时C++模板库使用智能指针和 RAII 模式,以帮助确保在应用程序代码引发异常时正确销毁对象。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. 有关智能指针和 RAII 的详细信息,请参阅智能指针对象资源(RAII)For more info about smart pointers and RAII, see Smart Pointers and Objects Own Resources (RAII).

  • Windows 运行时C++模板库的用途和设计是由活动模板库(ATL)的,它是一组基于C++模板的类,可简化 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. 由于 Windows 运行时C++模板库使用标准C++来包装 Windows 运行时,因此你可以更轻松地将用 ATL 编写的多个现有 COM 组件与 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. 如果你已经知道 ATL,你可能会发现 Windows 运行时C++模板库编程更容易。If you already know ATL, you might find that Windows Runtime C++ Template Library programming is easier.

入门Getting Started

下面是一些可帮助你立即开始使用 Windows 运行时C++模板库的资源。Here are some resources that can help you get working with the Windows Runtime C++ Template Library right away.

Windows 运行时库(WRL)The Windows Runtime Library (WRL)
在此第9频道视频中,详细了解 Windows 运行时C++模板库如何帮助你编写通用 WINDOWS 平台(UWP)应用,以及如何创作和使用 Windows 运行时组件。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.

如何:激活和使用 Windows 运行时组件How to: Activate and Use a Windows Runtime Component
演示如何使用 Windows 运行时C++模板库来初始化 Windows 运行时并激活和使用 Windows 运行时组件。Shows how to use the Windows Runtime C++ Template Library to initialize the Windows Runtime and activate and use a Windows Runtime component.

如何:完成异步操作How to: Complete Asynchronous Operations
演示如何使用 Windows 运行时C++模板库来启动异步操作,并在操作完成时执行工作。Shows how to use the Windows Runtime C++ Template Library to start asynchronous operations and perform work when the operations complete.

如何:处理事件How to: Handle Events
演示如何使用 Windows 运行时C++模板库来订阅和处理 Windows 运行时对象的事件。Shows how to use the Windows Runtime C++ Template Library to subscribe to and handle the events of a Windows Runtime object.

演练:使用 WRL 和媒体基础创建 UWP 应用Walkthrough: Creating a UWP app using WRL and Media Foundation
了解如何创建使用Microsoft 媒体基础的 UWP 应用。Learn how to create a UWP app that uses Microsoft Media Foundation.

如何:创建经典 COM 组件How to: Create a Classic COM Component
演示如何使用 Windows 运行时C++模板库来创建基本的 com 组件,以及从桌面应用程序注册和使用 COM 组件的基本方法。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.

如何:直接实例化 WRL 组件How to: Instantiate WRL Components Directly
了解如何使用 Microsoft::WRL::MakeMicrosoft::WRL::Details::MakeAndInitialize 函数从定义组件的模块实例化组件。Learn how to use the Microsoft::WRL::Make and Microsoft::WRL::Details::MakeAndInitialize functions to instantiate a component from the module that defines it.

如何:使用 winmdidl.exe 和 midlrt.exe 通过窗口元数据创建 .h 文件How to: Use winmdidl.exe and midlrt.exe to create .h files from windows metadata
演示如何通过从 .winmd 元数据创建 IDL 文件,使用 WRL 中的自定义 Windows 运行时组件。Shows how to consume custom Windows Runtime components from WRL by creating an IDL file from the .winmd metadata.

演练:使用任务和 XML HTTP 请求进行连接Walkthrough: Connecting Using Tasks and XML HTTP Requests
演示如何将IXMLHTTPRequest2IXMLHTTPRequest2Callback接口与任务一起使用,以将 HTTP GET 和 POST 请求发送到 UWP 应用中的 web 服务。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.

必应地图行程优化器示例Bing Maps Trip Optimizer sample
使用在演练中定义的 HttpRequest 类:在完整 UWP 应用的上下文中使用任务和 XML HTTP 请求进行连接Uses the HttpRequest class that's defined in Walkthrough: Connecting Using Tasks and XML HTTP Requests in the context of a complete UWP app.

使用C++示例创建 Windows 运行时 DLL 组件Creating a Windows Runtime DLL component with C++ sample
演示如何使用 Windows 运行时C++模板库创建进程内 DLL 组件,并从C++/cx、JavaScript 和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#.

DirectX 大理石迷宫游戏示例DirectX marble maze game sample
演示如何使用 Windows 运行时C++模板库在完整的三维游戏上下文中管理 COM 组件(例如 DirectX 和媒体基础)的生存期。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.

从桌面应用发送 toast 通知示例Sending toast notifications from desktop apps sample
演示如何使用 Windows 运行时C++模板库从桌面应用程序中使用 toast 通知。Demonstrates how to use the Windows Runtime C++ Template Library to work with toast notifications from a desktop app.

与C++ ATL 比较 Windows 运行时模板库Windows Runtime C++ Template Library Compared to ATL

Windows 运行时C++模板库类似于活动模板库(ATL),因为你可以使用它来创建小型、快速的 COM 对象。Windows Runtime C++ Template Library resembles the Active Template Library (ATL) because you can use it to create small, fast COM objects. Windows 运行时C++模板库和 ATL 还在模块中共享对象的定义、显式注册接口,以及使用工厂打开对象创建等概念。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. 如果你熟悉 ATL,你C++可能会喜欢 Windows 运行时模板库。You might be comfortable with Windows Runtime C++ Template Library if you're familiar with ATL.

Windows 运行时C++模板库支持 UWP 应用所需的 COM 功能。Windows Runtime C++ Template Library supports the COM functionality that is required for UWP apps. 因此,它又与 ATL 有所不同,因为它无法直接支持下列 COM 功能:Therefore, it differs from the ATL because it omits direct support for COM features such as:

  • 聚合aggregation

  • 常用实现stock implementations

  • 双重接口 (IDispatch)dual interfaces (IDispatch)

  • 标准枚举器接口standard enumerator interfaces

  • 连接点connection points

  • 分离式接口tear-off interfaces

  • OLE 嵌入OLE embedding

  • ActiveX 控件ActiveX controls

  • COM+COM+

概念Concepts

Windows 运行时C++模板库提供了表示几个基本概念的类型。Windows Runtime C++ Template Library provides types that represent a few basic concepts. 以下几节将介绍这些类型。The following sections describe those types.

ComPtrComPtr

ComPtr 是一种智能指针 类型,表示由模板参数指定的接口。ComPtr is a smart pointer type that represents the interface that's specified by the template parameter. 使用 ComPtr 可以声明能够访问从接口派生的对象成员的变量。Use ComPtr to declare a variable that can access the members of an object that's derived from the interface. ComPtr 会自动维护基础接口指针的引用计数,并在引用计数变为零时发布接口。ComPtr automatically maintains a reference count for the underlying interface pointer and releases the interface when the reference count goes to zero.

RuntimeClassRuntimeClass

RuntimeClass 表示继承一组指定接口的实例化类。RuntimeClass represents an instantiated class that inherits a set of specified interfaces. RuntimeClass 对象可以提供对一个或多个 Windows 运行时 COM 接口的支持或对组件的弱引用。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 represents a collection of related objects. Module 对象管理类工厂和注册。类工厂可以创建对象,注册则让其他应用程序能够使用对象。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). 使用 Callback 函数可以编写异步操作。Use the Callback function to write asynchronous operations.

EventSourceEventSource

EventSource 用于管理委托 事件处理程序。EventSource is used to manage delegate event handlers. 使用 Windows 运行时C++模板库来实现委托,并使用 EventSource 添加、移除和调用委托。Use Windows Runtime C++ Template Library to implement a delegate, and use EventSource to add, remove, and invoke delegates.

AsyncBaseAsyncBase

AsyncBase提供表示异步编程模型 Windows 运行时的虚拟方法。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.

FtmBaseFtmBase

FtmBase 表示自由线程封送拆收器对象。FtmBase represents a free-threaded marshaler object. FtmBase 可以创建全局接口表 (GIT),并帮助管理封送处理和代理对象。FtmBase creates a global interface table (GIT), and helps manage marshaling and proxy objects.

WeakRefWeakRef

WeakRef 是表示弱引用的智能指针类型。弱引用可引用能够访问或者不能访问的对象。WeakRef is a smart-pointer type that represents a weak reference, which references an object that might or might not be accessible. WeakRef 对象只能由 Windows 运行时(而不是经典 COM)使用。A WeakRef object can be used by only the Windows Runtime, and not by classic COM.

WeakRef 对象通常表示由外部线程或应用程序控制其存在性的对象。A WeakRef object typically represents an object whose existence is controlled by an external thread or application. 例如, WeakRef 对象可以引用文件对象。For example, a WeakRef object can reference a file object. 当文件打开时, WeakRef 有效,并且引用的文件可以访问。When the file is open, the WeakRef is valid and the referenced file is accessible. 当文件关闭时, WeakRef 无效,并且文件不可访问。But when the file is closed, the WeakRef is invalid and the file is not accessible.

按类别列出的密钥 ApiKey APIs by Category 突出显示主 Windows 运行时C++模板库类型、函数和宏。Highlights the primary Windows Runtime C++ Template Library types, functions, and macros.
引用Reference 包含 Windows 运行时C++模板库的参考信息。Contains reference information for the Windows Runtime C++ Template Library.
快速参考C++/cx)Quick Reference C++/CX) 简要介绍支持C++Windows 运行时的/cx 功能。Briefly describes the C++/CX features that support the Windows Runtime.
在视觉对象中使用 Windows 运行时组件C++Using Windows Runtime Components in Visual C++ 演示如何使用C++/cx 创建基本 Windows 运行时组件。Shows how to use C++/CX to create a basic Windows Runtime component.