Announcing WinUI 3 - Project Reunion 0.5! 🎉🎊

[anawishnoff]

Announcing WinUI - Project Reunion 0.5!

We've just released the first stable, supported version of WinUI 3 that can be used in desktop production apps! This release ships inside of the Project Reunion 0.5 package and includes stabilization updates and general improvements to make WinUI 3 apps suitable for production.

WinUI 3 is now shipping with Project Reunion! What does that mean?

This means that instead of installing the WinUI 3 VSIX and/or NuGet package, you'll download the Project Reunion VSIX. This still has all of the same WinUI project templates you're used to, but also provides access to other Project Reunion components, such as DWriteCore and MRTCore. The Project Reunion package includes a reference to the WinUI 3 NuGet package.

For more on Project Reunion, see their documentation and repository. For installation instructions, see Get started with Project Reunion.

What's new in WinUI 3 - Project Reunion 0.5

Most of the features introduced in past preview releases have now been stabilized for use in production apps, including (but definitely not limited to):

• Ability to create desktop apps with WinUI, including .NET 5 for Win32 apps
• Chromium-based WebView2 control
• Custom titlebar support
• ARM64 Support
• SwapChainPanel

For a full list, see our release notes.

Preview features

As this is a stable release, preview features have been removed from this version of WinUI 3, including support for building UWP apps. You can still access these features by using the current preview version of WinUI 3. See WinUI 3 - Project Reunion 0.5 Preview release notes for more information, and Get started with Project Reunion for installation instructions.

Getting started with WinUI 3 - Project Reunion 0.5

First, you'll need to set up your dev environment with the appropriate technologies. See our documentation for installation instructions and more information on project types:

Install Project Reunion 0.5

Create WinUI 3 Projects

While you're developing, check out the API Reference documentation for WinUI 3 - Project Reunion 0.5.

Take a look at our walk-through docs:

• Get started with WinUI 3 for desktop apps
• Build a basic WinUI 3 app for desktop
• Get started with WinUI 3 for UWP apps (Preview)

We love feedback! We encourage you to file any bug, big or small, on our repo using this template. Knowing which issues and features are important and/or critical to our customers highly influences which ones we tackle. Even though we now ship with Project Reunion, please continue to file WinUI-specific bugs on this repo.

To upgrade existing WinUI 3 preview apps to WinUI 3 - Project Reunion 0.5, carefully follow the instructions laid out here.

Using WinUI 3 - Project Reunion 0.5 with our ecosystem partners

WinUI 3 - Project Reunion 0.5 is in the process of being integrated into several other important ecosystem technologies. To test out and follow that progress, check out some of our partner technologies below:

• Actipro Software is migrating their vast UI control offerings over to WinUI 3, including their SyntaxEditor code editor, propertygrid, native type edit boxes, docking/MDI, charts, and more.

• DevExpress: DevExpress has released 20 new WinUI controls with Project Reunion 0.5 support, including the Data Grid, Scheduler, Charts, Ribbon Toolbar, and more. All 20 UI components are available free-of-charge.

• GrapeCity plans to bring their popular desktop UI controls to WinUI later this year! Learn more about their data connection service components for WinUI.

• Infragistics: Ultimate UI for WinUI brings business critical, high performing, and feature rich line of business controls to your apps that target any platform that runs Windows (including Windows on ARM64).

• Syncfusion: Updated their projects to Microsoft.ProjectReunion from Microsoft.WinUI following upgrade instructions. All their controls are working fine.

• Telerik UI for WinUI: the market first UI controls suite for crafting Win32 and UWP apps with WinUI 3, comes with feature-rich controls like Ribbon, DataGrid, Charts, Gauges, Barcode, and more.

• Uno Platform: Use WinUI 3 – Reunion 0.5, XAML and C# to build pixel-perfect, single-codebase, native applications that can run on Web, Desktop and Mobile. It is free, open-source and available today.

• Windows Community Toolkit (Microsoft): The WCT is currently working on supporting Reunion 0.5 in the near future. It provides tons of new controls and capabilities for use in your WinUI app. You can check out their open source repo here.

What's next

To keep up with progress being made on WinUI 3, please see our feature roadmap which gets updated regularly. We also give monthly updates on our WinUI Community Calls, where you can directly ask the team any questions you have.

---

Servicing Releases

Below you'll find updates on the servicing patches that we've shipped for Project Reunion 0.5. These are all stable releases that you can continue to use in your desktop production apps.

If you're building an app with Project Reunion for the first time, follow the installation instructions here.

If you have an app that's already using any version of Project Reunion 0.5, you can update to the latest release by following the instructions here.

Update #1 - Project Reunion 0.5.5 is now available

Project Reunion 0.5.4 is a stable servicing release that fixes a few critical bugs.

Bugs fixed in Project Reunion 0.5.5:

• Memory leaks caused by subscribing to some framework element events and page navigation due to a C#/WinRT issue

• Alt+F4 does not close desktop apps

• Drag and drop does not work with touch or pen due to an issue with StartDragAsync()

• Black flash on WebView2 when setting Visibility to Collapsed

• Microsoft.ProjectReunion.Foundation is breaking WPF compilations

• Installing the Project Reunion 0.5 NuGet package results in build failures in projects that target AnyCPU

• Crash when panel containing SwapChainPanel is opened multiple times

• Acrylic brush renders transparent

• A few bugs having to do with GC/ObjectDisposedExceptions, marshaling value and nullable types (TimeSpan, IReference, etc) in C#/WinRT are now fixed. In order to get these fixes, you must download the latest .NET 5 SDK.

Update #2 - Project Reunion 0.5.6 is now available

Project Reunion 0.5.6 is a small, stable servicing update that fixes a few more critical bugs.

Bugs fixed in Project Reunion 0.5.6

• Metadata is missing from attributes

• Crashes caused by XamlCompiler determining all types are not a part of WinUI framework

Update #3 - Project Reunion 0.5.7 is now available

Project Reunion 0.5.7 is a new servicing release that continues to fix a couple of critical bugs from Project Reunion 0.5.

Bugs fixed in Project Reunion 0..5.7

• Crash in ListView when scrolling with pen

• Padding of Minimize/Maximize/Close Buttons is Not Consistent When Using ExtendsContentIntoTitleBar

• WinUI 3 Desktop apps always show focus rects on launch, even if the app was launched via mouse/touch/pen

• UIA isn't properly handling display scale value

Update #4 - v0.5.8 is now available

Version 0.5.8 is a new servicing release that includes a security fix for Project Reunion 0.5.

For more details, see CVE-2021-34489.

Update #5 - v0.5.9 is now available

Version 0.5.9 is a stable, servicing release that includes another security fix for Project Reunion 0.5.

For more details, see CVE-2021-34533.

[Pinox]

What about Xaml-Controls-Gallery and Template Studio.

Also , when is WinUI 3.0 open source release date featured in the roadmap ?

[anawishnoff]

@Pinox Yup! You can see the winui3 branch of the Xaml Controls Gallery here: https://github.com/microsoft/Xaml-Controls-Gallery/tree/winui3. Unfortunately no dates to share for open source yet.

[Zidane]

I see that the previous issue was unpinned and no notes on this subject in this one.

Do we have in-app acrylic now or?

[Grinch]

I can confirm it appears the crash present in the preview for Acrylic is still present (C#, Packaged, Desktop). Am I to assume this is no longer an intended functioning feature of 0.5 or not? Haven't seen any commentary made on it aside from folks reporting the issue.

Exception thrown at 0x00007FF88C9D67AC (KernelBase.dll) in UI.exe: 0x40080202: WinRT transform error (parameters: 0x000000008000000B, 0x0000000080070490, 0x0000000000000014, 0x00000058B3B79990).
Exception thrown at 0x00007FF88C9D67AC (KernelBase.dll) in UI.exe: WinRT originate error - 0x80070490 : 'Windows.Graphics.Display: GetForCurrentView must be called on a thread that is associated with a CoreWindow.'.
Exception thrown at 0x00007FF88C9D67AC in UI.exe: Microsoft C++ exception: winrt::hresult_error at memory location 0x00000058B3B79F70.

[sylveon]

The newly published controls gallery for WinUI 3 feels very stuttery for me. It almost seems like the FPS is locked to 60 on my high refresh rate monitor (160Hz). Could we please not do that? It degrades the user experience of people who use monitors with a higher refresh rate, since the frames are out of sync with the monitor.

[jschwizer99]

@anawishnoff, the release notes for Reunion 0.5 list Custom cursor support. I would expect from this entry that it is possible to change cursor pointers. The last discussion on cursor support can be found in #4152. As we lost direct access over CoreWindow the only available workaround was subclassing of each control to get access to the protected ProtectedCursor. This approach is not very flexible as a lot of code is required just to change cursor pointers.

Was there an improvement in the current Reunion 0.5 release? Is there documentation on this topic? Besides the issues, I just found a UWP link PointerCursor that results in a 404.

Related tickets:
#4152
#2734
#506
microsoft/WindowsAppSDK#238

Many thanks for your support.

[bkaankose]

The newly published controls gallery for WinUI 3 feels very stuttery for me. It almost seems like the FPS is locked to 60 on my high refresh rate monitor (160Hz). Could we please not do that? It degrades the user experience of people who use monitors with a higher refresh rate, since the frames are out of sync with the monitor.

#4690

I tried to describe this issue here.

[Noemata]

Ran performance test from here again after updating to current release: https://github.com/Noemata/XamlBenchmark

CPU utilization has gone down a chunk. Not sure that is a good thing in this case.

Memory consumption is still the same as the previous release, being way too high with leaks. Its 10x higher than a UWP release build and 7x higher than WPF.

Render performance is 3x slower than WPF and UWP. At the current level, this will significantly dissuade adoption.

Render performance must be on a par with UWP at least. Curiously, WPF now outpaces even the release build of UWP for basic XAML rendering operations. That is very impressive for WPF, not so much for UWP which should be faster.

This is not a production ready release. Presently, larger Project Reunion apps will eventually consume all available memory. Please run your production release candidate through a better test regime (including those provided for you by third parties) before publishing a release qualified as "production ready".

Perhaps its time to bring in some of the WPF team to help out. They seem to be getting things very right both in terms of stability and performance!

[anawishnoff]

@Grinch @Zidane In-app acrylic should be mostly fixed in this release, and should no longer cause a crash. I believe there is still an issue with TintLuminosity, but that's next on our list to fix. Can you please open a bug if you're still seeing an issue?

@jschwizer99, it seems like that's a gap in our documentation. I don't believe ProtectedCursor has changes in Project Reunion 0.5, but I hear you that this is an unflexible workaround and I'll relay that back to the team and see if we have any plans around it. Here's a doc that explains a bit more about the CoreWindow changes.

[Zidane]

@anawishnoff

Could you take a moment to read what @Grinch posted? This is by no means fixed whatsoever and was brought up on the pre-release ticket.

There was this ticket that for whatever reason was asked to be closed: #4504

It went over to this ticket: #4496

...which I am not sure why that happened as this has no bearing on the fact that acrylic is BROKEN. Yes you can ignore the exceptions being thrown and the app will continue but acrylic literally does not render whatsoever using {ThemeResource SystemControlAcrylicElementBrush} on C#, Packaged, Desktop.

I welcome anyone else in the community to take the ProjectReunion 0.5 release, make a new WinUI packaged Desktop app, Put a rectangle on the main window and fill it with that brush, run the app.

Tell it to ignore the exceptions and continue.

Observe no acrylic...

Please advise? Would love to really use this new platform. I think it has limitless potential but it is frustrating to be told "No it works" and no one internally at Microsoft will take 5 seconds to actually run test code and see that is very much doesn't......

[anawishnoff]

@Zidane - My apologies as I didn't mean to dismiss the problem. What I meant in my previous response was that based on our engineers' testing, this feature was working - we've been pushing fixes towards previous bugs filed on this, and we've been doing testing on those. So, at least on my end it's news that there are still issues with in-app acrylic, other than the TintLuminosity issue I mentioned.

So, if you are still seeing lingering issues or new issues with acrylic, opening a bug with more information would be very helpful since the other bugs on this topic have been resolved/closed. Having a separate bug lets us assign the right person to take a look and provides an easy way to get all of the info we need to address it. We definitely want to address any issues here - this is an important feature that should absolutely be supported in the latest release.

[JanRajnoha]

I updated app from first available reunion version (prerelease) to stable version and app is crashing. I have message in App.xaml.cs on function InitializeComponent(); with message:

1. Is somewhere available list of changes between versions to avoid this problem.
2. What's the problem with this bug? I was just updated NuGet. On sample app, created with prerelease and updated to stable version was same problem, sample app from stable reunion is okay.

[zomgrolf]

Hello, I'm not sure if this is the right place... I'm a somewhat seasoned C++ developer who hasn't touched any Windows UI stuff in a good while -- however, having seen some presentations on WinUI 3 and Project Reunion, I decided to give it a go.

I was able to follow the 'Get started with WinUI 3 for desktop apps' article easily enough and created a basic desktop app from the template using the preview version of VS2019 16.10. It builds and runs fine, however when I try to open one of the source code files (e.g. MainWindow.xaml.cpp), I get a lot of IntelliSense errors complaining about undefined identifiers (InitializeComponent, int32_t, hresult_not_implemented, etc.). What's wrong? Why isn't a basic project set up correctly? How do I fix that?

Also, where do I go from here? I had a look at the 'Build a basic WinUI 3 app for desktop', but it seems to be aimed at C# developers. Although it wasn't immediately obvious to me how to translate it to C++, after a few minutes of searching the web, I got something (seemingly) working. I would much prefer to know what I'm doing though, instead of a (semi-)random hacking. Can you offer some pointers on where to look next for someone with C++17 experience (and a tiny bit of Win32 API + COM programming knowledge)?

Or do I need to learn C# and .NET first?
I do appreciate that my questions don't quite match the typical level of discussion here...

[Noemata]

@JanRajnoha , it's not enough to just update the Nuget package. There are other project level changes. Nothing major, but you cannot use an existing project as is. I created a new one to sort out how to make the needed changes. In particular, the Package project has a couple subtle differences. You should also delete all intermediate files in your bin and obj folders.

[Grinch]

@anawishnoff My apologies. Acrylic does appear to work for Backdrop sources but HostBackdrop isn't respected assuming the documentation is to be believed as to how it behaves (https://docs.microsoft.com/en-us/uwp/api/windows.ui.xaml.media.acrylicbackgroundsource?view=winrt-19041). At least when using it I am not seeing the expected result (something akin to what Windows 10 does in a settings page for the NavigationView).

Is this a known issue to your knowledge?

[sylveon]

HostBackdrop will not be supported for the initial release of WinUI and is "planned for a future release", as detailed in the roadmap.

[jschwizer99]

@zomgrolf [WinUI C++ Starting Points]
I did this step half a year ago as I have to work with a huge C++ codebase and thus switching everything to managed code is not an option.

With the current Visual Studio Preview 16.10.0 I also observe IntelliSense problems. Reloading the projects should solve the problems if all required winrt includes are defined. As WinUI is under development it is best to always update to the latest preview version. But this has to be paid with instabilities in the tooling. Visual Studio issues are usually fixed very fast in the next version.

In order to use C++ with WinUI, you need to master WinRT C++ and async programming (coroutines). All presentations and blogs of Kenny Kerr are a good starting point.

• CppCon 2017: Scott Jones & Kenny Kerr “C++/WinRT and the Future of C++ on Windows”
• Effective C++/WinRT for UWP and Win32

You will also find a lot of information about WinRT C++ event handling and coroutines on Microsoft pages

• https://docs.microsoft.com/en-us/windows/uwp/cpp-and-winrt-apis/handle-events
• https://docs.microsoft.com/en-us/archive/msdn-magazine/2018/june/c-effective-async-with-coroutines-and-c-winrt

The Photo Editor is a UWP WinRT C++ application example.

The blog Old New Thing of Raymond Chen deals with a lot of gotchas of WinRT C++ programming.

As both WinUI and WinRT C++ are under active development there will not be a single source of documentation.

If you come from standard C++ programming, you will notice that debugging WinRT C++ will be very hard. The underlying COM programming in combination with async events will make it often hard to pin down the source of the error. This gets especially problematic if source code is not accessible (WinUI is not yet open source). So debugging can be frustrating if you compare it to standard C++ multithreading programming.

If you are familiar with WinRT C++ it is simple to convert .NET WinUI examples to WinRT C++. Compared to C# .NET you will write more code. The definition of a property will be more effort. Analysis tools like profiler or concurrency analyzer are currently not useful with WinRT C++.

IMHO, the biggest risk of choosing WinRT C++ over .NET for WinUI programming is the additional Windows Community Toolkit and third-party library functionality. As these tools are using .NET they are not easily accessible over WinRT C++. Instead of mixing I would then rather have the full user interface layer of an application in managed code.

[zomgrolf]

@jschwizer99 Thanks, that was very helpful!

[anawishnoff]

@JanRajnoha - you can also take a look at the instructions to upgrade a WinUI 3 app from Project Reunion 0.5 Preview -> Project Reunion 0.5 Stable.

@jschwizer99 - I found some more info on ProtectedCursor for you. So the UIElement.ProtectedCursor property has been updated in Project Reunion 0.5, although the docs don't seem to be updated yet. However, you can find all the info in the spec. Also - thanks for posting those links and that info!

@Grinch - yes, as @sylveon said unfortunately background acrylic is not yet supported. Glad to hear in-app acrylic is working for you, though.

[jschwizer99]

@anawishnoff - Many thanks for checking the cursor status. The public Cursor Property is exactly what I'm looking for as the protected property is not helpful for app development. In this case, only a leave and exit event handler implementation is needed instead of a full subclassing which is quite some code in WinRT C++.

[JanRajnoha]

@anawishnoff oh thanks, it is working again :)

[jindal1979]

Will there be incremental release for bug fixes before next major release for 0.5 version.

[LadderLogic]

CaptureElement:
I was hoping to use CaptureElement in WinUI3 (Microsoft.UI namespace) when I followed the "Equivalent WinUI class: " link here, but I was greeted with a 404:
https://docs.microsoft.com/en-us/uwp/api/Windows.UI.Xaml.Controls.CaptureElement?view=winrt-19041

Is there a way to know when a certain control/element/feature will be available in Win UI 3 (esp. Media controls)? The general roadmap is a little broad.

[gabbybilka]

Check out #6325 to see features from this release in Windows App SDK 1.0 and leave any additional comments.