Add a C++/WinRT 3.x module-ready option/project template for WinUI C++ projects

Feature proposal

Please add an officially supported C++/WinRT 3.x C++20 module-ready project configuration/template for WinUI C++ projects.

C++/WinRT 3.x now supports per-namespace C++20 named modules such as:

import winrt.Windows.Foundation;
import winrt.Microsoft.UI.Xaml;
import winrt.Microsoft.UI.Xaml.Controls;

through:

<CppWinRTBuildModule>true</CppWinRTBuildModule>

However, the current Windows App SDK C++ project templates are still designed entirely around the traditional projection-header + PCH model.

This makes creating a new WinUI C++ project and migrating it to C++/WinRT modules a substantial manual operation.

---

Current Windows App SDK template

The current C++ Blank App template already selects the C++20-capable VS 2026 toolchain:

<PlatformToolset Condition="'$(VisualStudioVersion)' >= '18.0'">
  v145
</PlatformToolset>

<LanguageStandard Condition="'$(VisualStudioVersion)' >= '18.0'">
  stdcpp20
</LanguageStandard>

but the project remains configured around a traditional PCH:

<PrecompiledHeader>Use</PrecompiledHeader>
<PrecompiledHeaderFile>pch.h</PrecompiledHeaderFile>

and does not enable:

<CppWinRTBuildModule>true</CppWinRTBuildModule>
<BuildStlModules>true</BuildStlModules>

The generated pch.h also textually includes a large set of C++/WinRT projection headers:

#include <winrt/Windows.Foundation.h>
#include <winrt/Windows.Foundation.Collections.h>
#include <winrt/Windows.ApplicationModel.Activation.h>
#include <winrt/Microsoft.UI.Composition.h>
#include <winrt/Microsoft.UI.Xaml.h>
#include <winrt/Microsoft.UI.Xaml.Controls.h>
#include <winrt/Microsoft.UI.Xaml.Controls.Primitives.h>
#include <winrt/Microsoft.UI.Xaml.Data.h>
#include <winrt/Microsoft.UI.Xaml.Interop.h>
#include <winrt/Microsoft.UI.Xaml.Markup.h>
#include <winrt/Microsoft.UI.Xaml.Media.h>
#include <winrt/Microsoft.UI.Xaml.Navigation.h>
#include <winrt/Microsoft.UI.Xaml.Shapes.h>
#include <winrt/Microsoft.UI.Dispatching.h>

#include <wil/cppwinrt_helpers.h>

This is appropriate for the traditional header-based projection model, but is not a module-ready starting point.

---

Why enabling CppWinRTBuildModule is not enough

The C++/WinRT 3.x module documentation describes several additional requirements for a module-based project.

In particular:

• WinRT imports must not be placed inside the PCH;
• WinRT projection headers need to be moved out of the traditional PCH model;
• a module/import boundary needs to be established;
• WINRT_IMPORT_MODULE may be required when interoperating with code that
  textually includes C++/WinRT headers;
• XAML-generated source files require special handling because the XAML
  compiler currently emits module-unaware C++.

Documentation:

https://github.com/microsoft/cppwinrt/blob/master/nuget/modules.md

Therefore adding only:

<CppWinRTBuildModule>true</CppWinRTBuildModule>

to a project created by the current template does not provide a complete module-ready WinUI project structure.

---

Runtime Component template has the same issue

The current C++/WinRT Runtime Component project template is also based on:

<PrecompiledHeader>Use</PrecompiledHeader>
<PrecompiledHeaderFile>pch.h</PrecompiledHeaderFile>

and generated implementation files follow the traditional form:

#include "pch.h"
#include "Class.h"

#if __has_include("Class.g.cpp")
#include "Class.g.cpp"
#endif

There is currently no equivalent module-enabled Runtime Component template or project option.

---

Real-world migration example

I converted a non-trivial WinUI 3 C++/WinRT application to C++/WinRT 3.x modules:

https://github.com/hoshiizumiya/OpenNet/commit/92dacc87cefe4a3ee29e46c23c1c3490108ac42a

The migration required significantly more than setting CppWinRTBuildModule=true.

Among other changes, the project needed to:

• enable CppWinRTBuildModule;
• enable STL modules;
• remove the traditional WinRT-heavy PCH dependency;
• establish module import boundaries;
• provide module imports for hand-written XAML implementation files;
• handle generated XAML translation units separately;
• inject module setup into generated XAML metadata sources.

The XAML-generated-code part is a separate XAML compiler integration issue and does not need to be solved entirely by the project template itself, but the current project templates do not provide even the module-ready C++ side of the configuration.

---

Suggested behavior

This does not necessarily need to replace the existing header-based templates.

An opt-in experience would be sufficient, for example:

WinUI Blank App (C++/WinRT)
    [ ] Use C++/WinRT C++20 modules

or separate templates such as:

Blank App, Packaged (WinUI 3 in Desktop, C++/WinRT)
Blank App, Packaged (WinUI 3 in Desktop, C++/WinRT Modules)

A module-ready project would ideally configure at least:

<CppWinRTBuildModule>true</CppWinRTBuildModule>
<BuildStlModules>true</BuildStlModules>

and use an appropriate project structure in which C++/WinRT projection declarations are consumed through generated named modules rather than being placed in the traditional projection-heavy PCH.

The exact structure should follow the supported C++/WinRT 3.x module guidelines rather than requiring every application to independently recreate that configuration.

---

Item templates should also remain compatible

This should also be considered together with C++/WinRT item templates.

For example, generated Page/UserControl/Window/Runtime Class/Templated Control items should not assume that the containing project consumes all WinRT projections through traditional PCH/header inclusion.

This is separate from the nested-folder namespace/generated-path problem tracked in: #6688 and separate from the XAML compiler's module-awareness problem.

The three issues concern different layers:

1. project/item templates provide a module-ready C++ project structure;
2. C++/WinRT generates the named projection modules;
3. the XAML compiler/build pipeline consumes those modules correctly.

Start with the C++/WinRT modules.md guidance and compare the current Windows App SDK C++ Blank App and Runtime Component templates, including their project XML, pch.h, and generated implementation files. Done means an opt-in module-ready project/template structure enables the required module settings without relying on a projection-heavy PCH, while remaining compatible with the mentioned item templates.