C++20 module support v1 (import winrt;)

[DefaultRyan]

C++20 Module Support (import winrt;)

This PR adds C++20 named module support to C++/WinRT, allowing consumers to
write import winrt; instead of using #include directives and precompiled headers. In multi-project solutions, a shared module builder project compiles the platform projection once; consumer projects reference the pre-built module for significantly faster builds.

Quick overview

Two new MSBuild properties control module support:

• CppWinRTModuleBuild — Generates the platform SDK projection and compiles winrt.ixx. Set on a dedicated static library project (the "module builder"), or on a standalone project for single-project scenarios.
• CppWinRTModuleConsume — Consumes a pre-built module from a ProjectReference to a builder. The NuGet targets automatically resolve the IFC, OBJ, and include paths.

import winrt;
using namespace winrt::Windows::Foundation;

// Component types from a project reference (not in the module)
#include <winrt/MyComponent.h>

Design choices

Macro-driven, not flag-driven. Module-aware behavior in generated component files (.g.h, .g.cpp, module.g.cpp) is controlled by #ifdef WINRT_MODULE guards emitted by the code generator. The NuGet targets define WINRT_MODULE as a preprocessor definition — no special cppwinrt.exe command-line flag is needed. This means the same generated files work in both module and header mode without regeneration.

Boundary-based module guard. Each namespace header contains a "module guard" — a preprocessor block that checks whether the header's own namespace is in the module (via WINRT_MODULE_NS_<self>). If it IS in the module, the TU is doing a traditional #include (not via import), so the header falls through to #include "base.h" and all cross-dep guards are bypassed. If it is NOT in the module (e.g., a component header), the TU must have already done import winrt;, so the header uses base_macros.h only and cross-dep guards skip module namespaces. This means the same headers work in both module and traditional header mode without regeneration.

Per-namespace include guards with compound conditions. After import winrt;, consumers textually #include reference/component projection headers. Platform namespace deps (already in the module) must be skipped to avoid MSVC redeclaration errors, but component cross-namespace deps must NOT be skipped. Cross-namespace #include deps use compound guards — #if !defined(WINRT_MODULE_NS_<dep>) || defined(WINRT_MODULE_NS_<self>) — so deps in the module are skipped only when the including header is NOT itself in the module.

extern "C++" wrapping for include-then-import compatibility. The winrt.ixx module purview wraps all #include directives in extern "C++" { ... }, and namespace std blocks use WINRT_IMPL_EXTERN_CXX (which expands to extern "C++" in the ixx, empty in header mode). This gives declarations external C++ linkage so MSVC can merge textually-included declarations with module-exported declarations. This is critical for real-world codebases where 3rd-party headers (e.g., WIL's cppwinrt.h) #include winrt headers before user code does import winrt;.

Scoped import std;. import std; is NOT placed inside base.h because platform headers (<intrin.h>) transitively include STL headers, making a subsequent import std; unsafe. Instead, import std; is emitted at the TU level — in winrt.ixx (module purview), module.g.cpp, and .g.h files — controlled by the WINRT_IMPORT_STD macro.

Builder/consumer split. CppWinRTModuleBuild and CppWinRTModuleConsume are separate properties because in multi-project solutions, only one project should compile the expensive winrt.ixx. The CppWinRTGetModuleOutputs / CppWinRTResolveModuleReferences targets handle cross-project IFC/OBJ resolution via MSBuild's ProjectReference infrastructure.

import std; is orthogonal. import winrt; works with C++20. import std; is optional and independently controlled by the existing BuildStlModules property. On v143 (VS 2022), import std; requires /std:c++latest; on v145 (VS 2026), /std:c++20 suffices.

Exported winrt::impl namespace. The winrt::impl namespace is exported from the module alongside winrt. This is necessary because component projection headers specialize impl templates like category<>, abi<>, guid_v<>, and name_v<> for their types.

What's in this PR

Code generator (cppwinrt/):

• Generated component .g.h files use #ifdef WINRT_MODULE to import winrt; (and optionally import std;) before including component namespace headers
• Generated .g.cpp and module.g.cpp use #ifdef WINRT_MODULE / #ifndef WINRT_MODULE for import vs include paths
• winrt.ixx wraps the module purview in extern "C++" { ... }, defines WINRT_IMPL_EXTERN_CXX as extern "C++", and conditionally does import std;
• winrt_module_namespaces.h generated alongside winrt.ixx with per-namespace macros
• write_module_guard() — boundary-based: checks WINRT_MODULE_NS_<self> to decide between base_macros.h (import path) and base.h (traditional path)
• write_root_include_guarded() — compound guard: !defined(NS_dep) || defined(NS_self) for cross-namespace deps
• WINRT_IMPL_EXTERN_CXX applied to all namespace std blocks for module linkage compatibility
• Generated headers include inline comments explaining the module guard and cross-namespace guards
• import std; removed from base.h — only emitted in ixx/module.g.cpp/.g.h

NuGet targets (nuget/):

• CppWinRTBuildModule target — adds winrt.ixx to compilation, defines WINRT_MODULE and WINRT_IMPORT_STD
• CppWinRTGetModuleOutputs target — exports IFC/OBJ/GeneratedFilesDir for consumers
• CppWinRTResolveModuleReferences target — resolves module from ProjectReference items
• CppWinRTModuleBuild / CppWinRTModuleConsume properties in CppWinrtRules.Project.xml

NuGet test projects (test/nuget/):

• TestModuleBuilder — static lib, builds the module
• TestModuleConsumerApp — console app consuming the module + a component reference (multi-namespace, cross-namespace struct fields, platform type returns)
• TestModuleComponent — DLL with IDL, two namespaces, cross-namespace value type field, platform Uri return type
• TestModuleSingleProject — single project that builds and consumes its own module
• All module test projects include include_test.cpp — regression tests for include-with-WINRT_MODULE

Repo test projects (test/):

• test_cpp20_module / test_cpp20_module_winrt — C++20 module consumer/builder (no import std;)
• test_cpp23_module / test_cpp23_module_winrt — C++23 module consumer/builder (with import std;)
• test_component_module — component DLL with modules
• include_before_import_test.cpp — verifies #include before import winrt; works (extern "C++" coexistence)
• test_cpp20_module added to CI test matrix (all architectures, MSVC only)
• NuGet test consumer apps run as CI validation steps (fail on missing exe)

Documentation (docs/):

• modules.md — user-facing guide (Quick Start, properties, macros, architecture)
• modules-internals.md — maintainer guide (codegen pipeline, macro flow, extern "C++", boundary-based guards)
• nuget/readme.md — C++20 Modules section
• .github/instructions/modules.instructions.md — AI assistant instructions

Key macros

Macro	Scope	Purpose
WINRT_MODULE	Project-wide	Controls .g.h/.g.cpp/module.g.cpp behavior; activates boundary-based module guard in namespace headers
WINRT_BUILD_MODULE	winrt.ixx only	Set in ixx global module fragment; uses base_macros.h only
WINRT_MODULE_NS_*	winrt_module_namespaces.h	Per-namespace macros. Module guard and cross-dep guards use compound conditions
WINRT_IMPL_EXTERN_CXX	winrt.ixx purview	extern "C++" in module, empty in header mode. Applied to namespace std blocks
WINRT_IMPORT_STD	Project-wide (optional)	Enables import std; in winrt.ixx, .g.h, and module.g.cpp. Does NOT affect base.h

Current limitations

• The winrt module contains only platform SDK namespaces. NuGet WinMD references can be folded in via CppWinRTSDKReferences property on the builder project.
• import std; requires /std:c++latest on v143 toolset.
• import std; is NOT used inside base.h — platform headers transitively include STL headers first. Instead, import std; is at the TU level.
• Including a namespace header that IS in the module works — the module guard falls through to traditional #include "base.h" behavior.
• Including winrt headers BEFORE import winrt; works thanks to extern "C++" wrapping.

Future directions

• Investigate whether large WinMD references (e.g., WinUI) could be folded into the module via a dedicated CppWinRTModuleInput item group.
• Evaluate build time impact across real-world solutions.

Documentation

See docs/modules.md for the full user guide and docs/modules-internals.md for code generation internals.

Acknowledgements

Credit to @sylveon and @YexuanXiao for the trailblazing they've done in their forks, as well as their early feedback while this was in draft. Also @zadjii-msft and @Scottj1s for their earlier attempts and showing the potential build improvements.

[sylveon]

winrt_to_hresult_handler and friends needs WINRT_EXPORT extern "C++" to work properly when mixing non-modules and modules code in the same final DLL/EXE

[DefaultRyan]

I tested it locally. After enabling CppWinRTModule, compiling winrt.ixx.obj failed, showing that the symbol for CoGetCallContext could not be found. Manually linking Ole32.lib resolved the issue, but the header mode does not have this problem. I'm not sure what the cause is. Additionally, if both CppWinRTModule and BuildStlModule are enabled, it will break code that uses only header files.

You'll need to provide more info on how you configured your test project. I'm not hitting this in the test_cpp20_module project, even after adding some use of winrt::access_token.

[sylveon]

Idk about exporting the impl namespace, feel like we should find a better solution.

[YexuanXiao]

If exporting impl is unavoidable, I still hope to avoid a single winrt module. A slightly cleaner approach is to provide winrt.impl and winrt.base, where winrt.base imports winrt.impl but only re-exports non-impl declarations:

export module winrt.base;
import winrt.impl; // Not re-exported
export namespace winrt {
using winrt::hstring;
...
}

winrt.impl is intended for use only by files generated by cppwinrt, while user code should use winrt.base. And generate independent modules for each root namespace, such as winrt.Windows.

[sylveon]

My idea would be to generate the things required to produce as part of the module too, but that would eliminate the ability to share winrt.ifc between projects.

[YexuanXiao]

Damaging the development experience just to hide the implementation is completely not worth it in my opinion, especially since users can already access them through headers anyway. Considering only the development experience in Visual Studio, we could request the MSVC and IntelliSense teams to support an attribute such as [[msvc::internal]] to prevent IntelliSense from showing it.

[DefaultRyan]

OK, that compromise approach has worked! Update incoming...

• No more auto-import winrt; from namespace headers. We still write import winrt; for you in module.g.cpp and component.g.h.
• No more import std; from base.h. That now only happens in places where the TU is more controlled: the module purview in winrt.ixx, module.g.cpp, and component.g.h
• Top-level winrt headers that are present in the module, plus base.h can be included, even though it's preferred to import them from winrt. If you try to manually include them in a TU that has already imported the module, you'll almost certainly hit errors.
• Top-level winrt headers from outside the module (e.g. component projection) assume you've already imported the module if WINRT_MODULE is defined, and will not re-include stuff that's already in winrt.

[YexuanXiao]

I have to say, adding export to the outer scope of the partial specialization of std::coroutine_traits is indeed useful. I have successfully built a realistic WinUI3 project example that uses both include and import. I will publish it later.

[YexuanXiao]

I have published it at https://github.com/YexuanXiao/Authenticator/compare/module. It can be built using MSVC 14.51 and 14.52. It is not fully modularized yet, but it is sufficient to demonstrate feasibility.

[hoshiizumiya]

@sylveon Why not considerate @YexuanXiao 's modularized impletation. I hope we can accelerate modular process! And @YexuanXiao Why not give us a PR sample!

[YexuanXiao]

I have published it at https://github.com/YexuanXiao/Authenticator/compare/module. It can be built using MSVC 14.51 and 14.52. It is not fully modularized yet, but it is sufficient to demonstrate feasibility.

I have fully modularized the project. All .cpp files that require manual writing (including xaml.cpp) can be built entirely using modules without relying on header files.

The commit with the message "step1" mixes include and imports, while the commit with the message "step2" makes the project fully modularized (except for the cpp files generated by xamlc and module.g.cpp).

[DefaultRyan]

I have to say, adding export to the outer scope of the partial specialization of std::coroutine_traits is indeed useful. I have successfully built a realistic WinUI3 project example that uses both include and import. I will publish it later.

I'm curious to see a specific example of what you mean. Could you please share more details?

[YexuanXiao]

It is hard for me to give an explanation right now. Today I tried adding individual exports to every declaration instead of putting export before namespaces (about 800 changes, see https://github.com/YexuanXiao/cppwinrtplus/pull/58/files). But that broke my WinUI example in two ways, and I still can't fix it. I think we should add individual exports for each declaration, ship a version that doesn't support mixing #include and import, keep the codebase clean, and investigate further instead of inventing complicated workarounds.

[YexuanXiao]

I reported a new bug in MSVC. MSVC generates warning C4499 for a full specialization declaration with "export "C++": 'extern': an explicit specialization cannot have a storage class (ignored)". This issue can be reproduced without modules, and it is definitely a bug in MSVC because "export "C++"" is language linkage, but MSVC reports it as a storage class.
https://developercommunity.visualstudio.com/t/MSVC-refuses-to-add-linkage-specificatio/11077314
https://godbolt.org/z/qGEzd8Kvf
I have found another similar issue, MSVC generates warning C4630 for the "export "C++"" of the definition of a member function of a class template, stating that they cannot have a storage-class specifier.
https://developercommunity.visualstudio.com/t/MSVC-warns-C4630-for-the-language-linkag/11077315
https://godbolt.org/z/vczr5Kb45

[YexuanXiao]

@DefaultRyan I found that hstring_reference_flag is missing the inline modifier, which causes a redefinition error. I discovered this issue in the CI. #1571

[DefaultRyan]

It is hard for me to give an explanation right now. Today I tried adding individual exports to every declaration instead of putting export before namespaces (about 800 changes, see https://github.com/YexuanXiao/cppwinrtplus/pull/58/files). But that broke my WinUI example in two ways, and I still can't fix it. I think we should add individual exports for each declaration, ship a version that doesn't support mixing #include and import, keep the codebase clean, and investigate further instead of inventing complicated workarounds.

I did some work starting to port a real-world project C++/WinRT project to use modules, and we absolutely need some level of mixing, as there are widely-used dependencies that include cppwinrt headers. For example, WIL's cppwinrt.h includes <winrt/base.h>.

But good news, I went deeper on STL's usage of extern "C++" to workaround module redefinition/ownership issues when headers and modules are both present, and I got it working to the same level as STL. In a translation unit you can freely include cppwinrt headers before the module import, you just can't do it in the reverse order (import-then-include). I'm working on cleaning up and incorporating the codegen and will push another update.

So now, you just need to ensure those inclusions happen before the module import in a TU. This should be easy for most people, as those sorts of dependencies are typically wrapped up into a PCH, while the individual module imports should be happening in cpp files. If we start getting too many headers that themselves import instead of include, that's where things get brittle and bad, quickly.

I reported a new bug in MSVC. MSVC generates warning C4499 for a full specialization declaration with "export "C++": 'extern': an explicit specialization cannot have a storage class (ignored)". This issue can be reproduced without modules, and it is definitely a bug in MSVC because "export "C++"" is language linkage, but MSVC reports it as a storage class. https://developercommunity.visualstudio.com/t/MSVC-refuses-to-add-linkage-specificatio/11077314 https://godbolt.org/z/qGEzd8Kvf I have found another similar issue, MSVC generates warning C4630 for the "export "C++"" of the definition of a member function of a class template, stating that they cannot have a storage-class specifier. https://developercommunity.visualstudio.com/t/MSVC-warns-C4630-for-the-language-linkag/11077315 https://godbolt.org/z/vczr5Kb45

What is export "C++"? I think you meant extern "C++" or export extern "C++", right? I also had some trouble hitting C4630, but I got around it in the 17.44 tools by splitting export extern "C++" so now I wrap the whole namespace block in another language linkage block, like what the STL did.

extern "C++" {
  export namespace winrt {
  }
}

By doing this, I've gotten to the same level of compat as STL, as mentioned above.

[YexuanXiao]

I tried the latest commit, and I think we have reached a consensus on most issues. However, I still have some questions and suggestions.

First, WindowsNumerics.impl.h includes directxmath.h, and then includes WindowsNumerics.inl, which in turn includes stdexcept and limits. Therefore, the global module fragment of the winrt module must include stdexcept and limits in advance to avoid exporting them as part of the winrt module. Other standard library headers should not be used by winrt.ixx.

Currently, the generated winrt module both includes headers and imports std when WINRT_IMPORT_STD is defined, which appears to be a mistake.

Second, is winrt_module_namespaces.h still needed? Using extern "C++" is a simpler and more reliable approach.

Then, as @sylveon mentioned, template specializations should not be exported, so each declaration that needs to be exported should be marked with export, just as the STL does, rather than exporting coarsely by scope.

Finally, the winrt module should support legacy COM, which is necessary for WinUI3, and the headers and the module must consistently support them; otherwise, conflicting types will arise. I have added the WINRT_ENABLE_LEGACY_COM macro in my fork to control whether to include unknwn.h and inspectable.h.

[sylveon]

You can include directxmath.h in the global fragment, and then include WindowsNumerics.impl.h in the code. This is my approach.

[YexuanXiao]

You can include directxmath.h in the global fragment, and then include WindowsNumerics.impl.h in the code. This is my approach.

I haven't verified whether directxmath.h indirectly includes stdexcept and limits, but since directxmath.h and WindowsNumerics.inl are not maintained together, they should still be handled separately.

[YexuanXiao]

Additionally, base_xaml_component_connector_winui.h already has special handling for WinUI3. Since this has already happened, we should no longer argue about whether C++/WinRT needs to support WinUI3. I believe C++/WinRT 3.0 should port wil::resume_foreground back.

[DefaultRyan]

Second, is winrt_module_namespaces.h still needed? Using extern "C++" is a simpler and more reliable approach.

If my only concern was being able to tolerate including winrt headers, followed by importing the module, then I would have no worries. But...

Remember component authoring. Especially when we have a large solution, with many idl files creating winmds, scattered across multiple projects. These types are not going into the winrt module, so we are still including those headers. But those component types generally do depend on the platform types that are in the module, so they are going to be processed after import winrt;. `extern "C++" only helps with "include-then-import", but not "import-then-include".

Put another way:

// winrt/component.h

// My component's type has dependencies on, say, Windows.UI.Xaml.
#include <winrt/impl/Windows.UI.Xaml.2.h>

If I include winrt/component.h before import winrt;, it should compile, but dragging in these Windows.* dependency headers via text inclusion defeats the module build-time benefits (sharing a module between multiple projects instead of per-project PCH, compiled modules use far less disk space than the gigantic PCH). So, putting these component headers after the module import allows them to get their needed types from the module instead of textual include. But then, we need to prevent them from getting included, because "import-then-include" still doesn't work.

The alternative is just doing "all modules, everywhere", where the component projections also create all their own modules, and we generate them so they import the modules they need. Nobody ever includes winrt headers! There is some appeal to this idea, but it means dealing with the following:

• Not exporting duplicate definitions of the contents of base.h (refactor into winrt_base module.
• Do we export duplicate definitions of dependent types? (This is not rhetorical - I'm actually asking! Windows.Foundation.0.h stuff gets exported from winrt, but should it be exported from winrt.Component? If not, how complex is it to filter it out?)
• What to name all these different modules, and what happens if two different projects in a solution try to export the same conflicting module name.

[YexuanXiao]

Regarding the solution to the "import-then-include" problem, I implemented a solution in my own fork, because XAMLC currently only supports this mode. My approach is to set a general guard macro, WINRT_CONSUME_MODULE. When this macro is defined, all C++/WinRT headers expand to nothing. I have tested it and it works, even though XAMLC still includes some additional Windows headers for App.Xaml.h. See https://github.com/YexuanXiao/cppwinrtplus/blob/91b3b2e604d851de0f208cc699d3e18b42d58a5b/nuget/readme.md?plain=1#L167 and https://github.com/YexuanXiao/Authenticator/blob/277741b3e46a3287ed96b2940db35fe22aaaadaf/Authenticator/Authenticator/Window.xaml.cpp#L1.

This approach is simple enough, because the import already includes everything needed, so there's no need to include anything else. We can only control the winrt headers, and this method is sufficient to handle them.

This means that if someone decides to use the winrt module, they can simply define this macro on the first line of their .cpp file without overthinking it, and then the winrt module will take effect without any other winrt headers bothering them.

When XAMLC supports modules in the future, this macro can also be leveraged to change the generated code to the following form:

#ifdef WINRT_CONSUME_MODULE
import winrt;
#else
#include ...
#endif

This concept is very general and simple.

[DefaultRyan]

Regarding the solution to the "import-then-include" problem, I implemented a solution in my own fork, because XAMLC currently only supports this mode. My approach is to set a general guard macro, WINRT_CONSUME_MODULE. When this macro is defined, all C++/WinRT headers expand to nothing. I have tested it and it works, even though XAMLC still includes some additional Windows headers for App.Xaml.h. See https://github.com/YexuanXiao/cppwinrtplus/blob/91b3b2e604d851de0f208cc699d3e18b42d58a5b/nuget/readme.md?plain=1#L167 and https://github.com/YexuanXiao/Authenticator/blob/277741b3e46a3287ed96b2940db35fe22aaaadaf/Authenticator/Authenticator/Window.xaml.cpp#L1.

This approach is simple enough, because the import already includes everything needed, so there's no need to include anything else. We can only control the winrt headers, and this method is sufficient to handle them.

This means that if someone decides to use the winrt module, they can simply define this macro on the first line of their .cpp file without overthinking it, and then the winrt module will take effect without any other winrt headers bothering them.

When XAMLC supports modules in the future, this macro can also be leveraged to change the generated code to the following form:

#ifdef WINRT_CONSUME_MODULE
import winrt;
#else
#include ...
#endif

This concept is very general and simple.

I had something like that early on, but I think it was clashing with some other parts of the approach I was taking. Now that I've gone down the road of modularizing almost half of the Terminal project, I'm thinking of going back that way.

In fact, as I'm thinking of how to resolve some of the other pain points I'm hitting in the Terminal project, I keep coming back to "maybe the component projections should also be modules", which leads to "if we have multiple modules, we need to split out base to re-export" as well as "how do we name the different modules, and maybe we should be less monolithic". Which leads to some of the design decisions in your fork.

Some parts still give me pause - I don't fully see what the user-experience is around the cycle-breaking SCCs. Can I import Windows.Foo.Bar, or do I need to import all of Windows.Foo? Which namespace modules can I actually import? If more APIs are added that change the namespace graph, will the SCC partition namespaces differently and cause customer code to break because now they are importing the wrong namespace partitions?

But I was encouraged by the overall reduced friction of using it in your Authenticator repo.

[YexuanXiao]

In fact, as I'm thinking of how to resolve some of the other pain points I'm hitting in the Terminal project, I keep coming back to "maybe the component projections should also be modules", which leads to "if we have multiple modules, we need to split out base to re-export" as well as "how do we name the different modules, and maybe we should be less monolithic". Which leads to some of the design decisions in your fork.

Some parts still give me pause - I don't fully see what the user-experience is around the cycle-breaking SCCs. Can I import Windows.Foo.Bar, or do I need to import all of Windows.Foo? Which namespace modules can I actually import? If more APIs are added that change the namespace graph, will the SCC partition namespaces differently and cause customer code to break because now they are importing the wrong namespace partitions?

My original idea was to increase parallelism, reduce recompilation, and achieve a C#-like experience, and implementing a separate module for each namespace was the most straightforward approach I could think of. I also considered that changes to dependencies might break user code, but since I've already implemented it, so be it. I now think converting top-level namespaces to lowercase and adding a winrt prefix is also a good choice, and in the future we can further consider using module partitions to implement each module. I will continue to investigate how to make include and import coexist, just like in the STL.

[YexuanXiao]

I reported a new bug in MSVC. MSVC generates warning C4499 for a full specialization declaration with "export "C++": 'extern': an explicit specialization cannot have a storage class (ignored)". This issue can be reproduced without modules, and it is definitely a bug in MSVC because "export "C++"" is language linkage, but MSVC reports it as a storage class. https://developercommunity.visualstudio.com/t/MSVC-refuses-to-add-linkage-specificatio/11077314 https://godbolt.org/z/qGEzd8Kvf I have found another similar issue, MSVC generates warning C4630 for the "export "C++"" of the definition of a member function of a class template, stating that they cannot have a storage-class specifier. https://developercommunity.visualstudio.com/t/MSVC-warns-C4630-for-the-language-linkag/11077315 https://godbolt.org/z/vczr5Kb45

The MSVC Preview has fixed this issue, and the _MSC_FULL_VER is 195236314.

[DefaultRyan]

I'm going to put this PR on hold for a little bit. What I'm doing instead is adapting the "all-in on modules" approach used in @YexuanXiao 's cppwinrtplus fork, and will open up a fresh v2 PR using this approach. I've been kicking the tires on it and the per-namespace module approach seems pretty sound. I have a basic version working already, and am in the process of adding tests and trying it out in multi-project solutions.