C++/WinRT 簡介

發行項
10/05/2023

C++/WinRT 是完全標準現代的 Windows 執行階段 (WinRT) API 的 C++17 語言投影，僅實作為標頭檔案式程式庫，以及設計用來提供您現代化 Windows API 的第一級存取。使用 C++/WinRT，您可以撰寫及取用使用任何符合標準 C++17 編譯器的 Windows 執行階段 API。 Windows SDK 包含 C++/WinRT；其在版本 10.0.17134.0 (Windows 10，版本 1803 ) 中引進。

C++/WinRT 是 Microsoft 針對 C++/CX 語言投影和 Windows 執行階段 C++ 範本庫 (WRL) 建議的替代方案。 C++/WinRT 相關主題的完整清單包含有關與 C++/CX 和 WRL 交互操作，以及從從移植的資訊。

重要

最重要的一些 C++/WinRT 項目會在 C++/WinRT 的 SDK 支援和 C++/WinRT、XAML、VSIX 擴充功能和 NuGet 套件的 Visual Studio 支援等章節中說明。

另請參閱我可以在哪裡找到 C++/WinRT 範例應用程式？。

語言投影

Windows 執行階段根據元件物件模型 (COM) API，且設計它透過「語言投影」來存取。投影隱藏 COM 的詳細資訊，並針對特定語言提供更自然的程式設計體驗。

Windows 執行階段 API 參考內容中的 C++/WinRT 語言投影

當您在瀏覽Windows 執行階段 API，按一下右上方下拉式方塊中的 [語言]，然後選取C++/WinRT，當它們在 C++/WinRT 語言投影中顯示時，檢視 API 語法區塊。

C++/WinRT、XAML、VSIX 擴充功能和 NuGet 套件的 Visual Studio 支援

如需 Visual Studio 支援，您需要 Visual Studio 2022、Visual Studio 2019 或 Visual Studio 2017 (至少 15.6 版；我們建議至少 15.7 版)。從 Visual Studio 安裝程式中，安裝通用 Windows 平台開發工作負載。在 [安裝詳細資料]>[通用 Windows 平台開發] 中，勾選 [C++ (v14x) 通用 Windows 平台工具] 選項 (如果尚未勾選)。並且，在 Windows [設定]>[隱私權和安全性] (Windows 10：[更新與安全性]) >[開發人員專用]，啟用 [開發人員模式] 選項 (Windows 10：不是 [側載應用程式] 選項)。

雖然我們建議您使用最新版本的 Visual Studio 和 Windows SDK 進行開發，但如果您使用的是在 10.0.17763.0 (Windows 10 版本 1809) 之前隨 Windows SDK 發佈的 C++/WinRT 版本，那麼若要使用上面提到的 Windows 命名空間標頭，您的專案中需要至少 10.0.17134.0 (Windows 10 版本 1803) 的 Windows SDK 目標版本。

Visual Studio 2022 附帶了內建的 C++/WinRT 專案和項目範本，讓您可以立即開始進行 C++/WinRT 開發。它也附帶了 C++/WinRT 投影類型的 Visual Studio 原生偵錯視覺效果 (natvis)；提供類似於 C# 偵錯的體驗。 Natvis 會自動偵錯組建。如需詳細資訊，請參閱適用於 C++/WinRT 的 Visual Studio 原生偵錯視覺效果。

針對舊版的 Visual Studio，您會想要從 Visual Studio Marketplace 下載並安裝最新版的 C++/WinRT Visual Studio 擴充功能 (VSIX)。

VSIX 擴充功能為您在 Visual Studio 中提供了 C++/WinRT 專案和項目範本。
此外，它也為您提供了 C++/WinRT 投影類型的 Visual Studio 原生偵錯視覺效果 (natvis)。

下列各節會說明 C++/WinRT 的 Visual Studio 專案範本。當您建立已安裝最新版 VSIX 擴充功能的新 C++/WinRT 專案時候，新的 C++/WinRT 專案就會自動安裝 Microsoft.Windows.CppWinRT NuGet 套件。 Microsoft.Windows.CppWinRT NuGet 套件提供 C++/WinRT 建置支援 (MSBuild 屬性和目標)，讓您的專案能在開發電腦與建置代理程式之間可攜 (在其上只會安裝 NuGet套件，而不會安裝 VSIX 擴充功能)。

或者，您可藉由手動安裝 Microsoft.Windows.CppWinRT NuGet 套件來轉換現有的專案。安裝 (或更新到) 最新版本的 VSIX 擴充功能之後，請在 Visual Studio 中開啟現有專案，按一下 [專案]>[管理 NuGet 套件...]>[瀏覽]，在搜尋方塊中輸入或貼上 Microsoft.Windows.CppWinRT，選取搜尋結果中的項目，然後按一下　[安裝] 以安裝該專案的套件。新增該套件後，您會收到適用於專案的 C++/WinRT MSBuild 支援，包含叫用 cppwinrt.exe 工具。

重要

如果您有使用 1.0.190128.4 之前的 VSIX 擴充功能版本建立 (或升級使用) 的專案，則查看舊版的 VSIX 擴充功能。該區段包含您的專案組態相關重要資訊，您必須知道要將其升級為使用最新版的 VSIX 擴充功能。

因為 C++/ WinRT 使用來自 C++17 標準的功能，因此 NuGet 會在 Visual Studio 中設定專案屬性 [C/C++]>[語言]>[C++ 語言標準]>[ISO C++17 標準 (/std:c++17)]。
它也會新增 /bigobj 編譯器選項。
其新增 /await 編譯器選項來啟用 co_await。
並指示 XAML 編譯器發出 C++/WinRT Codegen。
您可能也想設定 [一致性模式：是 (/permissive-)，這會進一步限制您的程式碼符合標準。
另一個要注意的專案屬性是 [C/C++]>[一般]>[警告為錯誤]。將此設定為 [Yes(/WX)] 或 [No(/WX-)] 來品味。有時候，cppwinrt.exe 工具產生的來源檔案，會產生警告，直到您將實作新增至其中。

如上所述設定您的系統，您將能夠在 Visual Studio 中建立和建置或開啟 C++/WinRT 專案，並加以部署。

從 2.0 版起，Microsoft.Windows.CppWinRT NuGet 套件包含 cppwinrt.exe 工具。您可以指向位於 Windows 執行階段中繼資料 (.winmd) 檔案的 cppwinrt.exe 工具，以產生標頭檔案式標準 C++ 程式庫，其會「投影」中繼資料中所述的 API，從 C++/WinRT 程式碼耗用。 Windows 執行階段中繼資料 (.winmd) 檔案，提供描述 Windows 執行階段 API 介面的正式方式。透過在您可以產生程式庫的中繼資料指出 cppwinrt.exe，以在第二方或第三方 Windows 執行階段元件中搭配使用任何執行階段類別實作，或在您自己的應用程式中實作。如需詳細資訊，請參閱使用 C++/WinRT 取用 API。

透過使用 C++/WinRT，您也可以使用標準 C++ 實作自己的執行階段類別，而不用求助於 COM 樣式程式設計。對於執行階段類別，您只要在 IDL 檔案中描述您的類型，而 midl.exe 與 cppwinrt.exe 會為您產生實作重複使用的原始程式碼檔案。或者您可以只要實作衍生自 C++/WinRT 基底類別的介面。如需詳細資訊，請參閱使用 C++/WinRT 撰寫 API。

如需適用於 cppwinrt.exe 工具的自訂選項清單 (透過專案屬性設定)，請參閱 Microsoft.Windows.CppWinRT NuGet 套件讀我檔案。

您可以依照專案中安裝的 Microsoft.Windows.CppWinRT NuGet 套件顯示狀態，找出使用 C++/WinRT MSBuild 支援的專案。

以下是 VSIX 擴充功能所提供的 Visual Studio 專案範本。

空白的應用程式 (C++/WinRT)

適用於擁有 XAML 使用者介面的通用 Windows 平台 (UWP) 的應用程式範本。

Visual Studio 提供 XAML 編譯器支援，並從位於每個 XAML 標記檔案後面的介面定義語言 (IDL) (.idl) 產生實作與標頭虛設常式。在 IDL 檔案中，定義任何您想要在應用程式 XAML 網頁中參考的本機執行階段類別，然後見一次專案，在 Generated Files 中產生實作範本，以及 Generated Files\sources 中的虛設常式類型定義。然後使用這些適用於參考的虛設類型定義，實作您的本機執行階段類別。請參閱將執行階段類別分解成 Midl 檔案 (.idl)。

Visual Studio 中對 C++/WinRT 的 XAML 設計介面支援與 C# 接近同等。在 Visual Studio 中，您可以使用 [屬性] 視窗的 [事件] 索引標籤，在 C++/WinRT 專案內新增事件處理常式。您也可以將事件處理常式手動新增到您的程式碼中，請參閱在 C++/WinRT 中使用委派來處理事件，以取得詳細資訊。

核心應用程式 (C++/WinRT)

適用於不使用 XAML 的通用 Windows 平台 (UWP) 應用程式的專案範本。

但是，它使用適用於 Windows.ApplicationModel.Core 命名空間的 C++/WinRT Windows 命名空間標頭。在建置與執行後，請按一下空白空間新增彩色方格；然後再按一下彩色方格拖曳它。

Windows 主控台應用程式 (C++/WinRT)

Windows 傳統型 C++/WinRT 用戶端應用程式的專案範本 (具有主控台使用者介面)。

Windows 傳統型應用程式 (C++/WinRT)

Windows 傳統型 C++/WinRT 用戶端應用程式的專案範本，其在 Win32 MessageBox 內顯示 Windows 執行階段 Windows.Foundation.Uri。

Windows 執行階段元件 (C++/WinRT)

元件的專案範本；通常適用於通用 Windows 平台 (UWP) 的使用量。

此範本示範 midl.exe>cppwinrt.exe 工具鏈，其中從 IDL 產生 Windows 執行階段中繼資料 (.winmd)，然後從 Windows Runtime 中繼資料產生實作及標頭虛設常式。

在 IDL 檔案中，在您的元件、其預設的介面，以及任何其實作的其他介面中，定義執行階段類別。建置一次專案產生 module.g.cpp、module.h.cpp、Generated Files 中的實作範本，以及 Generated Files\sources 中的虛設常式類型定義。然後使用這些適用於參考的虛設類型定義，實作您元件中的執行階段類別。請參閱將執行階段類別分解成 Midl 檔案 (.idl)。

將已建置的 Windows 執行階段元件二進位與其 .winmd 和使用它們的 UWP 應用程式搭配一起。

舊版 VSIX 擴充功能

我們建議您安裝 (或更新為) 最新版的 VSIX 擴充功能。預設情況下，它會設定為自行更新。如果您這麼做，且具有使用 1.0.190128.4 之前的 VSIX 擴充功能版本建立的專案，則這一節包含將這些專案升級為使用新版本的重要資訊。如果您未更新，您仍會發現這一節中的資訊很有用。

就支援的 Windows SDK 和 Visual Studio 版本，以及 Visual Studio 組態而言，上面 C++/WinRT、XAML、VSIX 擴充功能和 NuGet 套件的 Visual Studio 支援一節中的資訊適用於舊版的 VSIX 擴充功能。以下資訊針對使用舊版建立 (或升級使用) 的專案，說明其行為和組態的重要差異。

在 1.0.181002.2 之前建立

如果您的專案使用 1.0.181002.2 之前的 VSIX 擴充功能版本建立，然後C++/WinRT 建置支援內建在該版本的 VSIX 擴充功能中。您的專案已在 .vcxproj 檔案中設定 <CppWinRTEnabled>true</CppWinRTEnabled> 屬性。

<Project ...>
    <PropertyGroup Label="Globals">
        <CppWinRTEnabled>true</CppWinRTEnabled>
...

您可以藉由手動安裝 Microsoft.Windows.CppWinRT NuGet 套件來升級您的專案。安裝 (或升級到) 最新版本的 VSIX 擴充功能之後，請在 Visual Studio 中開啟您的專案，按一下 [專案]>[管理 NuGet 套件...]>[瀏覽]，在搜尋方塊中輸入或貼上 Microsoft.Windows.CppWinRT，選取搜尋結果中的項目，然後按一下　[安裝] 以安裝您的專案的套件。

使用 1.0.181002.2 與 1.0.190128.3 之間版本建立 (或升級)

如果您的專案使用 1.0.181002.2 與 1.0.190128.3 (含) 之間的 VSIX 擴充功能版本建立，則專案範本會在專案中自動建立 Microsoft.Windows.CppWinRT NuGet 套件。您可能也已將舊專案升級為使用此範圍中的 VSIX 擴充功能版本。如果您這樣做，則 (因為建置支援也仍然存在於此範圍內的 VSIX 擴充功能版本中) 您升級的專案不一定已安裝 Microsoft.Windows.CppWinRT NuGet 套件。

若要升級您的專案，請遵循上一節中的指示，並確保您的專案已經安裝 Microsoft.Windows.CppWinRT NuGet 套件。

無效的升級組態

使用最新版的 VSIX 擴充功能時，如果也還沒安裝 Microsoft.Windows.CppWinRTNuGet 套件，專案就不適合具有 <CppWinRTEnabled>true</CppWinRTEnabled> 屬性。具有此組態的專案會產生建置錯誤訊息「C++/WinRT VSIX 不再提供專案的建置支援。請將專案參考加入 Microsoft.Windows.CppWinRT Nuget 套件」。

如上所述， C++/WinRT 專案現在必須已安裝的 NuGet 套件。

由於 <CppWinRTEnabled> 元素現在已過時，您可以選擇性地編輯 .vcxproj，以及刪除此元素。它不是絕對必要，但是個選項。

此外，如果 .vcxproj 包含 <RequiredBundles>$(RequiredBundles);Microsoft.Windows.CppWinRT</RequiredBundles>，則可以將它移除，以便在不需安裝 C++/WinRT VSIX 擴充功能的情況下建置。

適用於 C++/WinRT 的 SDK 支援

雖然現在僅針對相容性理由存在，但自版本 10.0.17134.0 (Windows 10，版本 1803) 開始，Windows SDK 包含標頭檔案式的標準 C++ 程式庫，以取用 Windows 命名空間中第一方 Windows API (Windows 執行階段 API)。這些標頭位於 %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt 資料夾內。從 Windows SDK 版本 10.0.17763.0 (Windows 10 版本 1809) 起，系統會為您在專案 $(GeneratedFilesDir) 資料夾內產生這些標頭。

針對相容性，Windows SDK 也會再次隨附 cppwinrt.exe 工具。不過，我們建議您改為安裝並使用最新版的 cppwinrt.exe，這隨附於 Microsoft.Windows.CppWinRT NuGet 套件。該套件以及 cppwinrt.exe 已在上述各節中說明。

C++/WinRT 投影中的自訂類型

在您的 C++/WinRT 程式設計中，您可以使用標準 C++ 語言功能和標準 C++ 資料類型與 C++/WinRT (包括一些 C++ 標準程式庫資料類型)。但也您會注意到投影中的某些自訂資料類型，且您可以選擇使用它們。例如，我們會使用開始使用 C++/WinRT 中快速程式碼範例的 winrt::hstring。

winrt::com_array 是您在某些時候可能會使用的另一種類型。但是您比較不可能直接使用 winrt::array_view等類型。或者，您可以選擇不想使用它，如果且當 C++ 標準程式庫中出現對等項目類型時，才不會變更任何程式碼。

警告

如果您仔細研究 C++/WinRT Windows 命名空間標頭，您也會看到這類類型。一個範例是 winrt::param::hstring，但有也會收集範例。這些會存在只是要最佳化輸入參數的繫結，並且它們會產生大幅的效能提升，讓大部分呼叫模式「只適用於」相關的標準 C++ 類型和容器。這些類型僅由投影在新增大多數值時使用。它們會高度最佳化，它們不用於一般用途，切勿冒險自行使用它們。您也不應該使用 winrt::impl 命名空間的任何項目，因為這些是實作類型，因此會隨時變更。您應該繼續使用標準類型，或來自 winrt 命名空間的類型。

另請參閱將參數傳入 ABI 界限。