从 C# 移动到 C++/WinRT

本主题全面编录了 将 C# 项目中的源代码移植到其等效 C ++/WinRT 中所涉及的技术详细信息。

有关移植其中一个通用 Windows 平台 (UWP)应用示例的案例研究，请参阅从 C# 将剪贴板示例移植到 C++/WinRT 的配套主题。 你可以通过跟着该演练指南一步步操作，并在过程中亲自移植该示例，来获得移植方面的实践和经验。

如何准备，以及预期内容

案例研究 将剪贴板示例从 C# 移植到 C++/WinRT 说明了在将项目移植到 C++/WinRT 时你将需要作出哪些软件设计决策的实例。 因此，最好通过深入了解现有代码的工作原理来准备移植。 这样，你将大致了解应用的功能和代码的结构，然后做出的决策将始终引导你前进，并按正确的方向前进。

在移植更改的预期类型方面，可以将这些更改分组为四个类别。

• 移植语言投影。 Windows 运行时（WinRT）被映射到多种编程语言中。 这些语言投影中的每一种，都是为了让其在对应的编程语言中显得自然且符合其惯用表达方式而设计的。 对于 C# 而言，某些 Windows 运行时 类型会投影为 .NET 类型。 例如，你将把 System.Collections.Generic.IReadOnlyList<T> 翻译回 Windows.Foundation.Collections.IVectorView<T>。 此外，在 C# 中，一些 Windows 运行时 操作被映射为便捷的 C# 语言功能。 例如，在 C# 中，使用 += 运算符语法注册事件处理委托。 因此，你需要将类似这样的语言特性还原为其背后正在执行的底层操作（例如，此处为事件注册）。
• 端口语言语法。 其中许多更改都是简单的机械转换，替换了一个符号。 例如，将点 （.） 更改为双冒号 （::）。
• 端口语言过程。 其中一些可能是简单、重复的更改（例如myObject.MyPropertymyObject.MyProperty()）。 其他人需要更深入的更改（例如，将涉及 使用 System.Text.StringBuilder 的过程移植到涉及 使用 std：：wostringstream 的过程）。
• C++/WinRT 特有的移植相关任务 Windows 运行时的某些细节在后台由 C# 隐式处理。 这些详细信息在 C++/WinRT 中显式完成。 例如，使用 .idl 文件定义运行时类。

在后面的基于任务的索引之后，本主题的其余部分根据上述分类进行结构化。

根据所执行的任务查找内容

涉及语言映射的更改

注册/撤销事件处理程序

在 C++/WinRT 中，可以使用多种语法选项来注册/撤销事件处理程序委托，如 在 C++/WinRT 中使用委托处理事件中所述。 另请参阅 移植 EnableClipboardContentChangedNotifications 方法。

有时，例如，当事件接收方（处理事件的对象）即将被销毁时，需要撤销事件处理程序，以便引发事件的事件源（引发事件的对象）不会调用销毁的对象。 请参阅 撤销已注册的委托。 在这种情况下，请为事件处理程序创建 event_token 成员变量。 有关示例，请参阅 移植 EnableClipboardContentChangedNotifications 方法。

还可以在 XAML 标记中注册事件处理程序。

<Button x:Name="OpenButton" Click="OpenButton_Click" />

在 C# 中，OpenButton_Click方法可以是私有方法，XAML 仍能够将其连接到 OpenButton 引发的 ButtonBase.Click 事件。

在 C++/WinRT 中，如果要在 XAML 标记中注册 OpenButton_Click 方法，则它在你的 实现类型 中必须为 public。 如果仅在命令性代码中注册事件处理程序，则事件处理程序不需要是公共的。

namespace winrt::MyProject::implementation
{
    struct MyPage : MyPageT<MyPage>
    {
        void OpenButton_Click(
            winrt::Windows::Foundation::IInspectable const& sender,
            winrt::Microsoft::UI::Xaml::RoutedEventArgs const& args);
    }
};

或者，可以将注册 XAML 页面设为实现类型的友元，并将 OpenButton_Click 设为私有。

namespace winrt::MyProject::implementation
{
    struct MyPage : MyPageT<MyPage>
    {
    private:
        friend MyPageT;
        void OpenButton_Click(
            winrt::Windows::Foundation::IInspectable const& sender,
            winrt::Microsoft::UI::Xaml::RoutedEventArgs const& args);
    }
};

最后一种情况是，你正在移植的 C# 项目在标记中绑定到事件处理程序（有关该情况的更多背景信息，请参阅 x:Bind 中的函数）。

<Button x:Name="OpenButton" Click="{x:Bind OpenButton_Click}" />

只需将标记更改为更简单 Click="OpenButton_Click"。 或者，如果愿意，可以保留该标记。 要支持它，你只需在 IDL 中声明该事件处理器。

void OpenButton_Click(Object sender, Microsoft.UI.Xaml.RoutedEventArgs e);

涉及语言语法的更改

移植类和成员

你需要决定，对于每个 C# 类型，是将其移植为 Windows 运行时 类型，还是移植为普通的 C++ 类、结构或枚举。 有关详细信息，以及演示如何做出这些决策的详细示例，请参阅 将剪贴板示例从 C# 移植到 C++/WinRT。

C# 属性通常会转换为访问器函数、修改器函数和后备数据成员。 有关详细信息和示例，请参阅 移植 IsClipboardContentChangedEnabled 属性。

对于非静态字段，将它们设为 实现类型的数据成员。

C# 静态字段会变为 C++/WinRT 中的静态访问器和/或设值器函数。 有关详细信息和示例，请参阅 移植构造函数、 当前和 FEATURE_NAME。

对于成员函数，同样，你需要对每一个成员函数判断它是否应在 IDL 中定义，还是应作为你的实现类型的公有成员函数或私有成员函数。 有关详细信息以及如何决定的示例，请参阅 MainPage 类型的 IDL。

移植 XAML 标记和资源文件

在将 剪贴板示例从 C# 移植到 C++/WinRT 的情况下， 我们能够跨 C # 和 C++/WinRT 项目使用相同的 XAML 标记（包括资源）和资产文件。 在某些情况下，必须对标记进行编辑才能实现此目的。 请参阅复制完成 MainPage 移植所需的 XAML 和样式。

涉及语言内部流程的变更

以下各节详细介绍了表中的某些项。

UI 元素构造

这些代码示例演示 XAML 页面命令性代码中 UI 元素的构造。

var myTextBlock = new TextBlock()
{
    Text = "Text",
    Style = (Microsoft.UI.Xaml.Style)this.Resources["MyTextBlockStyle"]
};

TextBlock myTextBlock;
myTextBlock.Text(L"Text");
myTextBlock.Style(
    winrt::unbox_value<Microsoft::UI::Xaml::Style>(
        Resources().Lookup(
            winrt::box_value(L"MyTextBlockStyle")
        )
    )
);

ToString（）

C# 类型提供 Object.ToString 方法。

int i = 2;
var s = i.ToString(); // s is a System.String with value "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。 你需要为任何想要转换为字符串的其他类型添加重载。

如果要将枚举转换为字符串，则需要提供 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 提供你自己的重载版本，否则会出现编译器错误。

另请参阅 移植 Footer_Click 方法。

构建字符串

对于字符串生成，C# 具有内置的 StringBuilder 类型。

另请参阅 移植 BuildClipboardFormatsOutputString 方法，以及 移植 DisplayChangedFormats 方法。

在主 UI 线程上运行代码

此示例取自 条形码扫描仪示例。

如果要在 C# 项目中的主 UI 线程上执行工作，通常使用 DispatcherQueue.TryEnqueue 方法（或 UWP 中的较旧的 CoreDispatcher.RunAsync ）。 下面是 C# 中的模式。

private async void Watcher_Added(DeviceWatcher sender, DeviceInformation args)
{
    DispatcherQueue.TryEnqueue(() =>
    {
        // Do work on the main UI thread here.
    });
}

在 C++/WinRT 中表达这一点要简单得多。 请注意，我们以值传递方式接收参数，这是基于这样一种假设：我们将需要在第一个挂起点之后（在本例中即 co_await）访问这些参数。 有关详细信息，请参阅 参数传递。

winrt::fire_and_forget Watcher_Added(DeviceWatcher sender, winrt::DeviceInformation args)
{
    co_await DispatcherQueue();
    // Do work on the main UI thread here.
}

如果需要以默认值以外的优先级执行工作，请参阅 winrt：：resume_foreground 函数，该函数具有具有优先级的重载。 有关演示如何等待 winrt：：resume_foreground 调用的代码示例，请参阅 使用线程相关性进行编程。

C++/WinRT 特有的移植相关任务

在 IDL 中定义运行时类

请参阅 MainPage 类型的 IDL，并合并您的.idl文件。

包括所需的 C++/WinRT Windows命名空间头文件

在 C++/WinRT 中，每当想要从Windows命名空间中使用类型时，都需要包含相应的 C++/WinRT Windows命名空间头文件。 有关示例，请参阅 移植 NotifyUser 方法。

装箱和取消装箱

C# 会自动将标量值装箱为对象。 C++/WinRT 要求显式调用 winrt：：box_value 函数。 这两种语言都要求你显式拆箱。 请参阅 C++/WinRT 中的装箱和拆箱。

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

如果尝试将空指针拆箱为值类型，C++/CX 和 C# 会引发异常。 C++/WinRT 将此视为编程错误，并且它崩溃。 在 C++/WinRT 中，如果要处理对象不是你认为的类型的情况，请使用 winrt：：unbox_value_or 函数。

有关示例，请参阅 移植 OnNavigatedTo 方法，以及 移植 Footer_Click 方法。

字符串的装箱和拆箱

字符串在某些方面是值类型，在其他方面是引用类型。 C# 和 C++/WinRT 以不同的方式对待字符串。

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

C# 将Windows 运行时字符串表示为引用类型;而 C++/WinRT 将字符串投影为值类型。 这意味着，装箱后的 null 字符串可能会有不同的表示形式，具体取决于你是通过哪种方式得到它的。

基本装箱和拆箱。

使类可供 {Binding} 标记扩展使用

如果打算使用 {Binding} 标记扩展将数据绑定到数据类型，请参阅 使用 {Binding} 声明的 Binding 对象。

在 XAML 标记中使用对象

在 C# 项目中，可以访问 XAML 标记中的私有成员和命名元素。 但在 C++/WinRT 中，使用 XAML {x：Bind} 标记扩展 使用的所有实体都必须在 IDL 中公开。

此外，在 C# 中，绑定到布尔值时会显示 true 或 false，而在 C++/WinRT 中则会显示 Windows.Foundation.IReference`1<Boolean>。

有关更多信息和代码示例，请参阅 从标记中使用对象。

使数据源可用于 XAML 标记

在 C++/WinRT 版本 2.0.190530.8 或更高版本中，winrt::single_threaded_observable_vector 创建一个同时支持 IObservableVector<T> 和 IObservableVector<IInspectable> 的可观测向量。 有关示例，请参阅 移植 Scenarios 属性。

可以像这样创作 Midl 文件（.idl） （另请参阅 将运行时类分解为 Midl 文件 （.idl） 。

namespace Bookstore
{
    runtimeclass BookSku { ... }

    runtimeclass BookstoreViewModel
    {
        Windows.Foundation.Collections.IObservableVector<BookSku> BookSkus{ get; };
    }

    runtimeclass MainPage : Microsoft.UI.Xaml.Controls.Page
    {
        MainPage();
        BookstoreViewModel MainViewModel{ get; };
    }
}

并按如下方式实现。

// BookstoreViewModel.h
...
struct BookstoreViewModel : BookstoreViewModelT<BookstoreViewModel>
{
    BookstoreViewModel()
    {
        m_bookSkus = winrt::single_threaded_observable_vector<Bookstore::BookSku>();
        m_bookSkus.Append(winrt::make<Bookstore::implementation::BookSku>(L"To Kill A Mockingbird"));
    }
    
	Windows::Foundation::Collections::IObservableVector<Bookstore::BookSku> BookSkus();
    {
        return m_bookSkus;
    }

private:
    Windows::Foundation::Collections::IObservableVector<Bookstore::BookSku> m_bookSkus;
};
...

有关详细信息，请参阅 XAML 项控件;绑定到 C++/WinRT 集合以及 使用 C++/WinRT 的集合。

使数据源可用于 XAML 标记（C++/WinRT 2.0.190530.8 之前）

XAML 数据绑定要求项源实现 IIterable<IInspectable>，以及以下接口组合之一。

• IObservableVector<IInspectable>
• IBindableVector 和 INotifyCollectionChanged
• IBindableVector 和 IBindableObservableVector
• IBindableVector 本身（无法响应更改）
• IVector<IInspectable>
• IBindableIterable（将迭代元素并将其保存到私有集合中）

在运行时无法检测到泛型接口（如 IVector<T> ）。 每个 IVector<T> 具有不同的接口标识符（IID），这是 T 的函数。任何开发人员都可以任意扩展 T 集，因此很明显，XAML 绑定代码永远不知道要查询的完整集。 对于 C# 来说，这种限制不是问题，因为实现 IEnumerable<T> 的每个 CLR 对象都会自动实现 IEnumerable。 在 ABI 级别，这意味着实现 IObservableVector<T> 的每个对象都会自动实现 IObservableVector<IInspectable>。

C++/WinRT 不提供该保证。 如果 C++/WinRT 运行时类实现了 IObservableVector<T>，那么我们并不能假定它也同时提供了 IObservableVector<IInspectable> 的实现。

因此，上一个示例应如下所示。

...
runtimeclass BookstoreViewModel
{
    // This is really an observable vector of BookSku.
    Windows.Foundation.Collections.IObservableVector<Object> BookSkus{ get; };
}

以及实现。

// BookstoreViewModel.h
...
struct BookstoreViewModel : BookstoreViewModelT<BookstoreViewModel>
{
    BookstoreViewModel()
    {
        m_bookSkus = winrt::single_threaded_observable_vector<Windows::Foundation::IInspectable>();
        m_bookSkus.Append(winrt::make<Bookstore::implementation::BookSku>(L"To Kill A Mockingbird"));
    }
    
    // This is really an observable vector of BookSku.
	Windows::Foundation::Collections::IObservableVector<Windows::Foundation::IInspectable> BookSkus();
    {
        return m_bookSkus;
    }

private:
    Windows::Foundation::Collections::IObservableVector<Windows::Foundation::IInspectable> m_bookSkus;
};
...

如果需要访问 m_bookSkus 中的对象，则需要将它们重新 QI 为 Bookstore::BookSku。

Widget MyPage::BookstoreViewModel(winrt::hstring title)
{
    for (auto&& obj : m_bookSkus)
    {
        auto bookSku = obj.as<Bookstore::BookSku>();
        if (bookSku.Title() == title) return bookSku;
    }
    return nullptr;
}

派生类

若要从运行时类派生，基类必须 可组合。 C# 不要求你执行任何特殊步骤，使类可组合，但 C++/WinRT 会这样做。 你可以使用 unsealed 关键字 来表明你希望类可以用作基类。

unsealed runtimeclass BasePage : Microsoft.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>
    {
        ...
    }
}

重要 API

• winrt 命名空间

相关主题

• C# 教程
• C++/WinRT
• 深入的数据绑定