microsoft / microsoft/WindowsAppSDK

Add a plain C++/WinRT Runtime Class item template for WinUI projects

Open
#6,689 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

area-WinAppSDK:Templates needs-triage
Dominant language
C++
Stars
4.7k
Forks
471
Avg merge
3d 13h
Merged PRs (30d)
28

Description

### Feature proposal

Please add a plain C++/WinRT Runtime Class item template for WinUI / Windows App SDK C++ projects.

The existing C++/WinRT WinUI item templates are primarily XAML UI concepts, such as:
- Page
- User Control
- Templated Control

but there is no convenient Add New Item template for creating an ordinary WinRT runtimeclass inside an existing WinUI C++ project.

---

### Why Templated Control is not a replacement

A Templated Control represents a specific XAML control pattern:
```idl
runtimeclass MyControl : Microsoft.UI.Xaml.Controls.Control
{
MyControl();
}
```
It is expected to have:
```cpp
DefaultStyleKey(...)
```

and a default `Style` / `ControlTemplate`, usually placed in `Themes/Generic.xaml`. That behavior is correct for a real custom Control.
However, many WinRT types used by a WinUI application are not templated Controls.

Examples include:
- attached-property providers;
- markup-extension-like runtime classes;
- DependencyObject-derived helper types;
- XAML-facing model or collection types;
- Composition/XAML effect types;
- ordinary WinRT runtime classes;
- helper runtime classes that need metadata visibility but no visual template.

For example:

```idl
namespace MyApp.UI.Xaml.Markup
{
runtimeclass UInt32Extension
{
UInt32Extension();
}
}
```

or:

```idl
namespace MyApp.UI.Xaml.Control.Effect
{
runtimeclass AnimatedValue
{
AnimatedValue();
String Value;
}
}
```

These types need the normal C++/WinRT component implementation pattern, but they do not need a `ControlTemplate`, `DefaultStyleKey`, or modifications to `Themes/Generic.xaml`.

Using the Templated Control item as a starting point therefore creates XAML-control-specific artifacts which have to be manually removed.

---

### Proposed item

For example:

```text
C++/WinRT Runtime Class
```

or:

```text
Windows Runtime Class (C++/WinRT)
```

The item would generate:

```text
MyType.idl
MyType.h
MyType.cpp
```

with a standard C++/WinRT producing-component skeleton.

Conceptually:

```idl
namespace MyProject.Some.Namespace
{
runtimeclass MyType
{
MyType();
}
}
```

```cpp
#pragma once

#include ".g.h"

namespace winrt::MyProject::Some::Namespace::implementation
{
struct MyType : MyTypeT
{
MyType();
};
}
```

and:

```cpp
#include "pch.h"
#include "MyType.h"

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

---

### Project subfolders should be supported

The template should also correctly support Add New Item from a nested project folder.

For example:

```text
MyProject
└─ UI
└─ Xaml
└─ Markup
└─ Add > New Item > C++/WinRT Runtime Class
```

with the user entering only:

```text
UInt32Extension
```

should produce the runtime type:

```text
MyProject.UI.Xaml.Markup.UInt32Extension
```

while keeping the physical filenames as:

```text
UInt32Extension.idl
UInt32Extension.h
UInt32Extension.cpp
```

This is related to: #6688 , which tracks the existing C++/WinRT item templates incorrectly handling namespace/generated-file paths for items created in project subfolders.

---

### XAML integration

A plain runtimeclass item should not automatically create a XAML file or a default style.

If the runtimeclass is later consumed by XAML, the existing XAML metadata pipeline should discover it through its normal WinRT/XAML type metadata mechanisms.

XAML-specific resources should only be generated by item types that actually require them.

---

### C++/WinRT 3.x compatibility

If possible, the new item should also be compatible with both:

- traditional C++/WinRT projection headers;
- C++/WinRT 3.x C++20 module-enabled projects.

This does not necessarily mean the item template itself has to implement the entire XAML/module integration story, but it should not assume that all projects use only textual `#include ` projections.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by comparing the existing C++/WinRT WinUI item templates with the proposed MyType.idl, MyType.h, and MyType.cpp outputs, then review issue #6688 for the nested-folder namespace and generated-path problem. Done means a plain runtime-class template creates only the three listed files, derives the namespace from the project folder, avoids Themes/Generic.xaml and XAML files, and remains compatible with the stated C++/WinRT project modes.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
desktop, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.