Announcing WinUI 3 - Project Reunion 0.5 Preview 🎉🐱‍💻

[anawishnoff]

WinUI 3 - Project Reunion 0.5 Preview

We've just released WinUI 3 - Project Reunion 0.5 Preview! This is the first release of WinUI 3 that ships inside of the Project Reunion package. This release consists of stabilization improvements, critical bug fixes, and some new functionality.

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 Building Windows apps with Project Reunion.

We expect to ship Project Reunion 0.5 in late March, which will include the first stable, supported version of WinUI 3.

What's new in WinUI 3 - Project Reunion 0.5 Preview

• In-app acrylic is now supported!

• The Pivot control is no longer supported, and has been deprecated in WinUI 3. We recommend using the NavigationView control for your in-app navigation scenarios.

• WinUI 3 and Project Reunion will be supported down-level to Windows 10 version 1809 - it requires build 17763 or newer.

• A few bug fixes, including:

  • App does not respond to theme changes in Windows when selecting Windows Default theme until restarted
  • ProgressBar doesn't show difference between Paused and Error option
  • Crash in Desktop XamlControlsGallery when trying to reorder ListView items with touch

  For a full list of the bugs fixed in this release, head over to our release notes. If you filed a bug on this repo that was fixed in this release, your issue will be closed shortly.

Please keep in mind that WinUI 3 - Project Reunion 0.5 Preview is still a pre-release product, and has a number of known issues and limitations that our team continues to work on. This preview is not intended for production apps.

Getting started with WinUI 3 - Project Reunion 0.5 Preview

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 Preview

Create WinUI 3 Projects

API Reference documentation for WinUI 3 - Project Reunion 0.5 Preview is coming soon.

Take a look at the walk-through documentation on building a UWP app with WinUI 3 - Project Reunion 0.5 Preview and building a Desktop app with WinUI 3 - Project Reunion 0.5 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.

For upgrading Preview 4 apps to WinUI 3 - Project Reunion 0.5 Preview, carefully follow the instructions laid out here.

Using WinUI 3 - Project Reunion 0.5 Preview with our ecosystem partners

WinUI 3 - Project Reunion 0.5 Preview 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:

• Windows Community Toolkit (Microsoft): The WCT is currently working on supporting Reunion 0.5 Preview 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.

• Uno Platform: Developers using WinUI have an option to take WinUI-built applications to WebAssembly, Linux, macOS, Android and iOS via open-source project Uno Platform, and easily style them with Material and Fluent UI design systems for pixel-perfect experience everywhere. To set up your environment and get started with Uno Platform follow instructions laid out here.

• Telerik: Telerik UI for WinUI is a UI component suite targeting WinUI 3 UWP apps currently released as Preview. The Telerik UI Preview includes several feature-rich controls including Ribbon, DataGrid, Charts, Gauges, Barcode, and more.

• Syncfusion: The Syncfusion WinUI controls preview includes a large variety of high performance and modern controls for WinUI 3 UWP apps. The initial preview includes a suite of controls for data visualization, notifications, navigation, and content editing.

• DevExpress: The entire suite of DevExpress UWP controls is available in preview for WinUI 3 UWP apps. Some example controls include Scheduler, Charts, Navigation, DataGrid, and more

• GrapeCity's service components allow users to integrate data from popular online data sources such as Dynamics, Salesforce, Quickbooks and Google Analytics, and optimize performance with data virtualization. GrapeCity also plans to bring their popular desktop UI controls to WinUI3 later this year.

• 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 the new ARM64-based Surface Pro X. The Ultimate UI or WinUI Preview includes DataGrid, Charts (50+), Gauges, and more.

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

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.

[dpaulino]

Wait, Pivot no longer works in WinUI 3? Hmm that might slow my move to WinUI 3 😞

[bkaankose]

Deprecating Pivot is kind of devastating. I'm pretty sure community will create this control from scratch and include it in the toolkit :) I actually wonder what was the motivation about this decision. Is there such a discussion somewhere?

Overall great release, thanks for the effort!

[mdtauk]

I propose that Pivot be transferred to the community toolkit, so the community can step in and support this control.

[jordan-msftfan]

Pivot control is important in many cases, and I think it should continue to be maintained, whether in the WinUI or switch to the Community Toolkit.

[jordan-msftfan]

Deprecating Pivot is kind of devastating. I'm pretty sure community will create this control from scratch and include it in the toolkit :) I actually wonder what was the motivation about this decision. Is there such a discussion somewhere?

Overall great release, thanks for the effort!

#4264

[vitordelucca]

Is pivots really needed? I feel that Tabs and NavView, and specially NavView, is really the future here. I guess only a few improvements on NavView and it will be enough (like gestures to switch views like pivot).

[mdtauk]

Is pivots really needed? I feel that Tabs and NavView, and specially NavView, is really the future here. I guess only a few improvements on NavView and it will be enough (like gestures to switch views like pivot).

Pivot is not always used for Navigation. It is also a more lightweight control, and is still in use by apps, including Microsoft ones.

If the WinUI team want to stop using it, that is fine, but it should be incumbent on them to provide a suitable pathway for people to move over their apps. NavigationView doesn't work nice with a NavigationView inside it - so switching between a group of tools or sections of a privacy page etc, currently done with a pivot, on a page, in a NavigationView structure, would need more work to transition from.

There is a Community Toolkit, that seems the perfect place for useful controls that "don't belong" in the full WinUI framework.

I have a personal suspicion that some on the team see Pivot as a "hold-over" from Windows Phone, and may also deem it a reminder of a "failed" endeavour.

Anyway, there is a place it can go, if Microsoft were willing to make it happen. And once WinUI goes open-source, the community could have maintained it, and it need not be deprecated totally.

[dpaulino]

Is pivots really needed? I feel that Tabs and NavView, and specially NavView, is really the future here. I guess only a few improvements on NavView and it will be enough (like gestures to switch views like pivot).

My app uses pivot here. Without pivot, how do I implement this in a way that is simple, accessible, touch-friendly, and swipe-able?

[mdtauk]

Is pivots really needed? I feel that Tabs and NavView, and specially NavView, is really the future here. I guess only a few improvements on NavView and it will be enough (like gestures to switch views like pivot).

My app uses pivot here. Without pivot, how do I implement this in a way that is simple, accessible, touch-friendly, and swipe-able?

The community toolkit is adding a TabbedCommandBar to do that kind of control - it may not be swipeable, but I think it uses the Pivot as a base control.

But the point is made, and the Pivot whilst replaced as a navigation design pattern, still has a place!

[dpaulino]

@mdtauk The TabbedCommandBar was actually inspired by Nightingale's UX, and I reviewed the PR 😂 Indeed, the pivot still has a place. I'm curious to understand the reason for its deprecation as well.

[vitordelucca]

Is pivots really needed? I feel that Tabs and NavView, and specially NavView, is really the future here. I guess only a few improvements on NavView and it will be enough (like gestures to switch views like pivot).

My app uses pivot here. Without pivot, how do I implement this in a way that is simple, accessible, touch-friendly, and swipe-able?

I believe this could probably be replaced by a official ribbon control? I think in Build 2017 there was some hints of that...

[michael-hawker]

@vitorgrs there's an existing Ribbon issue #168. We've implemented the TabbedCommandBar in the Windows Community Toolkit as a first experiment of it.

@dpaulino would you say the Touch Swipe is the main missing thing that Pivot provides that TabView and TabbedCommandBar don't?

I feel like we should have a general swipe behavior or something in the Toolkit to help with these scenarios.

As I also find the reverse where Pivot's scrolling behavior makes it complex to use when other mouse interaction is required in the content. This is why we didn't use it for the improved WCT ColorPicker.

I'm assuming Pivot has been removed as it was extremely complex for what it provided and was very hard to customize. I believe TabView and NavigationView provides similar layout options from a end-result point of view.

[michael-hawker]

For anyone looking, the Toolkit bits only support WinUI 3 Preview 4 currently. We're investigating if we can push out 0.5 preview supported bits in the near future.

[huoyaoyuan]

I use Pivot for parity with TabControl in WPF. It's very friendly with MVVM. NavigationView is quite unfriendly.

I'll call NavigationView a broken control - it never satisfied desktop designs.

[Marv51]

@anawishnoff The instructions to update a project to 0.5 from preview 4 that you link to seem out of date? or something didn't get merged?

[WamWooWam]

For my use-case here, a set of "tabbed" GridViews that you can swipe between, there is literally no replacement for Pivot available. I simply don't know what the WinUI team is thinking in removing this control.

[huoyaoyuan]

In xaml controls gallery, the description of Pivot is A Pivot allows you to show a collection of items from different sources in a tabbed view. However, many real world usage are using it for showing items from one source. In this case, it's logic is similar to MasterDetailsView in WCTK, but with better animation and the ability to set items manually.

[MartinZikmund]

I agree with everyone who is against deprecating Pivot as it really has a different set of use-cases than other available navigation controls. At minimum it should still be available as part of Windows Community Toolkit, but I don't see a point in removing it from WinUI anyway...

[yoshiask]

Is pivots really needed? I feel that Tabs and NavView, and specially NavView, is really the future here. I guess only a few improvements on NavView and it will be enough (like gestures to switch views like pivot).

My app uses pivot here. Without pivot, how do I implement this in a way that is simple, accessible, touch-friendly, and swipe-able?

The community toolkit is adding a TabbedCommandBar to do that kind of control - it may not be swipeable, but I think it uses the Pivot as a base control.

But the point is made, and the Pivot whilst replaced as a navigation design pattern, still has a place!

The TabbedCommandBar does not use a Pivot, it's actually a NavigationView. But that means it has all of the issues everyone has been listing here. It has no gestures, and cannot be nested (though, considering that it's a ribbon, it really shouldn't be).

[MartinZikmund]

Also have to add a shout-out to @mdtauk, because his visual refresh proposal for Pivot is beautiful #3957

[anawishnoff]

Hey folks, thanks for the great discussion here on Pivot. I don't want to step in and break the flow, but I see that it's clearly an important topic for a lot of you. I'm going to see if we can address the reasoning behind this or at least open a conversation about this on next week's community call on 3/17.

@anawishnoff The instructions to update a project to 0.5 from preview 4 that you link to seem out of date? or something didn't get merged?

@Marv51 - thanks for pointing this out. The upgrade instructions are a bit delayed this time around, I hope to publish them later today!

[dpaulino]

@anawishnoff Personally, I'm okay with whatever direction. I guess I was just surprised by the mention of its deprecation. It seemed sudden to me (or did I miss a blog post?). Pivot is used by a lot of apps, so it would be nice to get a blog post or some communication with details. For instance, if I want to upgrade my winui2 up to winui3, do I have to remove pivot? Like, is that a hard break? Or can I keep pivot and I can move away from pivot slowly?

A communication would help me plan. I was planning to bring my apps to winui3 as soon as it was out of preview, but this news will extend my move by half a year because I have to rewrite core pieces of my app now.

[WamWooWam]

A communication would help me plan. I was planning to bring my apps to winui3 as soon as it was out of preview, but this news will extend my move by half a year because I have to rewrite core pieces of my app now.

I wholeheartedly second this. Communication has been a big thing with WinUI generally, and while I understand when all details aren't finalised, making concrete statements is somewhat difficult, there's been a lot of bombshells like these dropped over the course of WinUI 3's development, stuff like MediaPlayerElement and reveal highlight just to name a few.

Previews are great, but if core features used by countless apps are just dropped out of the blue between them without any prior announcement, rhyme or reason, how exactly are we meant to plan around them?

[BreeceW]

I'm going to see if we can address the reasoning behind this or at least open a conversation about this on next week's community call on 3/17.
This is good to hear, but I like many others who have already expressed their thoughts am disappointed by the surprise total removal of Pivot. If there are technical difficulties in keeping Pivot in WinUI 3, could it be possible to have at least a Pivot control with the same API but with problematic features removed? If, for example, the reason for removing Pivot had to do with complications involving the swiping gestures, could we have a click-only Pivot in the meantime?

[huoyaoyuan]

You cannot even use NavigationView in desktop with this version: #4496

[robloo]

TabView and NavigationView are very heavy controls and are top-level paradigms, so having a light-weight control as a lower hierarchical level option, is useful.

Exactly. This is why I ask if anyone on the framework team is building apps these days.

Now if it were my choice, I would clarify the usage of the control, and discourage people from using it as a top level pattern, citing TabView for a multi document pattern, and Navigation for a structure pattern.

Agree. There are better choices for top-level navigation patterns like the example given before.

But I can understand there may be a perception of a lack of usage or engagement with the control, and so a judgement of what level of support or uplift is to be considered.

I think this is missing the point. There is a gap in functionality in the framework without the Pivot control. We need a basic, lightweight TabControl equivalent (from the WPF days) to do things such as below.

[mdtauk]

You cannot even use NavigationView in desktop with this version: #4496

Let's not mistake a bug with an intended deprecation.

[lhak]

According to the release notes, in-app acrylic is supposed to work but this does not seem to be the case.

[huoyaoyuan]

in-app acrylic is supposed to work but this does not seem to be the case.

That should be the reason crashing NavigationView, because it trusts and uses in-app acrylic.

[xerz-one]

@lhak @huoyaoyuan Indeed, I can reproduce the issue with a blank MSIX project where MainWindow.xaml contains the following: https://gist.github.com/xerz-one/b8c8a53a837ba231b6814bbe495161b7

It seems to complain about a WinRT transform error and about Windows.Graphics.Display: GetForCurrentView must be called on a thread that is associated with a CoreWindow. – just like in #4496, as if it can't use HWNDs

[anawishnoff]

@lhak , @huoyaoyuan , @xerz-one: In-app acrylic should definitely be working... it would be great to file an issue on this with repro steps if you haven't already. Thanks!

[huoyaoyuan]

@anawishnoff I can repro it within NavigationView with just the control only, and the error message shows that UWP Window is expected, see #4496

[michael-hawker]

@anawishnoff @azchohfi saw in-app acrylic not working with the Toolkit sample app too.

[Noemata]

Rather than comments, perhaps concrete examples might make things clearer:

/~https://github.com/Noemata/FakePOS

(issues moving to WinUI 0.5)

[jschwizer99]

For users with internet access restrictions we get the following installer error when trying to install WinUI Reunion 0.5 packages.

Does it mean that a WinUI application packaged with MSIX based on Reunion 0.5 is no more self-contained? Are there any changes needed in the setup so that the package can be installed by a user with restricted access? Many thanks in advance.

[anawishnoff]

@RealTommyKlein @alwu-msft Do you guys have any ideas about the error that @jschwizer99 is seeing?

[evelynwu-msft]

@RealTommyKlein @alwu-msft Do you guys have any ideas about the error that @jschwizer99 is seeing?

Project Reunion 0.5 Preview currently only ships as a framework package and so Internet access is required so that the framework package can be downloaded and installed from the Store.

[Marv51]

@jschwizer99 @alwu-msft That's identical to WinUI 2, right?

[evelynwu-msft]

@Marv51 Yes.

[jschwizer99]

@jschwizer99 @alwu-msft That's identical to WinUI 2, right?

I have only experience with WinUI 3.0 Preview 2/3/4 as a Win32 application that was side-loaded with the MSIX. As we are targeting the Win32 segment we have customers using older Windows versions and restrictions on network access. With Reunion 0.5 the minimal version was lifted to 1809. This should be fine to convince our customers to use up-to-date Windows versions. But with network access, it is a more difficult topic as our customers are partially working in secured environments. As long as WinUI is not shipping grade it is fine. But for production-grade, I prefer a solution in which I can bundle all required software. Up to now, I was using appx packages for 1904 users. I now switched to msix packages with Reunion 0.5.

[shaheedmalik]

@mdtauk The TabbedCommandBar was actually inspired by Nightingale's UX, and I reviewed the PR 😂 Indeed, the pivot still has a place. I'm curious to understand the reason for its deprecation as well.

It needs swipe then.

[evelynwu-msft]

@jschwizer99 @alwu-msft That's identical to WinUI 2, right?

I have only experience with WinUI 3.0 Preview 2/3/4 as a Win32 application that was side-loaded with the MSIX. As we are targeting the Win32 segment we have customers using older Windows versions and restrictions on network access. With Reunion 0.5 the minimal version was lifted to 1809. This should be fine to convince our customers to use up-to-date Windows versions. But with network access, it is a more difficult topic as our customers are partially working in secured environments. As long as WinUI is not shipping grade it is fine. But for production-grade, I prefer a solution in which I can bundle all required software. Up to now, I was using appx packages for 1904 users. I now switched to msix packages with Reunion 0.5.

We agree that it is an important scenario. We're unable to support it currently with Project Reunion 0.5 Preview, but that support is coming and hopefully you won't have to wait for too long to light it up. :)

[jschwizer99]

We agree that it is an important scenario. We're unable to support it currently with Project Reunion 0.5 Preview, but that support is coming and hopefully you won't have to wait for too long to light it up. :)

Many thanks for the answer. Looking forward to it as side-loading is currently not nice. It triggers for 10% of the users support calls as they fail to fully follow the steps required to install the self-signed certificate. For large Win32 applications, Microsoft Store distribution is not an option.

[get-flat]

Could you please clarify what exactly was released

• WinUI3 preview 4 + project reunion 0.5 preview
• WinUI3 GA + project reunion 0.5 preview
• when/if can we expect WinUI3 GA + project reunion 0.5 GA(?) (roadmap -> March 21)

After WinUI3 GA we can expect next previews. Would it be Winui preview + PR 0.5 GA or winui preview + PR 0.8 preview etc?

[Marv51]

@get-flat A preview of project reunion 0.5 was released (this contains a preview of WinUI 3). This preview was not on the roadmap. The stable release of reunion 0.5 with the stable WinUI 3 version is planned for late march.

[Grinch]

What's the state of fixing acrylic in this release? The fact that a key feature of this release doesn't function is rather disheartening.

[Zidane]

@anawishnoff

Any status on acrylic support? Or was that mistakenly put in the release post....?

[smourier]

I've just test the latest WinUI 3 + project reunion package and created a simple C++ app with Visual Studio 2019 preview last version.

Everything works fine but building, packaging, Intellisense scanning hundreds of files with modal dialog boxes, etc. takes ages in comparison with Winforms, WPF, Win32 desktop, etc. (C# or C++) which on my machine is almost immediate for a "blank" package.

Will it always be like that once even when it's released?