从 C++/CX 移动到 C++/WinRT

项目
07/13/2023

本主题是系列文章中的第一篇，介绍如何将 C++/CX 项目中的源代码移植到 C++/WinRT 中的等效项。

如果你的项目还使用 Windows 运行时 C++ 模板库 (WRL) 类型，请参阅从 WRL 迁移到 C++/WinRT。

移植策略

值得注意的是，从 C++/CX 到 C++/WinRT 的移植通常很简单，但从并行模式库 (PPL) 任务迁移到协同程序的情况例外。其模型不同。从 PPL 任务到协同程序没有自然的一对一映射，也没有适用于所有情况的机械移植代码的简单方法。有关移植的这一特定方面的帮助信息，以及在这两个模型之间进行互操作的选项，请参阅实现 C++/WinRT 与 C++/CX 之间的异步和互操作。

开发团队通常会报告说，一旦克服了移植异步代码的障碍，其余的移植工作大部分是机械式的。

一次性移植

如果你能够一次性移植整个项目，那么只需要阅读本主题即可获取所需的信息（无需阅读本主题后面的互操作主题）。建议首先使用 C++/WinRT 项目模板之一在 Visual Studio 中创建一个新项目（请参阅 Visual Studio 对 C++/WinRT 的支持）。然后将源代码文件移入该新项目，与此同时，将所有 C++/CX 源代码移植到 C++/WinRT 中。

或者，如果你希望在现有的 C++/CX 项目中进行移植工作，则需要向其添加 C++/WinRT 支持。采用 C++/CX 项目并添加 C++/WinRT 支持中介绍了执行此操作的步骤。完成移植之时，便已将原来的纯 C++/CX 项目变成了纯 C++/WinRT 项目。

注意

如果你有 Windows 运行时组件项目，则一次性移植是你唯一的选项。用 C++ 编写的 Windows 运行时组件项目包含的要么全部是 C++/CX 源代码，要么全部是 C++/WinRT 源代码。它们不能在此项目类型中共存。

逐步移植项目

除了前面部分中提到的 Windows 运行时组件项目以外，如果代码库的大小或复杂性使得有必要逐步移植项目，则需要一个移植过程，在此过程中的某段时间，C++/CX 和 C++/WinRT 代码将在同一项目中并存。除了阅读本主题，还应参阅实现 C++/WinRT 与 C++/CX 之间的互操作和实现 C++/WinRT 与 C++/CX 之间的异步和互操作。这些主题提供了一些信息和代码示例，演示如何在这两种语言投影之间进行互操作。

若要使项目为逐步移植过程做好准备，一种选择是向 C++/CX 项目添加 C++/WinRT 支持。采用 C++/CX 项目并添加 C++/WinRT 支持中介绍了执行此操作的步骤。然后，你就可以从这里逐步进行移植。

另一种选择是使用 C++/WinRT 项目模板之一在 Visual Studio 中创建一个新项目（请参阅 Visual Studio 对 C++/WinRT 的支持）。然后向该项目添加 C++/CX 支持。采用 C++/WinRT 项目并添加 C++/CX 支持中介绍了执行此操作的步骤。然后，你可以开始将源代码移入其中，与此同时，将一些 C++/CX 源代码移植到 C++/WinRT 中。

无论是哪种情况，都需要在 C++/WinRT 代码与尚未移植的任何 C++/CX 代码之间进行互操作（双向）。

注意

C++/CX 和 Windows SDK 都在根命名空间 Windows 中声明类型。投影到 C++/WinRT 的 Windows 类型具有与 Windows 类型相同的完全限定名称，但放置于 C++ winrt 命名空间中。这些不同的命名空间可让你按照自己的节奏从 C++/CX 移植到 C++/WinRT。

逐步移植 XAML 项目

重要

对于使用 XAML 的项目，无论何时，均要求所有 XAML 页面类型要么完全是 C++/CX，要么完全是 C++/WinRT。你仍可以在同一项目中 XAML 页面类型以外的位置（在模型和视图模型中以及其他位置）混合使用 C++/CX 和 C++/WinRT。

对于这种情况，我们建议的工作流是创建一个新的 C++/WinRT 项目并从 C++/CX 项目复制源代码和标记。只要所有 XAML 页面类型都是 C++/WinRT，就可以使用“项目”>“添加新项...”>“Visual C++”>“空白页(C++/WinRT)”来添加新 XAML 页面。

或者，可以在移植 XAML C++/CX 项目时使用 Windows 运行时组件 (WRC) 从中提出代码。

可以创建一个新的 C++/CX WRC 项目，将尽可能多的 C++/CX 代码移入该项目，然后将 XAML 项目更改为 C++/WinRT。
或者，可以创建一个新的 C++/WinRT WRC 项目，将 XAML 项目保留为 C++/CX，然后开始将 C++/CX 移植到 C++/WinRT，将所得到的代码移出 XAML 项目并移入组件项目。
还可以让 C++/CX 组件项目以及 C++/WinRT 组件项目处于同一个解决方案中，从应用程序项目引用两者，然后逐渐从一个项目移植到另一个项目。同样，请参阅实现 C++/WinRT 与 C++/CX 之间的互操作，了解有关在同一个项目中使用这两种语言投影的更多详细信息。

将 C++/CX 项目移植到 C++/WinRT 的第一步

无论使用哪种移植策略（一次性移植或逐步移植），第一步都是准备要移植的项目。下面回顾了移植策略中所述的内容，其中涉及你将要开始使用的项目类型以及如何对其进行设置。

一次性移植。使用 C++/WinRT 项目模板之一在 Visual Studio 中创建一个新项目。将文件从 C++/CX 项目移入该新项目，然后移植 C++/CX 源代码。
逐步移植非 XAML 项目。可以选择向 C++/CX 项目添加 C++/WinRT 支持（请参阅采用 C++/CX 项目并添加 C++/WinRT 支持），然后逐步进行移植。也可以选择创建一个新的 C++/WinRT 项目并向其添加 C++/CX 支持（请参阅采用 C++/WinRT 项目并添加 C++/CX 支持），移入文件并逐步进行移植。
逐步移植 XAML 项目。创建一个新的 C++/WinRT 项目，移入文件并逐步进行移植。无论何时，均要求 XAML 页面类型要么完全是 C++/WinRT，要么完全是 C++/CX。

无论选择哪种移植策略，本主题的其余部分均适用。它包含将源代码从 C++/CX 移植到 C++/WinRT 所涉及的技术细节的目录。如果要进行逐步移植，则可能还需要查看实现 C++/WinRT 与 C++/CX 之间的互操作和实现 C++/WinRT 与 C++/CX 之间的异步和互操作。

文件命名约定

XAML 标记文件

文件原始格式	C++/CX	C++/WinRT
开发人员 XAML 文件	MyPage.xaml MyPage.xaml.h MyPage.xaml.cpp	MyPage.xaml MyPage.h MyPage.cpp MyPage.idl（见下）
生成的 XAML 文件	MyPage.xaml.g.h MyPage.xaml.g.hpp	MyPage.xaml.g.h MyPage.xaml.g.hpp MyPage.g.h

请注意，C++/WinRT 会从 *.h 和 *.cpp 文件名中删除 .xaml。

C++/WinRT 添加了一个额外的开发人员文件，即 Midl 文件 (.idl) 。 C++/CX 在内部自动生成此文件，并将其添加到每个公开的和受保护的成员。在 C++/WinRT 中，你自行创作并添加此文件。如需更多详细信息、代码示例以及 IDL 创作演练，请参阅 XAML 控件；绑定到 C++/WinRT 属性。

另请参阅将运行时类重构到 Midl 文件 (.idl) 中

运行时类

C++/CX 不对头文件的名称施加限制；通常会将多个运行时类定义置于单个头文件中，小型类尤其如此。但是，C++/WinRT 要求每个运行时类将自己的头文件以类名称来命名。

C++/CX	C++/WinRT
Common.h `ref class A { ... }` `ref class B { ... }`	Common.idl `runtimeclass A { ... }` `runtimeclass B { ... }`
	A.h `namespace implements {` `struct A { ... };` `}`
	B.h `namespace implements {` `struct B { ... };` `}`

在 C++/CX 中，使用不同命名方式的头文件进行 XAML 自定义控制的做法不太常见（但仍属合法）。需根据类名来重命名这些头文件。

C++/CX	C++/WinRT
A.xaml `<Page x:Class="LongNameForA" ...>`	A.xaml `<Page x:Class="LongNameForA" ...>`
A.h `partial ref class LongNameForA { ... }`	LongNameForA.h `namespace implements {` `struct LongNameForA { ... };` `}`

头文件要求

C++/CX 不要求你包括任何特殊的头文件，因为它会在内部根据 .winmd 文件自动生成头文件。在 C++/CX 中，通常会对按名称使用的命名空间使用 using 指令。

using namespace Windows::Media::Playback;

String^ NameOfFirstVideoTrack(MediaPlaybackItem^ item)
{
    return item->VideoTracks->GetAt(0)->Name;
}

可以通过 using namespace Windows::Media::Playback 指令在不使用命名空间前缀的情况下编写 MediaPlaybackItem。我们还接触了 Windows.Media.Core 命名空间，因为 item->VideoTracks->GetAt(0) 返回 Windows.Media.Core.VideoTrack。但是，我们不需要在任何位置键入 VideoTrack 这个名称，因此不需要 using Windows.Media.Core 指令。

但是，C++/WinRT 要求你针对每个所使用的命名空间包括一个头文件，即使不为其命名。

#include <winrt/Windows.Media.Playback.h>
#include <winrt/Windows.Media.Core.h> // !!This is important!!

using namespace winrt;
using namespace Windows::Media::Playback;

winrt::hstring NameOfFirstVideoTrack(MediaPlaybackItem const& item)
{
    return item.VideoTracks().GetAt(0).Name();
}

另一方面，即使 MediaPlaybackItem.AudioTracksChanged 事件的类型为 TypedEventHandler<MediaPlaybackItem, Windows.Foundation.Collections.IVectorChangedEventArgs>，我们也不需包括 winrt/Windows.Foundation.Collections.h，因为并未使用该事件。

C++/WinRT 还要求你针对 XAML 标记所使用的命名空间包括相应的头文件。

<!-- MainPage.xaml -->
<Rectangle Height="400"/>

使用 Rectangle 类意味着你必须添加以下 include。

// MainPage.h
#include <winrt/Windows.UI.Xaml.Shapes.h>

如果忘记了头文件，则仍可正常编译，但会出现链接器错误，因为缺少 consume_ 类。

参数传递

编写 C++/CX 源代码时，在顶帽 (^) 引用时，你将 C++/CX 类型作为函数参数传递。

void LogPresenceRecord(PresenceRecord^ record);

在 C++/WinRT 中，对于同步函数，默认情况下应该使用 const& 参数。这将避免复制和互锁开销。但你的协同程序应使用按值传递来确保它们按值捕获，并避免生命周期问题（更多详细信息，请参阅利用 C++/WinRT 实现的并发和异步操作）。

void LogPresenceRecord(PresenceRecord const& record);
IASyncAction LogPresenceRecordAsync(PresenceRecord const record);

C++/WinRT 对象根本上是一个保留支持 Windows 运行时对象的接口指针的值。在复制 C++/WinRT 对象时，编译器复制封装的接口指针，从而递增其引用计数。副本的最终销毁涉及递减引用计数。因此，仅在必要时产生复制开销。

变量和字段引用

编写 C++/CX 源代码时，你使用顶帽 (^) 变量引用 Windows 运行时对象，使用箭头 (->) 运算符来取消引用顶帽变量。

IVectorView<User^>^ userList = User::Users;

if (userList != nullptr)
{
    for (UINT32 iUser = 0; iUser < userList->Size; ++iUser)
    ...

移植到等效 C++/WinRT 代码时，可以通过删除顶帽，并将箭头运算符 (->) 更改为点运算符 (.)，来完成大量工作。 C++/WinRT 投影类型是值，而不是指针。

IVectorView<User> userList = User::Users();

if (userList != nullptr)
{
    for (UINT32 iUser = 0; iUser < userList.Size(); ++iUser)
    ...

C++/CX 顶帽引用的默认构造函数会将它初始化为 null。下面是一个 C++/CX 代码示例，我们在其中创建一个具有正确类型，但是未初始化的变量/字段。换句话说，它最初不引用 TextBlock；我们打算在以后分配引用。

TextBlock^ textBlock;

class MyClass
{
    TextBlock^ textBlock;
};

有关 C++/WinRT 中的等效项，请参阅延迟初始化。

“属性”

C++/CX 语言扩展包括属性概念。编写 C++/CX 源代码时，你可以像访问字段那样访问属性。标准 C++ 没有属性概念，因此，在 C++/WinRT 中，你调用获取和设置函数。

在随后的示例中，XboxUserId、UserState、PresenceDeviceRecords 和 Size 全部都是属性。

从属性检索值

下面介绍如何在 C++/CX 中获取属性值。

void Sample::LogPresenceRecord(PresenceRecord^ record)
{
    auto id = record->XboxUserId;
    auto state = record->UserState;
    auto size = record->PresenceDeviceRecords->Size;
}

等效的 C++/WinRT 源代码调用与属性同名但没有参数的函数。

void Sample::LogPresenceRecord(PresenceRecord const& record)
{
    auto id = record.XboxUserId();
    auto state = record.UserState();
    auto size = record.PresenceDeviceRecords().Size();
}

请注意，PresenceDeviceRecords 函数返回其本身具有 Size 函数的 Windows 运行时对象。由于返回的对象也是 C++/WinRT 投影类型，因此我们使用点运算符调用 Size 来取消引用。

将属性设置为新值

将属性设置为新值遵循类似模式。首先，在 C++/CX 中。

record->UserState = newValue;

若要在 C++/WinRT 执行同等操作，调用与属性同名的函数，并传递参数。

record.UserState(newValue);

创建类的实例

你通过 C++/CX 对象的句柄来处理它，通常称为顶帽 (^) 引用。通过 ref new 关键字创建新对象，这反过来会调用 RoActivateInstance 来激活运行时类的新实例。

using namespace Windows::Storage::Streams;

class Sample
{
private:
    Buffer^ m_gamerPicBuffer = ref new Buffer(MAX_IMAGE_SIZE);
};

C++/WinRT 对象是一个值；因此你可以在堆栈上进行分配，或作为对象字段分配。切勿使用 ref new（或 new）来分配 C++/WinRT 对象。在后台，仍然在调用 RoActivateInstance。

using namespace winrt::Windows::Storage::Streams;

struct Sample
{
private:
    Buffer m_gamerPicBuffer{ MAX_IMAGE_SIZE };
};

如果初始化资源的成本很高，通常可以推迟资源的初始化，直到实际需要时再执行。如前所述，C++/CX 顶帽引用的默认构造函数会将它初始化为 null。

using namespace Windows::Storage::Streams;

class Sample
{
public:
    void DelayedInit()
    {
        // Allocate the actual buffer.
        m_gamerPicBuffer = ref new Buffer(MAX_IMAGE_SIZE);
    }

private:
    Buffer^ m_gamerPicBuffer;
};

移植到 C++/WinRT 的同一个代码。请注意 std::nullptr_t 构造函数的使用。有关该构造函数的详细信息，请参阅延迟初始化。

using namespace winrt::Windows::Storage::Streams;

struct Sample
{
    void DelayedInit()
    {
        // Allocate the actual buffer.
        m_gamerPicBuffer = Buffer(MAX_IMAGE_SIZE);
    }

private:
    Buffer m_gamerPicBuffer{ nullptr };
};

默认构造函数如何影响集合

C++ 集合类型使用默认构造函数，这可能导致意外的对象构造。

方案	C++/CX	C++/WinRT（不正确）	C++/WinRT（正确）
本地变量，一开始为空	`TextBox^ textBox;`	`TextBox textBox; // Creates a TextBox!`	`TextBox textBox{ nullptr };`
成员变量，一开始为空	`class C {` `TextBox^ textBox;` `};`	`class C {` `TextBox textBox; // Creates a TextBox!` `};`	`class C {` `TextBox textbox{ nullptr };` `};`
全局变量，一开始为空	`TextBox^ g_textBox;`	`TextBox g_textBox; // Creates a TextBox!`	`TextBox g_textBox{ nullptr };`
空引用的矢量	`std::vector<TextBox^> boxes(10);`	`// Creates 10 TextBox objects!` `std::vector<TextBox> boxes(10);`	`std::vector<TextBox> boxes(10, nullptr);`
在 map 中设置值	`std::map<int, TextBox^> boxes;` `boxes[2] = value;`	`std::map<int, TextBox> boxes;` `// Creates a TextBox at 2,` `// then overwrites it!` `boxes[2] = value;`	`std::map<int, TextBox> boxes;` `boxes.insert_or_assign(2, value);`
空引用的数组	`TextBox^ boxes[2];`	`// Creates 2 TextBox objects!` `TextBox boxes[2];`	`TextBox boxes[2] = { nullptr, nullptr };`
配对	`std::pair<TextBox^, String^> p;`	`// Creates a TextBox!` `std::pair<TextBox, String> p;`	`std::pair<TextBox, String> p{ nullptr, nullptr };`

有关空引用集合的详细信息

只要在 C++/CX 中有一个 Platform::Array（参见移植 Platform::Array），即可将其移植到 C++/WinRT 中的 std::vector（事实上，可以将其移植到任何邻近的容器），而不是将其作为数组保留。选择 std::vector 有多种优势。

例如，尽管存在用于创建固定大小的空引用矢量（参见上表）的速记，但没有用于创建空引用数组的速记。必须针对数组中的每个元素重复执行 nullptr。如果构造的数目太少，则会默认构造额外的。

对于矢量，可以在初始化时使用空引用填充它（如上表所示），也可以借助如下所示的代码在初始化后使用空引用填充它。

std::vector<TextBox> boxes(10); // 10 default-constructed TextBoxes.
boxes.resize(10, nullptr); // 10 empty references.

有关 std::map 示例的详细信息

std::map 的 [] 下标运算符的行为如下所示。

如果在 map 中发现此键，则返回现有值（可以将其覆盖）的引用。
如果未在 map 中发现此键，则在包含此键（在可移动的情况下已经移动）的 map 中创建新条目和默认构造的值，并返回此值（可以随后将其覆盖）的引用。

换言之，[] 运算符始终在 map 中创建一个条目。这不同于 C#、Java 和 JavaScript。

从运行时基类转换为派生类

通常有一个已知引用派生类型对象的基类引用。在 C++/CX 中，使用 dynamic_cast 将基类引用强制转换为派生类引用。 dynamic_cast 实际上只是对 QueryInterface 的隐藏调用。下面是一个典型示例：你要处理依赖属性更改事件，并且要从 DependencyObject 强制转换回拥有依赖属性的实际类型。

void BgLabelControl::OnLabelChanged(Windows::UI::Xaml::DependencyObject^ d, Windows::UI::Xaml::DependencyPropertyChangedEventArgs^ e)
{
    BgLabelControl^ theControl{ dynamic_cast<BgLabelControl^>(d) };

    if (theControl != nullptr)
    {
        // succeeded ...
    }
}

等效 C++/WinRT 代码将 dynamic_cast 替换为对 IUnknown::try_as 函数的调用，该函数会封装 QueryInterface。还可以选择改为调用 IUnknown::as，这会在未返回对所需接口（具有所请求的类型的默认接口）的查询时引发异常。下面是 C++/WinRT 代码示例。

void BgLabelControl::OnLabelChanged(Windows::UI::Xaml::DependencyObject const& d, Windows::UI::Xaml::DependencyPropertyChangedEventArgs const& e)
{
    if (BgLabelControlApp::BgLabelControl theControl{ d.try_as<BgLabelControlApp::BgLabelControl>() })
    {
        // succeeded ...
    }

    try
    {
        BgLabelControlApp::BgLabelControl theControl{ d.as<BgLabelControlApp::BgLabelControl>() };
        // succeeded ...
    }
    catch (winrt::hresult_no_interface const&)
    {
        // failed ...
    }
}

派生类

若要从运行时类派生，基类必须是可组合类。 C++/CX 不需要你执行任何特殊步骤即可将类变为可组合类，但 C++/WinRT 需要。请使用 unsealed 关键字来指示你希望将类用作基类。

unsealed runtimeclass BasePage : Windows.UI.Xaml.Controls.Page
{
    ...
}
runtimeclass DerivedPage : BasePage
{
    ...
}

在实现标头类中，在包括为派生类自动生成的标头之前，必须包括基类标头文件。否则会出现“将此类型用作表达式非法”之类的错误。

// DerivedPage.h
#include "BasePage.h"       // This comes first.
#include "DerivedPage.g.h"  // Otherwise this header file will produce an error.

namespace winrt::MyNamespace::implementation
{
    struct DerivedPage : DerivedPageT<DerivedPage>
    {
        ...
    }
}

通过代理进行事件处理

下面介绍了在 C++/CX 中处理事件的典型示例，在本例中将 lambda 函数用作代理。

auto token = myButton->Click += ref new RoutedEventHandler([=](Platform::Object^ sender, RoutedEventArgs^ args)
{
    // Handle the event.
    // Note: locals are captured by value, not reference, since this handler is delayed.
});

它是 C++/WinRT 中的等效项。

auto token = myButton().Click([=](IInspectable const& sender, RoutedEventArgs const& args)
{
    // Handle the event.
    // Note: locals are captured by value, not reference, since this handler is delayed.
});

不使用 lambda 函数，你可以选择作为自由函数或指向成员函数的指针实现代理。有关详细信息，请参阅使用 C++/WinRT 中的代理来处理事件。

如果你正在从内部使用（不是跨二进制文件）事件和代理的 C++/CX 基本代码移植，winrt::delegate 将帮助你复制 C++/WinRT 中的这个模式。另请参阅项目中的参数化委托、简单信号和回调。

撤销代理

在 C++/CX 中，使用 -= 运算符来撤销之前的事件注册。

myButton->Click -= token;

它是 C++/WinRT 中的等效项。

myButton().Click(token);

有关详细信息和选项，请参阅撤销已注册的代理。

装箱和取消装箱

C++/CX 自动将标量装箱到对象中。 C++/WinRT 要求你显式调用 winrt::box_value 函数。两种语言都要求你以显式方式取消装箱。请参阅使用 C++/WinRT 装箱和取消装箱。

在下面的表中，我们将使用这些定义。

C++/CX	C++/WinRT
`int i;`	`int i;`
`String^ s;`	`winrt::hstring s;`
`Object^ o;`	`IInspectable o;`

操作	C++/CX	C++/WinRT
装箱	`o = 1;` `o = "string";`	`o = box_value(1);` `o = box_value(L"string");`
取消装箱	`i = (int)o;` `s = (String^)o;`	`i = unbox_value<int>(o);` `s = unbox_value<winrt::hstring>(o);`

如果尝试取消值类型的 null 指针的装箱，C++/CX 和 C# 会引发异常。 C++/WinRT 将其视为编程错误，因此会崩溃。在 C++/WinRT 中，请使用 winrt::unbox_value_or 函数来处理对象类型不符合预期的情况。

方案	C++/CX	C++/WinRT
取消已知整数的装箱	`i = (int)o;`	`i = unbox_value<int>(o);`
如果 o 为 null	`Platform::NullReferenceException`	崩溃
如果 o 不是装箱的整数	`Platform::InvalidCastException`	崩溃
取消整数的装箱，在为 null 的情况下使用回退；任何其他情况则崩溃	`i = o ? (int)o : fallback;`	`i = o ? unbox_value<int>(o) : fallback;`
尽可能取消整数的装箱；在任何其他情况下使用回退	`auto box = dynamic_cast<IBox<int>^>(o);` `i = box ? box->Value : fallback;`	`i = unbox_value_or<int>(o, fallback);`

将字符串装箱和取消装箱

字符串在某些情况下是值类型，在另一些情况下是引用类型。 C++/CX 和 C++/WinRT 对待字符串的方式有所不同。

ABI 类型 HSTRING 是一个指向引用计数字符串的指针。但是，它并非派生自 IInspectable，因此从技术上来说它不是一个对象。另外，null HSTRING 表示空字符串。将并非派生自 IInspectable 的项装箱时，需将其包装到 IReference<T> 中，而 Windows 运行时会以 PropertyValue 对象的形式提供标准实现（自定义类型以 PropertyType::OtherType 形式报告）。

C++/CX 将 Windows 运行时字符串表示为引用类型，而 C++/WinRT 则将字符串投影为值类型。这意味着装箱的 null 字符串可能有不同的表示形式，具体取决于你所采用的方法。

另外，C++/CX 允许取消引用 null String^ ，在这种情况下，其行为类似于字符串 ""。

行为	C++/CX	C++/WinRT
声明	`Object^ o;` `String^ s;`	`IInspectable o;` `hstring s;`
字符串类型类别	引用类型	值类型
null HSTRING 投影方式	`(String^)nullptr`	`hstring{}`
null 和 `""` 是否相同？	是	是
null 的有效性	`s = nullptr;` `s->Length == 0`（有效）	`s = hstring{};` `s.size() == 0`（有效）
如果将 null 字符串分配给对象	`o = (String^)nullptr;` `o == nullptr`	`o = box_value(hstring{});` `o != nullptr`
如果将 `""` 分配给对象	`o = "";` `o == nullptr`	`o = box_value(hstring{L""});` `o != nullptr`

基本装箱和取消装箱。

操作	C++/CX	C++/WinRT
将字符串装箱	`o = s;` 空字符串变为 nullptr。	`o = box_value(s);` 空字符串变为非 null 对象。
取消已知字符串的装箱	`s = (String^)o;` Null 对象变为空字符串。如果不是字符串，则引发 InvalidCastException。	`s = unbox_value<hstring>(o);` Null 对象崩溃。如果不是字符串，则崩溃。
将可能的字符串取消装箱	`s = dynamic_cast<String^>(o);` Null 对象或非字符串变为空字符串。	`s = unbox_value_or<hstring>(o, fallback);` Null 或非字符串变为 fallback。空字符串被保留。

并发和异步操作

并行模式库 (PPL)（例如 concurrency::task）已更新，现在支持 C++/CX 顶帽引用。

对于 C++/WinRT，应改用协同程序和 co_await。详细信息和代码示例，请参阅利用 C++/WinRT 实现的并发和异步运算。

使用 XAML 标记中的对象

在 C++/CX 项目中，可以使用 XAML 标记中的专用成员和命名元素。但在 C++/WinRT 中，以 XAML {x:Bind} 标记扩展形式使用的所有实体必须在 IDL 中以公开方式公开。

另外，绑定到布尔值时，在 C++/CX 中会显示 true 或 false，但在 C++/WinRT 中会显示 Windows.Foundation.IReference`1<布尔值>。

有关详细信息和代码示例，请参阅使用标记中的对象。

将 C++/CX 平台类型映射到 C++/WinRT 类型

C++/CX 在平台命名空间中提供了多个数据类型。这些类型不是标准的 C++，因此只能在启用 Windows 运行时语言扩展（Visual Studio 项目属性“C/C++”>“常规”>“使用 Windows 运行时扩展”>“是(/ZW)”）的情况下使用。下表帮助你从平台类型移植到 C++/WinRT 中的等效项。完成后，由于 C++/WinRT 是标准 C++，因此你可以关闭 /ZW 选项。

C++/CX	C++/WinRT
Platform::Agile^	winrt::agile_ref
Platform::Array^	请参阅移植 Platform::Array^
Platform::Exception^	winrt::hresult_error
Platform::InvalidArgumentException^	winrt::hresult_invalid_argument
Platform::Object^	winrt::Windows::Foundation::IInspectable
Platform::String^	winrt::hstring

将 Platform::Agile^ 移植到 winrt::agile_ref

C++/CX 中的 Platform::Agile^ 类型表示可以从任何线程访问的 Windows 运行时类。 C++/WinRT 的等效项是 winrt::agile_ref。

在 C++/CX 中。

Platform::Agile<Windows::UI::Core::CoreWindow> m_window;

在 C++/WinRT 中。

winrt::agile_ref<Windows::UI::Core::CoreWindow> m_window;

移植 Platform::Array

在 C++/CX 要求使用数组的情况下，C++/WinRT 允许使用任何相邻的容器。请参阅默认构造函数如何影响集合，了解为何可以使用 std::vector。

因此，只要在 C++/CX 中有 Platform::Array^，移植选项中就会包括使用初始值设定项列表、std::array 或 std::vector 的选项。有关详细信息和代码示例，请参阅标准初始值设定项列表和标准数组和矢量。

将 Platform::Exception^ 移植到 winrt::hresult_error

当 Windows 运行时 API 返回非 S_OK HRESULT 时，Platform::Exception^ 类型在 C++/CX 中生成。 C++/WinRT 的等效项是 winrt::hresult_error。

若要移植到 C++/WinRT，将使用 Platform::Exception^ 的所有代码更改为使用 winrt::hresult_error。

在 C++/CX 中。

catch (Platform::Exception^ ex)

在 C++/WinRT 中。

catch (winrt::hresult_error const& ex)

C++/WinRT 提供这些异常类。

例外类型	基类	HRESULT
winrt::hresult_error		调用 hresult_error::to_abi
winrt::hresult_access_denied	winrt::hresult_error	E_ACCESSDENIED
winrt::hresult_canceled	winrt::hresult_error	ERROR_CANCELLED
winrt::hresult_changed_state	winrt::hresult_error	E_CHANGED_STATE
winrt::hresult_class_not_available	winrt::hresult_error	CLASS_E_CLASSNOTAVAILABLE
winrt::hresult_illegal_delegate_assignment	winrt::hresult_error	E_ILLEGAL_DELEGATE_ASSIGNMENT
winrt::hresult_illegal_method_call	winrt::hresult_error	E_ILLEGAL_METHOD_CALL
winrt::hresult_illegal_state_change	winrt::hresult_error	E_ILLEGAL_STATE_CHANGE
winrt::hresult_invalid_argument	winrt::hresult_error	E_INVALIDARG
winrt::hresult_no_interface	winrt::hresult_error	E_NOINTERFACE
winrt::hresult_not_implemented	winrt::hresult_error	E_NOTIMPL
winrt::hresult_out_of_bounds	winrt::hresult_error	E_BOUNDS
winrt::hresult_wrong_thread	winrt::hresult_error	RPC_E_WRONG_THREAD

请注意，每个类（通过 hresult_error 基类）均提供 to_abi 函数，其返回错误 HRESULT，并提供 message 函数，其返回该 HRESULT 的字符串表示形式。

下面是在 C++/CX 中抛出异常的示例。

throw ref new Platform::InvalidArgumentException(L"A valid User is required");

以及 C++/WinRT 中的等效项。

throw winrt::hresult_invalid_argument{ L"A valid User is required" };

将 Platform::Object^ 移植到 winrt::Windows::Foundation::IInspectable

与所有 C++/WinRT 类型一样，winrt::Windows::Foundation::IInspectable 属于值类型。下面介绍如何初始化类型为 null 的变量。

winrt::Windows::Foundation::IInspectable var{ nullptr };

从 Platform::String^ 移植到 winrt::hstring

Platform::String^ 等同于 Windows 运行时 HSTRING ABI 类型。对于 C++/WinRT，等效项是 winrt::hstring。但使用 C++/WinRT，你可以使用 C++ 标准库宽字符串类型（如 std::wstring）和/或宽字符串文字调用 Windows 运行时 API。有关更多详细信息和代码示例，请参阅 C++/WinRT 中的字符串处理。

通过 C++/CX，你可以访问 Platform::String::Data 属性来作为 C 样式 wchar_t* 数组检索字符串（例如，将其传递到 std::wcout）。

auto var{ titleRecord->TitleName->Data() };

使用 C++/WinRT 也一样，你可以使用 hstring::c_str 函数获取 null 结尾的 C 样式字符串版本，就像从 std::wstring 获取的一样。

auto var{ titleRecord.TitleName().c_str() };

在实现获取或返回字符串的 API 时，通常要将使用 Platform::String^ 的任何 C++/CX 代码更改为使用 winrt::hstring。

下面是获取字符串的 C++/CX API 的示例。

void LogWrapLine(Platform::String^ str);

对于 C++/WinRT，你可以像这样在 MIDL 3.0 中声明该 API。

// LogType.idl
void LogWrapLine(String str);

C++/WinRT 工具链随后将为你生成源代码，如下所示。

void LogWrapLine(winrt::hstring const& str);

ToString()

C++/CX 类型提供 Object::ToString 方法。

int i{ 2 };
auto s{ i.ToString() }; // s is a Platform::String^ with value L"2".

C++/ WinRT 不直接提供此工具，不过可以转为使用替代方法。

int i{ 2 };
auto s{ std::to_wstring(i) }; // s is a std::wstring with value L"2".

C++/WinRT 也支持 winrt::to_hstring，但仅限数目有限的一些类型。对于任何其他需要字符串化的类型，你需要添加重载。

Language	将整数字符串化	将枚举字符串化
C++/CX	`String^ result = "hello, " + intValue.ToString();`	`String^ result = "status: " + status.ToString();`
C++/WinRT	`hstring result = L"hello, " + to_hstring(intValue);`	`// must define overload (see below)` `hstring result = L"status: " + to_hstring(status);`

如果将枚举字符串化，则需提供 winrt::to_hstring 的实现。

namespace winrt
{
    hstring to_hstring(StatusEnum status)
    {
        switch (status)
        {
        case StatusEnum::Success: return L"Success";
        case StatusEnum::AccessDenied: return L"AccessDenied";
        case StatusEnum::DisabledByPolicy: return L"DisabledByPolicy";
        default: return to_hstring(static_cast<int>(status));
        }
    }
}

这些字符串化通常通过数据绑定来隐式使用。

<TextBlock>
You have <Run Text="{Binding FlowerCount}"/> flowers.
</TextBlock>
<TextBlock>
Most recent status is <Run Text="{x:Bind LatestOperation.Status}"/>.
</TextBlock>

这些绑定会对被绑定属性执行 winrt::to_hstring。至于第二个示例 (StatusEnum)，则必须提供你自己的 winrt::to_hstring 重载，否则会出现编译器错误。

字符串生成

C++/CX 和 C++/WinRT 按照标准的 std::wstringstream 来生成字符串。

操作	C++/CX	C++/WinRT
追加字符串，保留 null	`stream.print(s->Data(), s->Length);`	`stream << std::wstring_view{ s };`
追加字符串，在遇到第一个 null 时停止	`stream << s->Data();`	`stream << s.c_str();`
提取结果	`ws = stream.str();`	`ws = stream.str();`

操作	C++/CX	C++/WinRT
根据文本构造字符串	`String^ s = "hello";` `String^ s = L"hello";`	`// winrt::hstring s{ "hello" }; // Doesn't compile` `winrt::hstring s{ L"hello" };`
从 std::wstring 进行转换，保留 null	`String^ s = ref new String(ws.c_str(),` `(uint32_t)ws.size());`	`winrt::hstring s{ ws };` `s = winrt::hstring(ws);` `// s = ws; // Doesn't compile`
从 std::wstring 进行转换，在遇到第一个 null 时停止	`String^ s = ref new String(ws.c_str());`	`winrt::hstring s{ ws.c_str() };` `s = winrt::hstring(ws.c_str());` `// s = ws.c_str(); // Doesn't compile`
转换为 std::wstring，保留 null	`std::wstring ws{ s->Data(), s->Length };` `ws = std::wstring(s>Data(), s->Length);`	`std::wstring ws{ s };` `ws = s;`
转换为 std::wstring，在遇到一个 null 时停止	`std::wstring ws{ s->Data() };` `ws = s->Data();`	`std::wstring ws{ s.c_str() };` `ws = s.c_str();`
将文本传递给方法	`Method("hello");` `Method(L"hello");`	`// Method("hello"); // Doesn't compile` `Method(L"hello");`
将 std::wstring 传递给方法	`Method(ref new String(ws.c_str(),` `(uint32_t)ws.size()); // Stops on first null`	`Method(ws);` `// param::winrt::hstring accepts std::wstring_view`

通过

从 C++/CX 移动到 C++/WinRT

移植策略

一次性移植

逐步移植项目

逐步移植 XAML 项目

将 C++/CX 项目移植到 C++/WinRT 的第一步

文件命名约定

XAML 标记文件

运行时类

头文件要求

参数传递

变量和字段引用

“属性”

从属性检索值

将属性设置为新值

创建类的实例

默认构造函数如何影响集合

有关空引用集合的详细信息

有关 std::map 示例的详细信息

从运行时基类转换为派生类

派生类

通过代理进行事件处理

撤销代理

装箱和取消装箱

将字符串装箱和取消装箱

并发和异步操作

使用 XAML 标记中的对象

将 C++/CX 平台类型映射到 C++/WinRT 类型

将 Platform::Agile^ 移植到 winrt::agile_ref

移植 Platform::Array

将 Platform::Exception^ 移植到 winrt::hresult_error

将 Platform::Object^ 移植到 winrt::Windows::Foundation::IInspectable

从 Platform::String^ 移植到 winrt::hstring

ToString()

字符串生成

更多示例

重要的 API

反馈

其他资源

通过

从 C++/CX 移动到 C++/WinRT

移植策略

一次性移植

逐步移植项目

逐步移植 XAML 项目

将 C++/CX 项目移植到 C++/WinRT 的第一步

文件命名约定

XAML 标记文件

运行时类

头文件要求

参数传递

变量和字段引用

“属性”

从属性检索值

将属性设置为新值

创建类的实例

默认构造函数如何影响集合

有关空引用集合的详细信息

有关 std::map 示例的详细信息

从运行时基类转换为派生类

派生类

通过代理进行事件处理

撤销代理

装箱和取消装箱

将字符串装箱和取消装箱

并发和异步操作

使用 XAML 标记中的对象

将 C++/CX 平台类型映射到 C++/WinRT 类型

将 Platform::Agile^ 移植到 winrt::agile_ref

移植 Platform::Array

将 Platform::Exception^ 移植到 winrt::hresult_error

将 Platform::Object^ 移植到 winrt::Windows::Foundation::IInspectable

从 Platform::String^ 移植到 winrt::hstring

ToString()

字符串生成

更多示例

重要的 API

相关主题

反馈

其他资源