從 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.MyProperty 變更為 myObject.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 方法」，則該方法在實作類型中必須是公用的。 如果您只在命令式程式碼中註冊事件處理常式，則事件處理常式不需要是公用的。

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

最後一個案例是您要移植的 C# 專案從標記繫結到事件處理常式 (如需更多案例背景，請參閱 Functions in x:Bind)。

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

您可以將該標記變更為更簡單的 Click="OpenButton_Click"。 或者，如果想要的話，也可以保留該標記不變。 為了加以支援，您只需要在 IDL 中宣告事件處理常式。

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

涉及語言語法的變更

移植類別與成員

針對每個 C# 類型，您都必須決定要將其移植到 Windows 執行階段類型，還是一般 C++ 類別/結構/列舉。 如需詳細資訊，以及說明如何做出這些決策的詳細範例，請參閱將剪貼簿範例從 C# 移植到 C++/WinRT。

C# 屬性通常會成為存取子函式、更動子函式和支援資料成員。 如需詳細資訊和範例，請參閱移植 IsClipboardContentChangedEnabled 屬性。

對於非靜態欄位，請將其設為 實作類型的資料成員。

C# 靜態欄位會成為 C++/WinRT 靜態存取子和 (或) 更動子涵式。 如需詳細資訊和範例，請參閱移植建構函式 Current 和 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 = (Windows.UI.Xaml.Style)this.Resources["MyTextBlockStyle"]
};

TextBlock myTextBlock;
myTextBlock.Text(L"Text");
myTextBlock.Style(
    winrt::unbox_value<Windows::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 執行緒上執行作業時，通常會使用 CoreDispatcher.RunAsync 方法，如下所示。

private async void Watcher_Added(DeviceWatcher sender, DeviceInformation args)
{
    await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
    {
        // 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 Dispatcher();
    // Do work on the main UI thread here.
}

如果您需要以預設值以外的優先順序來執行工作，請參閱 winrt::resume_foreground 函式，其有採用 priority 的多載。 如需示範如何等候對 winrt::resume_foreground 呼叫的程式碼範例，請參閱考量使用執行緒親和性程式設計。

C++/WinRT 特定的移植相關工作

定義 IDL 中的執行階段類別

請參閱 MainPage 類型的 IDL 及合併 .idl 檔案。

包含您需要的 C++/WinRT Windows 命名空間標頭檔案

在 C++/WinRT 中，每當您要使用 Windows 命名空間的類型時，您必須包含對應的 C++/WinRT Windows 命名空間標頭檔案。 如需範例，請參閱移植 NotifyUser 方法。

Box 處理和 Unbox 處理

C# 會自動將純量 Box 處理為物件。 C++/WinRT 會要求您明確地呼叫 winrt::box_value 函式。 這兩種語言都需要您明確地進行 Unbox 處理。 請參閱使用 C++/WinRT 進行 Box 處理和 Unbox 處理。

在後續表格中，我們將使用下列定義。

如果您嘗試將 null 指標 Unbox 處理為某個實值類型，則 C++/CX 和 C# 會引發例外狀況。 C++/WinRT 會將此視為程式設計錯誤，並且毀損。 在 C++/WinRT 中，如果您想處理物件不是您所認為類型的情況，請使用 winrt::unbox_value_or 函式。

如需範例，請參閱移植 OnNavigatedTo 方法，以及移植 Footer_Click 方法。

進行字串的 Box 處理和 Unbox 處理

字串在某些方面是實值類型，而在其他方面則是參考類型。 C# 和 C++/WinRT 會以不同的方式處理字串。

ABI 類型 HSTRING 是參考計數字串的指標。 但是它並非衍生自 IInspectable，因此在技術上並不是「物件」。 此外, null HSTRING 代表空字串。 將非衍生自 IInspectable 的項目包裝在 IReference<T>內，即可完成 Box 處理，而 Windows 執行階段會以 PropertyValue 物件形式提供標準實作 (自訂類型會回報為 PropertyType::OtherType)。

C# 表示作為參考類型的 Windows 執行階段字串；而 C++/WinRT 會將字串投影為實值類型。 這表示已進行 Box 處理的 null 字串可以有不同的表示法 (取決於您達成的方式)。

基本 Box 處理和 Unbox 處理。

讓類別可供 {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 : Windows.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 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>
    {
        ...
    }
}

重要 API

• winrt 命名空間

相關主題

• C# 教學課程
• C++/WinRT
• 深入了解資料繫結