GitPlanet

Cheap and reliable Node.js hosting starts at $3/month, and $1/month static HTML hosting

Created with love in Canada, visit hostnodejs.com today

Feel like to post an Ad? Learn Details
All Projects → microsoft → Cswinrt

microsoft / Cswinrt

Licence: mit
C# language projection for the Windows Runtime

Build status

The C#/WinRT Language Projection

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.

WinRT APIs are defined in *.winmd format, and C#/WinRT includes tooling that generates C# code that can be compiled into interop assemblies, similar to how C++/WinRT 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 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 lifetime management.

Create and distribute an interop assembly

Component authors need to build a C#/WinRT projection assembly for .NET5+ consumers. In the diagram below, the cswinrt.exe tool processes Windows Metadata (*.winmd) files in the "Contoso" namespace to create projection source files. These source files are then compiled into an interop projection assembly named Contoso.projection.dll. The projection assembly must be distributed along with the implementation assemblies (Contoso.*.dll) as a NuGet package.

Creating projection

Reference an interop assembly

Application developers on .NET5+ can reference C#/WinRT interop assemblies by adding a reference to the interop NuGet package. This replaces any *.winmd references. The .NET5+ application includes WinRT.Runtime.dll which handles WinRT type activation logic.

Adding projection

Motivation

.NET 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 its .NET 5 release.

WinUI3.0 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.

However, C#/WinRT is a general effort and is intended to support other scenarios and versions of the .NET runtime, compatible down to .NET Standard 2.0.

Usage and Developer Guidance

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

Please read the usage and repository structure docs for a detailed breakdown. For recommendations on migrating from System.Runtime.InteropServices, see the COM Interop guide. For additional documentation and walkthroughs, visit http://aka.ms/cswinrt.

Building and running C#/WinRT

C#/WinRT currently requires the following packages, or newer, to build:

The 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 and the .NET 5 SDK, configures the environment to use .NET 5 (creating a global.json if necessary), builds the compiler, and builds and executes the unit tests. To build C#/WinRT, follow these steps:

  • Open a Visual Studio Developer command prompt pointing at the repo.
  • Run build.cmd.
  • To launch the project in Visual Studio, run devenv cswinrt.sln from the same command prompt. This will inherit the necessary environment.

Note: By default, projection projects only generate source files for Release configurations, where cswinrt.exe can execute in seconds. To generate projection sources for Debug configurations, set the project property GenerateTestProjection to 'true'. In either case, existing projection sources under the "Generated Files" folder will still be compiled into the projection assembly. This configuration permits a faster inner loop in Visual Studio.

What's New

C#/WinRT version 1.1.4 is the latest release and includes bugfixes for the Windows SDK projections, as well as improvements to C#/WinRT authoring support currently in preview. C#/WinRT version 1.1.2 is aligned with the most recent .NET 5 March update. See the releases page for the most recent C#/WinRT NuGet releases and corresponding versions for .NET SDK updates. Details on breaking changes and known issues can be found on the releases page.

Related Projects

C#/WinRT is part of the 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 Project Reunion - 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. Project Reunion combines Win32 native app capabilities with modern API usage techniques, so your apps light up everywhere your users are. Project Reunion also includes WinUI, WebView2, MSIX, C++/WinRT, and Rust/WinRT.

Contributing

File a new issue! This project welcomes contributions and suggestions of all types.

We ask that before you start work on a feature that you would like to contribute, please read our Contributor's Guide.

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.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Note that the project description data, including the texts, logos, images, and/or trademarks, for each open source project belongs to its rightful owner. If you wish to add or remove any projects, please contact us at [email protected].