通过

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

  • 项目

Windows 运行时 C++ 模板库 (WRL) 是一个提供低级别方式来创作和使用 Windows 运行时组件的模板库。

注意

WRL 现在已由 C++/WinRT 取代。C++/WinRT 是 Windows 运行时 API 的标准 C++17 语言投影。 从版本 1803 (10.0.17134.0) 起，C++/WinRT 在 Windows SDK 中提供。 C++/WinRT 完全在头文件中实现，旨在提供对新式 Windows API 的优先访问权限。

通过 C++/WinRT，可以使用任何符合标准的 C++17 编译器来同时使用和创作 Windows 运行时 API。 与适用于 Windows 运行时的任何其他语言选择相比，通常 C++/WinRT 的表现更好，生成的二进制文件更小。 我们将继续支持 C++/CX 和 WRL，但强烈建议新应用程序使用 C++/WinRT。 有关详细信息，请参阅 C++/WinRT。

好处

Windows 运行时 C++ 模板库使你能够更轻松地实现和使用组件对象模型 (COM) 组件。 它提供引用计数这类管理技术来管理对象的生存期，并可通过测试 HRESULT 值来确定操作是否成功。 若要成功使用 Windows 运行时 C++ 模板库，必须认真遵循这些规则和方法。

C++/CX 是一种使用 Windows 运行时组件的基于语言的高级方式。 Windows 运行时 C++ 模板库和 C++/CX 都通过代表你自动执行管护任务来简化 Windows 运行时代码的编写。

Windows 运行时 C++ 模板库和 C++/CX 提供不同的优势。 下面是你可能想要使用 Windows 运行时 C++ 模板库而不是 C++/CX 的部分原因：

  • Windows 运行时 C++ 模板库在 Windows 运行时应用程序二进制接口 (ABI) 上添加了少量的抽象，使你能够控制基础代码以更好地创建或使用 Windows 运行时 API。

  • C++/CX 将 COM HRESULT 值表示为异常。 如果你继承了使用 COM 或不使用异常的代码库，可能会发现 Windows 运行时 C++ 模板库可以更自然地与 Windows 运行时配合工作，因为你不必使用异常。

    注意

    Windows 运行时 C++ 模板库使用 HRESULT 值且不引发异常。 此外，Windows 运行时 C++ 模板库还使用智能指针和 RAII 模式，以帮助确保在应用程序代码引发异常时正确销毁对象。 有关智能指针和 RAII 的详细信息，请参阅智能指针和对象拥有资源 (RAII)。

  • Windows 运行时 C++ 模板库的用途和设计是由活动模板库 (ATL) 创作而来。活动模板库是一组基于模板的 C++ 类，可以简化编程 COM 对象。 由于 Windows 运行时 C++ 模板库使用标准 C++ 来包装 Windows 运行时，因此你可以更轻松地将许多以 ATL 编写的现有 COM 组件移植到 Windows 运行时并与之交互。 如果你已了解 ATL，可能会发现 Windows 运行时 C++ 模板库编程更容易。

入门

下面是一些可帮助你立即开始使用 Windows 运行时 C++ 模板库的资源。

如何：激活和使用 Windows 运行时组件
介绍如何使用 Windows 运行时 C++ 模板库初始化 Windows 运行时，以及如何激活和使用 Windows 运行时组件。

如何：完成异步操作
介绍如何使用 Windows 运行时 C++ 模板库启动异步操作并在操作完成时执行工作。

如何：处理事件
介绍如何使用 Windows 运行时 C++ 模板库订阅和处理 Windows 运行时对象的事件。

演练：使用 WRL 和媒体基础创建 UWP 应用
了解如何创建使用 Microsoft 媒体基础的 UWP 应用。

如何：创建经典 COM 组件
介绍如何使用 Windows 运行时 C++ 模板库创建基本的 COM 组件，以及从桌面应用程序注册和使用 COM 组件的基本方法。

如何：直接实例化 WRL 组件
了解如何使用 Microsoft::WRL::Make 和 Microsoft::WRL::Details::MakeAndInitialize 函数从定义组件的模块实例化组件。

如何：使用 winmdidl.exe 和 midlrt.exe 通过窗口元数据创建 .h 文件
演示如何通过从 .winmd 元数据创建 IDL 文件，使用 WRL 中的自定义 Windows 运行时组件。

演练：使用任务和 XML HTTP 请求进行连接
介绍如何将 IXMLHTTPRequest2 和 IXMLHTTPRequest2Callback 接口与任务结合使用，以将 HTTP GET 和 POST 请求发送到 UWP 应用中的 Web 服务。

必应地图行程优化器示例
在完整 UWP 应用的上下文中使用演练：使用任务和 XML HTTP 请求进行连接中定义的 HttpRequest 类。

使用 C++ 示例创建 Windows 运行时 DLL 组件
介绍如何使用 Windows 运行时 C++ 模板库创建进程内 DLL 组件，以及从 C++/CX、JavaScript 和 C# 中使用该组件。

DirectX Marble Maze 游戏示例
演示如何使用 Windows 运行时 C++ 模板库管理 COM 组件（比如，完整的 3D 游戏上下文中的 DirectX 和媒体基础）的生存期。

来自桌面应用的 Toast 通知。
演示如何从桌面应用发送 toast 通知。

Windows 运行时 C++ 模板库与 ATL 的比较

Windows 运行时 C++ 模板库与活动模板库 (ATL) 相似，因为前者也可用于创建快速的小型 COM 对象。 Windows 运行时 C++ 模板库和 ATL 之间还存在一些相同的概念，例如在模块中定义对象、显式注册接口，以及使用工厂开始创建对象。 如果你熟悉 ATL 的话，可能也能得心应手地使用 Windows 运行时 C++ 模板库。

Windows 运行时 C++ 模板库支持 UWP 应用所需的 COM 功能。 因此，它又与 ATL 有所不同，因为它无法直接支持下列 COM 功能：

  • aggregation (聚合)

  • 常用实现

  • 双重接口 (IDispatch)

  • 标准枚举器接口

  • 连接点

  • 分离式接口

  • OLE 嵌入

  • ActiveX 控件

  • COM+

概念

Windows 运行时 C++ 模板库提供了表示几个基本概念的类型。 以下几节将介绍这些类型。

ComPtr

ComPtr 是一种智能指针 类型，表示由模板参数指定的接口。 使用 ComPtr 可以声明能够访问从接口派生的对象成员的变量。 ComPtr 会自动维护基础接口指针的引用计数，并在引用计数变为零时发布接口。

RuntimeClass

RuntimeClass 表示继承一组指定接口的实例化类。 RuntimeClass 对象既可支持一个或多个 Windows 运行时 COM 接口，也可提供对组件的弱引用。

模块

模块 表示一组相关的对象。 Module 对象管理类工厂和注册。类工厂可以创建对象，注册则让其他应用程序能够使用对象。

回调

回调 函数可以创建对象，该对象的成员函数为事件处理程序（回调方法）。 使用 Callback 函数可以编写异步操作。

EventSource

EventSource 用于管理委托 事件处理程序。 使用 Windows 运行时 C++ 模板库可实现委托，使用 EventSource 可添加、删除和调用委托。

AsyncBase

AsyncBase 提供表示 Windows 运行时异步编程模型的虚方法。 重写此类中的成员可以创建能够启动、停止或检查异步操作进度的自定义类。

FtmBase

FtmBase 表示自由线程封送拆收器对象。 FtmBase 可以创建全局接口表 (GIT)，并帮助管理封送处理和代理对象。

WeakRef

WeakRef 是表示弱引用 的智能指针类型。弱引用可引用能够访问或者不能访问的对象。 WeakRef 对象仅可由 Windows 运行时使用，而不能由传统 COM 使用。

WeakRef 对象通常表示由外部线程或应用程序控制其存在性的对象。 例如， WeakRef 对象可以引用文件对象。 当文件打开时， WeakRef 有效，并且引用的文件可以访问。 当文件关闭时， WeakRef 无效，并且文件不可访问。

按类别列出的关键 API
重点介绍主要的 Windows 运行时 C++ 模板库类型、函数和宏。

引用
包含 Windows 运行时 C++ 模板库的参考信息。

快速参考 (C++-CX)
简要介绍支持 Windows 运行时的 C++/CX 功能。

在 Visual C++ 中使用 Windows 运行时组件
介绍如何使用 C++/CX 创建基本的 Windows 运行时组件。