repository·master·Indexed 23 days ago
https://github.com/microsoft/cppwinrtA header-only C++ language projection for the Windows Runtime (WinRT) that enables the use of modern Windows APIs with standard C++17 code. It includes the Microsoft.Windows.CppWinRT NuGet package for build automation, a Visual Studio Extension (VSIX) for debug visualization and templates, and the cppwinrt.exe CLI tool for generating projections and C++20 module interface units (.ixx) from Windows Metadata (.winmd) files.
The C++/WinRT VSIX provides two primary developer productivity features:
C++/WinRT projections are accessed via specific module names:
winrt_base: Contains core C++/WinRT types like hstring, com_ptr, and IUnknown. This is re-exported by all namespace modules.winrt_numerics: Contains Windows::Foundation::Numerics types. This is re-exported by winrt_base.winrt.<Namespace>: The per-namespace projection (e.g., winrt.Windows.Foundation).| Module | Contents |
|--------|----------|
| `winrt_base` | Core C++/WinRT types (`hstring`, `com_ptr`, `IUnknown`, etc.) — re-exported by all namespace modules |
| `winrt_numerics` | `Windows::Foundation::Numerics` types — re-exported by `winrt_base` |
| `winrt.<Namespace>` | Per-namespace projection (e.g., `winrt.Windows.Foundation`) |When working with C++/WinRT modules, you must adhere to these three rules to avoid compiler errors:
import in PCH: MSVC cannot handle import declarations inside a Precompiled Header (PCH). All module imports must reside in .cpp files or other non-PCH files.#include-ing a header and then import-ing the same content, doing this with C++/WinRT projection headers is extremely expensive for build times. Use import directly whenever possible.WINRT_IMPORT_MODULE: If you have already import-ed a module, #include-ing a header that declares the same types will cause conflicting declaration errors. To safely include WinRT headers after an import (e.g., to support libraries like WIL), define the WINRT_IMPORT_MODULE macro before the #include statement. This turns the header into a mostly no-op.When working with modules across different projects, follow these constraints to avoid linker errors and ABI mismatches:
ProjectReferences to component projects with CppWinRTConsumeModule. Instead, each consumer should build its own reference projection from the component's .winmd.CppWinRTConsumeModule=true on a dedicated static library project (a Module Builder) designed to compile platform SDK modules. This builder should use flags that produce safe modules (no -opt, no -comp).CppWinRTModuleInclude and CppWinRTModuleExclude apply to platform, reference, and component projections. Ensure your filters cover all intended namespaces./Zp settings./std:c++20).C++/WinRT uses the discovered metadata to generate different types of headers based on the source:
For any discovered .winmd file, C++/WinRT creates reference (consuming) projection headers. To use these in your application, simply #include the generated headers from your project's generated files directory.
For any .idl file contained within your project, C++/WinRT creates component (producing) projection headers. Additionally, it generates the necessary templates and skeleton implementations for each runtime class, which are stored in the Generated Files directory.
C++/WinRT supports C++20 named modules as an alternative to #include-based consumption. Instead of using #include <winrt/Windows.Foundation.h>, you can use the import keyword.
Example:
import winrt.Windows.Foundation;To consume pre-built platform module IFCs from a referenced project, set the CppWinRTConsumeModule metadata to true on the ProjectReference.
C++20 modules do not allow circular imports. Because WinRT namespaces often have cyclic dependencies (e.g., Windows.Foundation and Windows.Foundation.Collections), C++/WinRT uses Strongly Connected Components (SCC) to consolidate cycles into a single module.
How it works:
.ixx file contains the declarations for all namespaces in that cycle. It uses forward declarations and ordered header includes to break the cycle..ixx file that simply uses export import to re-export the owner module.Result: Importing any namespace within the cycle (e.g., import winrt.Windows.Foundation; or import winrt.Windows.Foundation.Collections;) resolves to the same underlying module implementation.
To consume the shared modules produced by a Module Builder project, configure your consumer project's .vcxproj as follows:
<PropertyGroup>
<CppWinRTBuildModule>true</CppWinRTBuildModule>
<CppWinRTModuleInclude>MyCompany.MyComponent</CppWinRTModuleInclude>
<CppWinRTModuleExclude>Microsoft.UI;Microsoft.Web</CppWinRTModuleExclude>
</PropertyGroup>CppWinRTConsumeModule=true:<ItemGroup>
<ProjectReference Include="..\ModuleBuilder\ModuleBuilder.vcxproj">
<CppWinRTConsumeModule>true</CppWinRTConsumeModule>
</ProjectReference>
</ItemGroup>Setting CppWinRTConsumeModule to true tells the build system to use the builder's pre-built platform IFCs instead of re-compiling them locally.
<PropertyGroup>
<CppWinRTBuildModule>true</CppWinRTBuildModule>
<CppWinRTModuleInclude>MyCompany.MyComponent</CppWinRTModuleInclude>
<CppWinRTModuleExclude>Microsoft.UI;Microsoft.Web</CppWinRTModuleExclude>
</PropertyGroup>
<ItemGroup>
<ProjectReference Include="..\ModuleBuilder\ModuleBuilder.vcxproj">
<CppWinRTConsumeModule>true</CppWinRTConsumeModule>
</ProjectReference>
</ItemGroup>Windows.ApplicationModel.Core namespace to manage application lifecycle and core functionality in a code-only environment.To consume a third-party component provided as a .winmd file, follow these steps:
.winmd file you wish to consume.Generated Files subfolder.pch.h or source code to access the projected classes.For most developers, you should not build C++/WinRT from source. Instead, download and install the latest version using the official NuGet package to integrate the language projection into your Windows Runtime (WinRT) projects.
http://aka.ms/cppwinrt/nuget