Skip to content

CsWinRT 3.0.0-preview.260319.2

Pre-release
Pre-release

Choose a tag to compare

View all tags
@manodasanW manodasanW released this 25 Mar 03:23
· 209 commits to staging/3.0 since this release
3.0.0-preview.260319.2
f929ed2
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

This is our first preview of CsWinRT 3.0 which is a rewrite of CsWinRT based on .NET 10 and with AOT and trimming in mind from the start. CsWinRT 3.0 is a breaking change release and does several things differently to address various feedback we have got over time.

You can find more details on CsWinRT 3.0 and the breaking changes here.

Recommended: .NET 10.0.5 or later (.NET SDK 10.0.105 / .NET SDK 10.0.201).

Reference projections

Projections generated by CsWinRT for distribution are reference assemblies allowing for applications to adopt CsWinRT versions faster than the libraries that they depend on can and also removing the need for libraries to ship updates just for adopting new CsWinRT releases. You can find more details on creating projections with CsWinRT 3.0 here.

Multi-targeting

Since this is a breaking change compared to previous CsWinRT releases, to allow libraries and applications to be able to adopt CsWinRT 3.0 at their own pace, we have worked with the .NET team to add a new Windows OS version TFM with a .1 suffix allowing for existing libraries to multi-target if desired:

<!-- CsWinRT 2.x -->
<TargetFramework>net10.0-windows10.0.26100.0</TargetFramework>

<!-- CsWinRT 3.0 -->
<TargetFramework>net10.0-windows10.0.26100.1</TargetFramework>

You can find more details on this here.

The .NET SDK also defines a CSWINRT3_0 preprocessor constant when CsWinRT 3.0 is active, which you can use for conditional compilation:

#if CSWINRT3_0
    // CsWinRT 3.0 specific code
#else
    // CsWinRT 2.x
#endif

Projection updates

  • Span<T> projections: WinRT array parameters are now projected as spans instead of arrays, enabling zero-allocation patterns with stackalloc and avoiding the need to allocate exactly-sized arrays. This is source compatible thanks to C# 14's first-class span types.

    WinRT parameter kind CsWinRT 2.x CsWinRT 3.0
    [in] T[] (pass array) T[] ReadOnlySpan<T>
    [out] T[] (fill array) T[] Span<T>
    [out] T[] (receive array) out T[] out T[]

  • Unified event handlers: TypedEventHandler<TSender, TResult> is now projected as the new .NET 10 System.EventHandler<TSender, TEventArgs> type, making WinRT events consistent with standard .NET patterns and fully portable across platform-agnostic code.

  • Point/Rect/Size corrected to float: These foundational types now correctly project their fields as float instead of double, matching the actual WinRT ABI and removing unnecessary implicit casts.

  • No more partial requirement: Developers no longer need to make types partial for AOT compatible WinRT marshalling.

AOT & trimming

The WinRT AOT source generator that previously ran on every library and application project has been moved to a build task that runs during the application build. This allows it to see the entire application including code generated by other source generators and to generate deduplicated vtables and marshaling code. This also helps improve Intellisense performance in larger projects. You can find more details on this here. We are also leveraging the new TypeMap functionality in .NET 10 to allow better trimming and to address the pain points that exist in our AOT support in CsWinRT 2.x. Additionally, we are working on benchmarking and investigating further improvements to both performance and binary size.

Known limitations and breaking changes

This preview only supports generating and consuming projections. Authoring support will be coming up in a future preview.
You may run into publishing errors when publishing trimmed with JIT which we are investigating.

  • Embedded mode has been removed. CsWinRT 3.0 requires projection assemblies to be generated.
  • .NET Standard 2.0 support has been removed.

Removed APIs

Removed API Replacement
As<I>() on projected types WindowsRuntimeActivationFactory
FromAbi(nint) on projected types WindowsRuntimeMarshal.ConvertToManaged()
FromManaged(object) on projected types WindowsRuntimeMarshal.ConvertToUnmanaged()

Packages

Both the CsWinRT package and the updated Windows SDK targeting package are required to be referenced to use this preview:

C#/WinRT package:
https://www.nuget.org/packages/Microsoft.Windows.CsWinRT/3.0.0-preview.260319.2

.NET Windows SDK targeting package:

<WindowsSdkPackageVersion>10.0.xxxxx.85-preview</WindowsSdkPackageVersion>

https://www.nuget.org/packages/Microsoft.Windows.SDK.NET.Ref/10.0.26100.85-preview
https://www.nuget.org/packages/Microsoft.Windows.SDK.NET.Ref/10.0.22621.85-preview
https://www.nuget.org/packages/Microsoft.Windows.SDK.NET.Ref/10.0.22000.85-preview
https://www.nuget.org/packages/Microsoft.Windows.SDK.NET.Ref/10.0.19041.85-preview
https://www.nuget.org/packages/Microsoft.Windows.SDK.NET.Ref/10.0.18362.85-preview
https://www.nuget.org/packages/Microsoft.Windows.SDK.NET.Ref/10.0.17763.85-preview

CsWinRT 2.x

Now that the CsWinRT 3.0 preview is out, we do plan on doing a CsWinRT 2.3 stable release soon. After the CsWinRT 3.0 stable release is out, our plan is to continue monitoring for and addressing critical bugs that come up for CsWinRT 2.x as libraries and applications multi-target or move over to CsWinRT 3.0 at their own pace.

Feedback

This is a preview release and we'd love your feedback! Please file issues on GitHub and tag them with CsWinRT 3.0. For questions and discussions, use GitHub Discussions.

Assets 2
Loading