Skip to content

Updated README and CONTRIBUTING #2080

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Updated README and CONTRIBUTING #2080

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c970859
Init
0x5bfa Oct 15, 2025
7f26c61
Update and fix
0x5bfa Oct 16, 2025
8a71e2a
Update README
0x5bfa Oct 16, 2025
407e2c2
Update
0x5bfa Oct 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
165 changes: 83 additions & 82 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,119 +1,120 @@
# C#/WinRT Contributor's Guide

Below is our guidance for how to build the repo, report issues, propose new features, and submit contributions via Pull Requests (PRs).
This guide explains how to report issues, propose features, build the repository, and submit PRs.

## Building the C#/WinRT repo
1. [Find or File an Issue First](#find-or-file-an-issue-first)
2. [Working on a Fix or Feature After Approvals](#working-on-a-fix-or-feature-after-approvals)
3. [Building the repo](#building-the-repo)

C#/WinRT currently requires the following packages, or newer, to build:
## Find or File an Issue First

- [Visual Studio 17.0](https://visualstudio.microsoft.com/downloads/)
- [.NET 8.0 SDK](https://dotnet.microsoft.com/download/dotnet/8.0)
- [nuget.exe 5.8.0-preview.3](https://www.nuget.org/downloads)
- Microsoft.WinUI 3.0.0-preview4.210210.4
- Microsoft.WindowsAppSDK 1.1.5
Before starting any work to submit a PR, **find or file an issue first**. This ensures no duplicated effort and keeps collaboration efficient.

The [`build.cmd`](src/build.cmd) script takes care of all related configuration steps and is the simplest way to get started building C#/WinRT. It installs prerequisites such as `nuget.exe` and the .NET 6 SDK, configures the environment to use .NET 6 (creating a `global.json` if necessary), builds the compiler, and builds and executes the unit tests. To build C#/WinRT, follow these steps:
Check both open and closed issues before filing a new one. If none matches your case, file a new issue.

- Open a Visual Studio Developer command prompt pointing at the repo.
- Run `src\build.cmd`.
- To launch the project in Visual Studio, run `devenv src\cswinrt.sln` from the same command prompt. This will inherit the necessary environment.
### When to File an Issue

**Note:** By default, the projects for various [Projections](src/Projections) only generate source files for Release configurations, where `cswinrt.exe` can execute in seconds. To generate sources for the [Projections](src/Projections) projects on Debug configurations, set the project property `GenerateTestProjection` to `true`. This configuration permits a faster inner loop in Visual Studio. In either case, existing projection sources under the "Generated Files" folder will still be compiled into the projection assembly.
* Unsure if it’s a bug or feature request
* → [File an Issue](https://github.com/microsoft/CsWinRT/issues/new/choose)
* Have a question not answered in the docs
* → [Post a Discussion](https://github.com/microsoft/CsWinRT/discussions)
* Want to propose or confirm a planned feature
* → [Post a Discussion](https://github.com/microsoft/CsWinRT/discussions)

### Customizing `build.cmd` options

There are several settings that can be set with `build.cmd` that you might not know about without studying the code. The build settings and defaults are as follows.

```cmd
build.cmd [Platform] [Configuration] [VersionNumber] [VersionString] [AssemblyVersion]
```
### What to Describe

| Parameter | Value(s) |
|-|-|
| Platform | *x64 \| x86 | Default is `x64`
| Configuration | *Release \| Debug |
| VersionNumber | *0.0.0.0 |
| VersionString | *0.0.0-private.0 |
| AssemblyVersion | *0.0.0.0 |
\*Default value
* Versions of .NET, C#/WinRT, and SDK projections
* Tools and IDEs used (e.g., VS 2022, VS Code)
* Build version of Windows used
* **Detailed reproduction steps** (most important)
* Full error text or screenshots
* Note if you plan to implement the fix/feature yourself

**Examples**
> [!IMPORTANT]
> **DO NOT** post "+1", "me too", or similar comments ー they just add noise to an issue.
> If you don't have any additional info/context to add but would like to indicate that you're affected by the issue, upvote the original issue by reacting with 😊 or 👍 (+1) emoji and post your context if necessary. This way we can actually measure how impactful an issue is.

- Building in Release mode for platform x64, and creates a 0.0.0-private.0.nupkg
```cmd
build.cmd
```
- Building in Debug mode for platform x86, and creates a 0.0.0-private.0.nupkg
```cmd
build.cmd x86 Debug
```
- Building in Debug mode for platform x64, and creates a 2.0.0-mycswinrt.0.nupkg that has `WinRT.Runtime` with AssemblyVersion of 2.0.0.0
```cmd
build.cmd x64 Debug 2.0.0.0 2.0.0-mycswinrt.0 2.0.0.0
```
This is useful if you want to quickly confirm that your private .nupkg is being used by checking the `WinRT.Runtime` assembly version.
## Working on a Fix or Feature After Approvals

## Before you start, file an issue
### 1. Fork and Branch

Please follow this simple rule to help us eliminate any unnecessary wasted effort & frustration, and ensure an efficient and effective use of everyone's time - yours, ours, and other community members':
After your proposal is discussed and approved:

> 👉 If you have a question, think you've discovered an issue, would like to propose a new feature, etc., then find/file an issue **BEFORE** starting work to fix/implement it.
1. Fork the repo
2. Clone your fork
3. Create and push a feature branch
4. Implement your changes
5. Test your changes on your local
6. Submit a Pull Request (PR)

### Search Existing Issues First
### 2. Agree with CLA

Before filing a new issue, search existing open and closed issues first: It is likely someone else has found the problem you're seeing, and someone may be working on or have already contributed a fix!
Most contributions require signing a [Contributor License Agreement (CLA)](https://cla.opensource.microsoft.com), confirming that you own the rights to your contribution and grant Microsoft permission to use it.

If no existing item describes your issue/feature, great - please file a new issue:
When you open a pull request, the CLA bot automatically checks whether a signature is required and updates the PR with a status or comment.
Follow the bot’s instructions if prompted. You only need to complete this process once for all Microsoft repositories that use the CLA bot.

### File a New Issue
### 3. Code Review

* Don't know whether you're reporting an issue or requesting a feature? File an issue
* Have a question that you don't see answered in docs, videos, etc.? File an issue
* Want to know if we're planning on building a particular feature? File an issue
* Found an existing issue that describes yours? Great - upvote and add additional commentary / info / repro-steps / etc.
Mark your PR as "Ready for Review" when it’s ready for feedback from the team and the community. It may take several review cycles to ensure correctness and stability.

### Include Issue Details
### 4. Merge

**Please include as much information as possible in your issue**. The more information you provide, the more likely your issue/ask will be understood and implemented. Helpful information includes:
After approvals, your PR will be merged into the main branch and automatically closed.

* What versions of .NET, C#/WinRT, and the SDK Projection you're using
* What tools and apps you're using (e.g. VS 2019, VSCode, etc.)
* What build of Windows your device is running
* Don't assume we're experts in setting up YOUR environment and don't assume we are experts in YOUR workflow. Teach us to help you!
* **We LOVE detailed repro steps!** What steps do we need to take to reproduce the issue? Assume we love to read repro steps. As much detail as you can stand is probably _barely_ enough detail for us!
* Prefer error message text where possible or screenshots of errors if text cannot be captured
* **If you intend to implement the fix/feature yourself then say so!** If you do not indicate otherwise we will assume that the issue is ours to solve, or may label the issue as `Help-Wanted`.
Thank you in advance for your contribution!

### DO NOT post "+1" comments
## Building the repo

> ⚠ DO NOT post "+1", "me too", or similar comments - they just add noise to an issue.
### Prerequisites

If you don't have any additional info/context to add but would like to indicate that you're affected by the issue, upvote the original issue by clicking its [+😊] button and hitting 👍 (+1) icon. This way we can actually measure how impactful an issue is.
- [Visual Studio 2022](https://visualstudio.microsoft.com/downloads/)
- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet)

---
### Build steps

## Development

### Fork, Clone, Branch and Create your PR
1. Open a Visual Studio Developer command prompt in the repo root.
2. Run a script to install dependencies, set up the environment, build the compiler, and run unit tests.
```
src\build.cmd
```
3. (Optional) Open the solution in Visual Studio. This will inherit the necessary environment.
```
devenv src\cswinrt.sln
```

Once you've discussed your proposed feature/fix/etc. with a team member, and you've agreed on an approach or a spec has been written and approved, it's time to start development:
> [!NOTE]
> Projection projects under `src/Projections` only generate sources in `Release` by default. To generate them in `Debug`, set the property `GenerateTestProjection` to `true`. This configuration will enable a faster inner loop in Visual Studio. "Generated Files" remain under the Generated Files folder regardless of configuration.

1. Fork the repo if you haven't already
1. Clone your fork locally
1. Create & push a feature branch
1. Create a Pull Request
1. Work on your changes
### Customizing `build.cmd` options

### Code Review
You can specify platform, configuration, and version parameters:

When you'd like the team to take a look, (even if the work is not yet fully complete), mark the PR as 'Ready For Review' so that the team can review your work and provide comments, suggestions, and request changes. It may take several cycles, but the end result will be solid, testable, conformant code that is safe for us to merge.
```cmd
build.cmd [Platform] [Configuration] [VersionNumber] [VersionString] [AssemblyVersion]
```

### Merge
| Parameter | Values | Default
|-|-|-|
| Platform | `x64 \| x86` | `x64` |
| Configuration | `Release \| Debug` | `Release` |
| VersionNumber | \* | `0.0.0.0` |
| VersionString | \* | `0.0.0-private.0` |
| AssemblyVersion |\* | `0.0.0.0` |

Once your code has been reviewed and approved by the requisite number of team members, it will be merged into the master branch. Once merged, your PR will be automatically closed.
Building in `Release` for `x64`, and creates `0.0.0-private.0.nupkg`
```cmd
build.cmd
```

---
Building in `Debug` for `x86`, and creates `0.0.0-private.0.nupkg`
```cmd
build.cmd x86 Debug
```

## Thank you
Building in `Debug` for `x64`, and creates `2.0.0-mycswinrt.0.nupkg` that has `WinRT.Runtime` with AssemblyVersion of `2.0.0.0`
```cmd
build.cmd x64 Debug 2.0.0.0 2.0.0-mycswinrt.0 2.0.0.0
```

Thank you in advance for your contribution!
This is useful if you want to quickly confirm that your private .nupkg is being used by checking the `WinRT.Runtime` assembly version.
81 changes: 26 additions & 55 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,69 +1,40 @@
[![Build Status](https://dev.azure.com/microsoft/Dart/_apis/build/status%2FCsWinRT%20GitHub%20CI?branchName=master)](https://dev.azure.com/microsoft/Dart/_build/latest?definitionId=112455&branchName=master)
<h1 align="center">C#/WinRT Language Projection</h1>

# The C#/WinRT Language Projection
<p align="center">
<a style="text-decoration:none" href="https://www.nuget.org/packages/Microsoft.Windows.CsWinRT">
<img src="https://img.shields.io/nuget/v/Microsoft.Windows.CsWinRT" alt="NuGet badge" /></a>
</p>

C#/WinRT provides Windows Runtime (WinRT) projection support for the C# language. A "projection" is an adapter that enables programming the WinRT APIs in a natural and familiar way for the target language. The C#/WinRT projection hides the details of interop between C# and WinRT interfaces, and provides mappings of many WinRT types to appropriate .NET equivalents, such as strings, URIs, common value types, and generic collections.
C#/WinRT provides **Windows Runtime (WinRT) API** projection support for C#. A *projection* is an adapter that lets developers use WinRT APIs naturally in their language of choice. The C#/WinRT projection abstracts interop details and maps WinRT types to their .NET equivalents, such as strings, URIs, value types, and generic collections.

WinRT APIs are defined in `*.winmd` format, and C#/WinRT includes tooling that generates C# code for consumption scenarios, or generates a `*.winmd` for authoring scenarios. Generated C# source code can be compiled into interop assemblies, similar to how [C++/WinRT](https://github.com/Microsoft/cppwinrt) generates headers for the C++ language projection. This means that neither the C# compiler nor the .NET Runtime require built-in knowledge of WinRT any longer.
C#/WinRT includes tools that:
- Generate C# source for consuming WinRT APIs from `*.winmd` files
- Generate `*.winmd` files for authoring WinRT components

## Motivation
Generated C# source can be compiled into interop assemblies, similar to how [C++/WinRT](https://github.com/Microsoft/cppwinrt) produces headers for C++. This design removes the need for the C# compiler or .NET runtime to have built-in WinRT support.

[.NET Core](https://docs.microsoft.com/en-us/dotnet/core/) is the focus for the .NET platform. It is an open-source, cross-platform runtime that can be used to build device, cloud, and IoT applications. Previous versions of .NET Framework and .NET Core have built-in knowledge of WinRT which is a Windows-specific technology. By lifting this projection support out of the compiler and runtime, we are supporting efforts to make .NET more efficient for .NET 5 onwards.
## Getting started

[WinUI 3](https://github.com/Microsoft/microsoft-ui-xaml) is the effort to lift official native Microsoft UI controls and features out of the operating system, so app developers can use the latest controls and visuals on any in-market version of the OS. C#/WinRT is needed to support the changes required for lifting the XAML APIs out of Windows.UI.XAML and into Microsoft.UI.XAML.
- [Usage guide](docs/usage.md)
- [Customizing C#/WinRT](nuget/readme.md)
- [NativeAOT and Trimming support](docs/aot-trimming.md)
- [Authoring C#/WinRT components](docs/authoring.md)
- [About WinRT.Host.dll](docs/hosting.md)
- [C#/WinRT version history](docs/version-history.md)
- [Repository structure](docs/structure.md)
- [COM Interop guide](docs/interop.md)
- Related projects
- [xlang](https://github.com/microsoft/xlang)
- [Windows App SDK](https://github.com/microsoft/WindowsAppSDK)

However, C#/WinRT is a general effort and is intended to support other scenarios and versions of the .NET runtime. While our focus is on supporting .NET 5, we aspire to generate projections that are compatible down to .NET Standard 2.0. Please refer to our issues backlog for more information.

## What's New

See our [release notes](https://github.com/microsoft/CsWinRT/releases) for the latest C#/WinRT releases and corresponding .NET SDK versions. C#/WinRT runtime and Windows SDK projection updates typically become available in a future .NET SDK update, which follows a monthly release cadence. We also make updates to the C#/WinRT tool itself, which are shipped through the C#/WinRT NuGet package. Details on breaking changes and specific issues can be found in the releases notes.

## Using C#/WinRT

Download the C#/WinRT NuGet package here: https://www.nuget.org/packages/Microsoft.Windows.CsWinRT/

You can also build a C#/WinRT package yourself from source: see our [Contributor's Guide](CONTRIBUTING.md) for more information on building the repo.

### Documentation

- [Usage guide](docs/usage.md) - usage guide for developers
- [C#/WinRT NuGet properties](nuget/readme.md) - documentation on customizing C#/WinRT NuGet package properties
- [Repository structure](docs/structure.md) - detailed breakdown of this repository
- [COM Interop guide](docs/interop.md) - for recommendations on migrating from System.Runtime.InteropServices

For additional documentation and walkthroughs, visit <http://aka.ms/cswinrt>.

### C#/WinRT Architecture

The C#/WinRT runtime assembly, `WinRT.Runtime.dll`, is required by all C#/WinRT assemblies. It provides an abstraction layer over the .NET runtime, supporting .NET 5+. The runtime assembly implements several features for all projected C#/WinRT types, including WinRT activation, marshaling logic, and [COM wrapper](https://docs.microsoft.com/dotnet/standard/native-interop/com-wrappers) lifetime management.
For additional documentation and walkthroughs, visit http://aka.ms/cswinrt.

## Contributing

The C#/WinRT team welcomes feedback and contributions! There are several ways to contribute to the project:

- **[File a new issue](https://github.com/microsoft/CsWinRT/issues/new/choose)**<br>
- **[Ask a question](https://github.com/microsoft/CsWinRT/discussions/categories/q-a)**<br>
- **[Start a discussion](https://github.com/microsoft/CsWinRT/discussions)**<br>
- **[Make a feature request](https://github.com/microsoft/CsWinRT/issues/new?assignees=&labels=enhancement&template=feature_request.md&title=)**<br>

We ask that **before you start work on a feature that you would like to contribute**, please read our [Contributor's Guide](CONTRIBUTING.md), which also includes steps on building the C#/WinRT repo.

## Related Projects

C#/WinRT is part of the [xlang](https://github.com/microsoft/xlang) family of projects that help developers create APIs that can run on multiple platforms and be used with a variety of languages. The mission of C#/WinRT is not to support cross-platform execution directly, but to support the cross-platform goals of .NET Core.

C#/WinRT is also part of the [Windows App SDK](https://github.com/microsoft/WindowsAppSDK) - a set of libraries, frameworks, components, and tools that you can use in your apps to access powerful platform functionality across many versions of Windows. The Windows App SDK combines Win32 native app capabilities with modern API usage techniques, so your apps light up everywhere your users are. The Windows App SDK also includes [WinUI](https://docs.microsoft.com/en-us/windows/apps/winui/), [WebView2](https://docs.microsoft.com/en-us/microsoft-edge/webview2/), [MSIX](https://docs.microsoft.com/en-us/windows/msix/overview), [C++/WinRT](https://github.com/microsoft/CppWinRT/), and [Rust/WinRT](https://github.com/microsoft/winrt-rs).

### License Info

Most contributions require you to agree to a
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
We welcome feedback and contributions! We ask that **before you start work on a feature that you would like to contribute**, please read our [Contributor's Guide](CONTRIBUTING.md).

## Code of Conduct

This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
contact [[email protected]](mailto:[email protected]) with any additional questions or comments.

For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments.