C++/WinRT 簡介Introduction to C++/WinRT

 

 

C++/WinRT 是完全標準現代的 Windows 執行階段 (WinRT) API 的 C++17 語言投影,僅實作為標頭檔案式程式庫,以及設計用來提供您現代化 Windows API 的第一級存取。C++/WinRT is an entirely standard modern C++17 language projection for Windows Runtime (WinRT) APIs, implemented as a header-file-based library, and designed to provide you with first-class access to the modern Windows API. 使用 C++/WinRT,您可以撰寫及取用使用任何符合標準 C++17 編譯器的 Windows 執行階段 API。With C++/WinRT, you can author and consume Windows Runtime APIs using any standards-compliant C++17 compiler. Windows SDK 包含 C++/WinRT;其在版本 10.0.17134.0 (Windows 10,版本 1803 ) 中引進。The Windows SDK includes C++/WinRT; it was introduced in version 10.0.17134.0 (Windows 10, version 1803).

C++/WinRT 是 Microsoft 針對 C++/CX 語言投影和 Windows 執行階段 C++ 範本庫 (WRL) 建議的替代方案。C++/WinRT is Microsoft's recommended replacement for the C++/CX language projection, and the Windows Runtime C++ Template Library (WRL). C++/WinRT 相關主題的完整清單包含有關與 C++/CX 和 WRL 交互操作,以及從從移植的資訊。The full list of topics about C++/WinRT includes info about both interoperating with, and porting from, C++/CX and WRL.

重要

最重要的一些 C++/WinRT 項目會在 C++/WinRT 的 SDK 支援C++/WinRT、XAML、VSIX 擴充功能和 NuGet 套件的 Visual Studio 支援等章節中說明。Some of the most important pieces of C++/WinRT to be aware of are described in the sections SDK support for C++/WinRT and Visual Studio support for C++/WinRT, XAML, the VSIX extension, and the NuGet package.

另請參閱我可以在哪裡找到 C++/WinRT 範例應用程式?Also see Where can I find C++/WinRT sample apps?.

語言投影Language projections

Windows 執行階段根據元件物件模型 (COM) API,且設計它透過「語言投影」 來存取。The Windows Runtime is based on Component Object Model (COM) APIs, and it's designed to be accessed through language projections. 投影會隱藏 COM 的詳細資訊,並針對特定語言提供更自然的程式設計體驗。A projection hides the COM details, and provides a more natural programming experience for a given language.

Windows 執行階段 API 參考內容中的 C++/WinRT 語言投影The C++/WinRT language projection in the Windows Runtime API reference content

當您在瀏覽Windows 執行階段 API,按一下右上方下拉式方塊中的 [語言] ,然後選取C++/WinRT,當它們在 C++/WinRT 語言投影中顯示時,檢視 API 語法區塊。When you're browsing Windows Runtime APIs, click the Language combo box in the upper right, and select C++/WinRT to view API syntax blocks as they appear in the C++/WinRT language projection.

C++/WinRT、XAML、VSIX 擴充功能和 NuGet 套件的 Visual Studio 支援Visual Studio support for C++/WinRT, XAML, the VSIX extension, and the NuGet package

如需 Visual Studio 支援,您需要 Visual Studio 2019 或 Visual Studio 2017 (至少 15.6 版;我們建議至少 15.7 版)。For Visual Studio support, you'll need Visual Studio 2019 or Visual Studio 2017 (at least version 15.6; we recommend at least 15.7). 從 Visual Studio 安裝程式中,安裝通用 Windows 平台開發工作負載。From within the Visual Studio Installer, install the Universal Windows Platform development workload. 在 [安裝詳細資料] > [通用 Windows 平台開發] 中,勾選 [C++ (v14x) 通用 Windows 平台工具] 選項 (如果尚未勾選)。In Installation Details > Universal Windows Platform development, check the C++ (v14x) Universal Windows Platform tools option(s), if you haven't already done so. 而在 Windows [設定] > [更新與安全性] & > [針對開發人員] 中,選擇 [開發人員模式] 選項,而非 [側載應用程式] 選項。And, in Windows Settings > Update & Security > For developers, choose the Developer mode option rather than the Sideload apps option.

雖然我們建議您使用最新版的 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 目標版本。While we recommend that you develop with the latest versions of Visual Studio and the Windows SDK, if you're using a version of C++/WinRT that shipped with the Windows SDK prior to 10.0.17763.0 (Windows 10, version 1809), then, to use the the Windows namespaces headers mentioned above, you'll need a minimum Windows SDK target version in your project of 10.0.17134.0 (Windows 10, version 1803).

您會想要從 Visual Studio Marketplace下載並安裝最新版的 C++/WinRT Visual Studio 擴充功能 (VSIX)You'll want to download and install the latest version of the C++/WinRT Visual Studio Extension (VSIX) from the Visual Studio Marketplace.

  • VSIX 擴充功能為您在 Visual Studio 中提供 C++/WinRT 專案和項目範本,以便您開始進行 C++/WinRT 開發。The VSIX extension gives you C++/WinRT project and item templates in Visual Studio, so that you can get started with C++/WinRT development.
  • 此外,它也會提供您 C++/WinRT 投影類型的 Visual Studio 原生偵錯視覺效果 (natvis);提供與 C# 偵錯相似的體驗。In addition, it gives you Visual Studio native debug visualization (natvis) of C++/WinRT projected types; providing an experience similar to C# debugging. Natvis 會自動偵錯組建。Natvis is automatic for debug builds. 您可以透過定義符號 WINRT_NATVIS 選擇加入到發行組建。You can opt into it release builds by defining the symbol WINRT_NATVIS.

下列各節會說明 C++/WinRT 的 Visual Studio 專案範本。The Visual Studio project templates for C++/WinRT are described in the sections below. 當您建立已安裝最新版 VSIX 擴充功能的新 C++/WinRT 專案時候,新的 C++/WinRT 專案就會自動安裝 Microsoft.Windows.CppWinRT NuGet 套件When you create a new C++/WinRT project with the latest version of the VSIX extension installed, the new C++/WinRT project automatically installs the Microsoft.Windows.CppWinRT NuGet package. Microsoft.Windows.CppWinRT NuGet 套件提供 C++/WinRT 建置支援 (MSBuild 屬性和目標),讓您的專案能在開發電腦與建置代理程式之間可攜 (在其上只會安裝 NuGet套件,而不會安裝 VSIX 擴充功能)。The Microsoft.Windows.CppWinRT NuGet package provides C++/WinRT build support (MSBuild properties and targets), making your project portable between a development machine and a build agent (on which only the NuGet package, and not the VSIX extension, is installed).

或者,您可藉由手動安裝 Microsoft.Windows.CppWinRT NuGet 套件來轉換現有的專案。Alternatively, you can convert an existing project by manually installing the Microsoft.Windows.CppWinRT NuGet package. 安裝 (或更新為) 最新版 VSIX 擴充功能之後,請在 Visual Studio 中開啟現有的專案,按一下 [專案] >[管理 NuGet 套件...] >[瀏覽] 、在搜尋方塊中輸入或貼上 Microsoft.Windows.CppWinRT、在搜尋結果中選取項目,然後按一下 [安裝] 以安裝適用於該專案的套件。After installing (or updating to) the latest version of the VSIX extension, open the existing project in Visual Studio, click Project > Manage NuGet Packages... > Browse, type or paste Microsoft.Windows.CppWinRT in the search box, select the item in search results, and then click Install to install the package for that project. 新增該套件後,您會收到適用於專案的 C++/WinRT MSBuild 支援,包含叫用 cppwinrt.exe 工具。Once you've added the package, you'll get C++/WinRT MSBuild support for the project, including invoking the cppwinrt.exe tool.

重要

如果您有使用 1.0.190128.4 之前的 VSIX 擴充功能版本建立 (或升級使用) 的專案,則查看舊版的 VSIX 擴充功能If you have projects that were created with (or upgraded to work with) a version of the VSIX extension earlier than 1.0.190128.4, then see Earlier versions of the VSIX extension. 該區段包含您的專案組態相關重要資訊,您必須知道要將其升級為使用最新版的 VSIX 擴充功能。That section contains important info about the configuration of your projects, which you'll need to know to upgrade them to use the latest version of the VSIX extension.

  • 因為 C++/ WinRT 使用來自 C++17 標準的功能,因此 NuGet 會在 Visual Studio 中設定專案屬性 [C/C++] > [語言] > [C++ 語言標準] > [ISO C++17 標準 (/std:c++17)] 。Because C++/WinRT uses features from the C++17 standard, the NuGet package sets project property C/C++ > Language > C++ Language Standard > ISO C++17 Standard (/std:c++17) in Visual Studio.
  • 它也會新增 /bigobj 編譯器選項。It also adds the /bigobj compiler option.
  • 其新增 /await 編譯器選項來啟用 co_awaitIt adds the /await compiler option in order to enable co_await.
  • 並指示 XAML 編譯器發出 C++/WinRT Codegen。It instructs the XAML compiler to emit C++/WinRT codegen.
  • 您可能也想要設定 [一致性模式: 是 (/permissive--)],其進一步將您的程式碼限制為符合標準。You might also want to set Conformance mode: Yes (/permissive-), which further constrains your code to be standards-compliant.
  • 另一個要注意的專案屬性是 [C/C++] > [一般] > [警告為錯誤] 。Another project property to be aware of is C/C++ > General > Treat Warnings As Errors. 將此設定為 [Yes(/WX)] 或 [No(/WX-)] 來品味。Set this to Yes(/WX) or No (/WX-) to taste. 有時候,cppwinrt.exe 工具產生的來源檔案,會產生警告,直到您將實作新增至其中。Sometimes, source files generated by the cppwinrt.exe tool generate warnings until you add your implementation to them.

如上所述設定您的系統,您將能夠在 Visual Studio 中建立和建置或開啟 C++/WinRT 專案,並加以部署。With your system set up as described above, you'll be able to create and build, or open, a C++/WinRT project in Visual Studio, and deploy it.

從 2.0 版起,Microsoft.Windows.CppWinRT NuGet 套件包含 cppwinrt.exe 工具。As of version 2.0, the Microsoft.Windows.CppWinRT NuGet package includes the cppwinrt.exe tool. 您可以指向位於 Windows 執行階段中繼資料 (.winmd) 檔案的 cppwinrt.exe 工具,以產生標頭檔案式標準 C++ 程式庫,其會「投影」 中繼資料中所述的 API,從 C++/WinRT 程式碼耗用。You can point the cppwinrt.exe tool at a Windows Runtime metadata (.winmd) file to generate a header-file-based standard C++ library that projects the APIs described in the metadata for consumption from C++/WinRT code. Windows 執行階段中繼資料 (.winmd) 檔案,提供描述 Windows 執行階段 API 介面的正式方式。Windows Runtime metadata (.winmd) files provide a canonical way of describing a Windows Runtime API surface. 透過在您可以產生程式庫的中繼資料指出 cppwinrt.exe,以在第二方或第三方 Windows 執行階段元件中搭配使用任何執行階段類別實作,或在您自己的應用程式中實作。By pointing cppwinrt.exe at metadata, you can generate a library for use with any runtime class implemented in a second- or third-party Windows Runtime component, or implemented in your own application. 如需詳細資訊,請參閱使用 C++/WinRT 取用 APIFor more info, see Consume APIs with C++/WinRT.

透過使用 C++/WinRT,您也可以使用標準 C++ 實作自己的執行階段類別,而不用求助於 COM 樣式程式設計。With C++/WinRT, you can also implement your own runtime classes using standard C++, without resorting to COM-style programming. 對於執行階段類別,您只要在 IDL 檔案中描述您的類型,而 midl.execppwinrt.exe 會為您產生實作重複使用的原始程式碼檔案。For a runtime class, you just describe your types in an IDL file, and midl.exe and cppwinrt.exe generate your implementation boilerplate source code files for you. 或者您可以只要實作衍生自 C++/WinRT 基底類別的介面。You can alternatively just implement interfaces by deriving from a C++/WinRT base class. 如需詳細資訊,請參閱使用 C++/WinRT 撰寫 APIFor more info, see Author APIs with C++/WinRT.

如需適用於 cppwinrt.exe 工具的自訂選項清單 (透過專案屬性設定),請參閱 Microsoft.Windows.CppWinRT NuGet 套件讀我檔案For a list of customization options for the cppwinrt.exe tool, set via project properties, see the Microsoft.Windows.CppWinRT NuGet package readme.

您可以依照專案中安裝的 Microsoft.Windows.CppWinRT NuGet 套件顯示狀態,找出使用 C++/WinRT MSBuild 支援的專案。You can identify a project that uses the C++/WinRT MSBuild support by the presence of the Microsoft.Windows.CppWinRT NuGet package installed within the project.

以下是 VSIX 擴充功能所提供的 Visual Studio 專案範本。Here are the Visual Studio project templates provided by the VSIX extension.

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

適用於擁有 XAML 使用者介面的通用 Windows 平台 (UWP) 的應用程式範本。A project template for a Universal Windows Platform (UWP) app that has a XAML user-interface.

Visual Studio 提供 XAML 編譯器支援,並從位於每個 XAML 標記檔案後面的介面定義語言 (IDL) (.idl) 產生實作與標頭虛設常式。Visual Studio provides XAML compiler support to generate implementation and header stubs from the Interface Definition Language (IDL) (.idl) file that sits behind each XAML markup file. 在 IDL 檔案中,定義任何您想要在應用程式 XAML 網頁中參考的本機執行階段類別,然後見一次專案,在 Generated Files 中產生實作範本,以及 Generated Files\sources 中的虛設常式類型定義。In an IDL file, define any local runtime classes that you want to reference in your app's XAML pages, and then build the project once to generate implementation templates in Generated Files, and stub type definitions in Generated Files\sources. 然後使用這些適用於參考的虛設類型定義,實作您的本機執行階段類別。Then use those stub type definitions for reference to implement your local runtime classes. 請參閱將執行階段類別分解成 Midl 檔案 (.idl)See Factoring runtime classes into Midl files (.idl).

Visual Studio 2019 中針對 C++/WinRT 的 XAML 設計介面支援即使用 C# 進行同位檢查。The XAML design surface support in Visual Studio 2019 for C++/WinRT is close to parity with C#. 在 Visual Studio 2019 中,您可以使用 [屬性] 視窗的 [事件] 索引標籤,在 C++/WinRT 專案內新增事件處理常式。In Visual Studio 2019, you can use the Events tab of the Properties window to add event handlers within a C++/WinRT project. 您也可以將事件處理常式手動新增到您的程式碼,—請參閱在 C++/WinRT 中使用委派來處理事件,以取得詳細資訊。You can also add event handlers to your code manually—see Handle events by using delegates in C++/WinRT for more info.

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

適用於不使用 XAML 的通用 Windows 平台 (UWP) 應用程式的專案範本。A project template for a Universal Windows Platform (UWP) app that doesn't use XAML.

但是,它使用適用於 Windows.ApplicationModel.Core 命名空間的 C++/WinRT Windows 命名空間標頭。Instead, it uses the C++/WinRT Windows namespace header for the Windows.ApplicationModel.Core namespace. 在建置與執行後,請按一下空白空間新增彩色方格;然後再按一下彩色方格拖曳它。After building and running, click on an empty space to add a colored square; then click on a colored square to drag it.

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

Windows 傳統型 C++/WinRT 用戶端應用程式的專案範本 (具有主控台使用者介面)。A project template for a C++/WinRT client application for Windows Desktop, with a console user-interface.

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

Windows 傳統型 C++/WinRT 用戶端應用程式的專案範本,其在 Win32 MessageBox 內顯示 Windows 執行階段 Windows.Foundation.UriA project template for a C++/WinRT client application for Windows Desktop, which displays a Windows Runtime Windows.Foundation.Uri inside a Win32 MessageBox.

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

元件的專案範本;通常適用於通用 Windows 平台 (UWP) 的使用量。A project template for a component; typically for consumption from a Universal Windows Platform (UWP).

此範本示範 midl.exe > cppwinrt.exe 工具鏈,其中從 IDL 產生 Windows 執行階段中繼資料 (.winmd),然後從 Windows Runtime 中繼資料產生實作及標頭虛設常式。This template demonstrates the midl.exe > cppwinrt.exe toolchain, where Windows Runtime metadata (.winmd) is generated from IDL, and then implementation and header stubs are generated from the Windows Runtime metadata.

在 IDL 檔案中,在您的元件、其預設的介面,以及任何其實作的其他介面中,定義執行階段類別。In an IDL file, define the runtime classes in your component, their default interface, and any other interfaces they implement. 建置一次專案產生 module.g.cppmodule.h.cppGenerated Files 中的實作範本,以及 Generated Files\sources 中的虛設常式類型定義。Build the project once to generate module.g.cpp, module.h.cpp, implementation templates in Generated Files, and stub type definitions in Generated Files\sources. 然後使用這些適用於參考的虛設類型定義,實作您元件中的執行階段類別。Then use those the stub type definitions for reference to implement the runtime classes in your component. 請參閱將執行階段類別分解成 Midl 檔案 (.idl)See Factoring runtime classes into Midl files (.idl).

將已建置的 Windows 執行階段元件二進位與其 .winmd 和使用它們的 UWP 應用程式搭配一起。Bundle the built Windows Runtime component binary and its .winmd with the UWP app consuming them.

舊版 VSIX 擴充功能Earlier versions of the VSIX extension

我們建議您安裝 (或更新為) 最新版的 VSIX 擴充功能We recommend that you install (or update to) the latest version of the VSIX extension. 預設情況下,它會設定為自行更新。It is configured to update itself by default. 如果您這麼做,且具有使用 1.0.190128.4 之前的 VSIX 擴充功能版本建立的專案,則這一節包含將這些專案升級為使用新版本的重要資訊。If you do that, and you have projects that were created with a version of the VSIX extension earlier than 1.0.190128.4, then this section contains important info about upgrading those projects to work with the new version. 如果您未更新,您仍會發現這一節中的資訊很有用。If you don't update, then you'll still find the info in this section useful.

就支援的 Windows SDK 和 Visual Studio 版本,以及 Visual Studio 組態而言,上面 C++/WinRT、XAML、VSIX 擴充功能和 NuGet 套件的 Visual Studio 支援一節中的資訊適用於舊版的 VSIX 擴充功能。In terms of supported Windows SDK and Visual Studio versions, and Visual Studio configuration, the info in the Visual Studio support for C++/WinRT, XAML, the VSIX extension, and the NuGet package section above applies to earlier versions of the VSIX extension. 以下資訊針對使用舊版建立 (或升級使用) 的專案,說明其行為和組態的重要差異。The info below describes important differences regarding the behavior and configuration of projects created with (or upgraded to work with) earlier versions.

在 1.0.181002.2 之前建立Created earlier than 1.0.181002.2

如果您的專案使用 1.0.181002.2 之前的 VSIX 擴充功能版本建立,然後C++/WinRT 建置支援內建在該版本的 VSIX 擴充功能中。If your project was created with a version of the VSIX extension earlier than 1.0.181002.2, then C++/WinRT build support was built into that version of the VSIX extension. 您的專案已在 .vcxproj 檔案中設定 <CppWinRTEnabled>true</CppWinRTEnabled> 屬性。Your project has the <CppWinRTEnabled>true</CppWinRTEnabled> property set in the .vcxproj file.

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

您可以藉由手動安裝 Microsoft.Windows.CppWinRT NuGet 套件來升級您的專案。You can upgrade your project by manually installing the Microsoft.Windows.CppWinRT NuGet package. 安裝 (或升級為) 最新版 VSIX 擴充功能之後,請在 Visual Studio 中開啟您的專案,按一下 [專案] >[管理 NuGet 套件...] >[瀏覽] 、在搜尋方塊中輸入或貼上 Microsoft.Windows.CppWinRT、在搜尋結果中選取項目,然後按一下 [安裝] 以安裝適用於您專案的套件。After installing (or upgrading to) the latest version of the VSIX extension, open your project in Visual Studio, click Project > Manage NuGet Packages... > Browse, type or paste Microsoft.Windows.CppWinRT in the search box, select the item in search results, and then click Install to install the package for your project.

使用 1.0.181002.2 與 1.0.190128.3 之間版本建立 (或升級)Created with (or upgraded to) between 1.0.181002.2 and 1.0.190128.3

如果您的專案使用 1.0.181002.2 與 1.0.190128.3 (含) 之間的 VSIX 擴充功能版本建立,則專案範本會在專案中自動建立 Microsoft.Windows.CppWinRT NuGet 套件。If your project was created with a version of the VSIX extension between 1.0.181002.2 and 1.0.190128.3, inclusive, then the Microsoft.Windows.CppWinRT NuGet package was installed in the project automatically by the project template. 您可能也已將舊專案升級為使用此範圍中的 VSIX 擴充功能版本。You might also have upgraded an older project to use a version of the VSIX extension in this range. 如果您這樣做,則—因為建置支援也仍然存在於此範圍內的 VSIX 擴充功能版本中—您升級的專案不一定已安裝 Microsoft.Windows.CppWinRT NuGet 套件。If you did, then—since build support was also still present in versions of the VSIX extension in this range—your upgraded project may or may not have the Microsoft.Windows.CppWinRT NuGet package installed.

若要升級您的專案,請遵循上一節中的指示,並確保您的專案已經安裝 Microsoft.Windows.CppWinRT NuGet 套件。To upgrade your project, follow the instructions in the previous section and ensure that your project does have the Microsoft.Windows.CppWinRT NuGet package installed.

無效的升級組態Invalid upgrade configurations

使用最新版的 VSIX 擴充功能時,如果也還沒安裝 Microsoft.Windows.CppWinRTNuGet 套件,專案就不適合具有 <CppWinRTEnabled>true</CppWinRTEnabled> 屬性。With the latest version of the VSIX extension, it's not valid for a project to have the <CppWinRTEnabled>true</CppWinRTEnabled> property if it doesn't also have the Microsoft.Windows.CppWinRT NuGet package installed. 具有此組態的專案會產生建置錯誤訊息「C++/WinRT VSIX 不再提供專案的建置支援。A project with this configuration produces the build error message, "The C++/WinRT VSIX no longer provides project build support. 請將專案參考加入 Microsoft.Windows.CppWinRT Nuget 套件」。Please add a project reference to the Microsoft.Windows.CppWinRT Nuget package."

如上所述, C++/WinRT 專案現在必須已安裝的 NuGet 套件。As mentioned above, a C++/WinRT project now needs to have the NuGet package installed in it.

由於 <CppWinRTEnabled> 元素現在已過時,您可以選擇性地編輯 .vcxproj,以及刪除此元素。Since the <CppWinRTEnabled> element is now obsolete, you can optionally edit your .vcxproj, and delete the element. 它不是絕對必要,但是個選項。It's not strictly necessary, but it's an option.

此外,如果 .vcxproj 包含 <RequiredBundles>$(RequiredBundles);Microsoft.Windows.CppWinRT</RequiredBundles>,則可以將它移除,以便在不需安裝 C++/WinRT VSIX 擴充功能的情況下建置。Also, if your .vcxproj contains <RequiredBundles>$(RequiredBundles);Microsoft.Windows.CppWinRT</RequiredBundles>, then you can remove it so that you can build without requiring the C++/WinRT VSIX extension to be installed.

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

雖然現在僅針對相容性理由存在,但自版本 10.0.17134.0 (Windows 10,版本 1803) 開始,Windows SDK 包含標頭檔案式的標準 C++ 程式庫,以取用 Windows 命名空間中第一方 Windows API (Windows 執行階段 API)。Although it is now present only for compatibility reasons, as of version 10.0.17134.0 (Windows 10, version 1803), the Windows SDK contains a header-file-based standard C++ library for consuming first-party Windows APIs (Windows Runtime APIs in Windows namespaces). 這些標頭位於 %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt 資料夾內。Those headers are inside the folder %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt. 從 Windows SDK 版本 10.0.17763.0 (Windows 10 版本 1809) 起,系統會為您在專案 $(GeneratedFilesDir) 資料夾內產生這些標頭。As of the Windows SDK version 10.0.17763.0 (Windows 10, version 1809), these headers are generated for you inside your project's $(GeneratedFilesDir) folder.

針對相容性,Windows SDK 也會再次隨附 cppwinrt.exe 工具。Again for compatibility, the Windows SDK also comes with the cppwinrt.exe tool. 不過,我們建議您改為安裝並使用最新版的 cppwinrt.exe,這隨附於 Microsoft.Windows.CppWinRT NuGet 套件。However, we recommend that you instead install and use the most recent version of cppwinrt.exe, which is included with the Microsoft.Windows.CppWinRT NuGet package. 該套件以及 cppwinrt.exe 已在上述各節中說明。That package, and cppwinrt.exe, are described in the sections above.

C++/WinRT 投影中的自訂類型Custom types in the C++/WinRT projection

在您的 C++/WinRT 程式設計中,您可以使用標準 C++ 語言功能和標準 C++ 資料類型與 C++/WinRT—包括一些 C++ 標準程式庫資料類型。In your C++/WinRT programming, you can use standard C++ language features and Standard C++ data types and C++/WinRT—including some C++ Standard Library data types. 但也您會注意到投影中的某些自訂資料類型,且您可以選擇使用它們。But you'll also become aware of some custom data types in the projection, and you can choose to use them. 例如,我們會使用開始使用 C++/WinRT 中快速程式碼範例的 winrt::hstringFor example, we use winrt::hstring in the quick-start code example in Get started with C++/WinRT.

winrt::com_array 是您在某些時候可能會使用的另一種類型。winrt::com_array is another type that you're likely to use at some point. 但是您比較不可能直接使用 winrt::array_view等類型。But you're less likely to directly use a type such as winrt::array_view. 或者,您可以選擇不想使用它,如果且當 C++ 標準程式庫中出現對等項目類型時,才不會變更任何程式碼。Or you may choose not to use it so that you won't have any code to change if and when an equivalent type appears in the C++ Standard Library.

警告

如果您仔細研究 C++/WinRT Windows 命名空間標頭,您也會看到這類類型。There are also types that you might see if you closely study the C++/WinRT Windows namespace headers. 一個範例是 winrt::param::hstring,但有也會收集範例。An example is winrt::param::hstring, but there are collection examples too. 這些會存在只是要最佳化輸入參數的繫結,並且它們會產生大幅的效能提升,讓大部分呼叫模式「只適用於」相關的標準 C++ 類型和容器。These exist solely to optimize the binding of input parameters, and they yield big performance improvements and make most calling patterns "just work" for related standard C++ types and containers. 這些類型僅由投影在新增大多數值時使用。These types are only ever used by the projection in cases where they add most value. 它們會高度最佳化,它們不用於一般用途,切勿冒險自行使用它們。They're highly optimized and they're not for general use; don't be tempted to use them yourself. 您也不應該使用 winrt::impl 命名空間的任何項目,因為這些是實作類型,因此會隨時變更。Nor should you use anything from the winrt::impl namespace, since those are implementation types, and therefore subject to change. 您應該繼續使用標準類型,或來自 winrt 命名空間的類型。You should continue to use standard types, or types from the winrt namespace.

另請參閱將參數傳入 ABI 界限Also see Passing parameters into the ABI boundary.

重要 APIImportant APIs