Microsoft-ui-xaml: Question: Adopt WinUI 2.4 in an existing UWP application

[cosminstirbu]

Hello,

I'm trying to wrap my ahead around the steps required adopt WinUI 2.4 in an existing UWP application.

I have read the docs and also browsed the code in Xaml-Controls-Gallery and I would like to double check that I understood the migration path correctly.

Therefore, I have a few questions:

1. It seems that not all controls from Windows.UI.Xaml.Controls have been migrated to Microsoft.UI.Xaml.Controls (e.g StackPanel is missing from Microsoft.UI.Xaml.Controls). Is there any documentation related to the gap between these two namespaces?

2. Is it expected that once we identify all the Windows.UI.Xaml.Controls classes that can be migrated to Microsoft.UI.Xaml.Controls we need to manually edit all of .xaml and .cs files to point to the new namespace (e.g. xmlns:muxc="using:Microsoft.UI.Xaml.Controls" / using MUXC = Microsoft.UI.Xaml.Controls;)? Are there any tools / plans to automate this process?

3. How come there are no Visual Studio templates for creating a new UWP application using WinUI 2.4? (I did notice that there are WinUI 3 preview templates on the marketplace)

Thank you,
Cosmin

[robloo]

It seems that not all controls from Windows.UI.Xaml.Controls have been migrated to Microsoft.UI.Xaml.Controls (e.g StackPanel is missing from Microsoft.UI.Xaml.Controls). Is there any documentation related to the gap between these two namespaces?

Button, TextBlock, etc. are also not included. A good rule of thumb: If you don't have reason to use the WinUI 2.4 version (i.e. you don't know why you need it) then just use what is in Windows.UI.Xaml. Documentation listing the control in WinUI 2.4 is here: https://docs.microsoft.com/en-us/uwp/api/microsoft.ui.xaml.controls?view=winui-2.4

Note that WinUI also includes new styles for nearly ALL controls. This is one of the main befits -- you get the latest look and feel. Just modify the App.xaml to get the styles there is no need to update all control namespaces.

Is it expected that once we identify all the Windows.UI.Xaml.Controls classes that can be migrated to Microsoft.UI.Xaml.Controls we need to manually edit all of .xaml and .cs files to point to the new namespace (e.g. xmlns:muxc="using:Microsoft.UI.Xaml.Controls" / using MUXC = Microsoft.UI.Xaml.Controls;)? Are there any tools / plans to automate this process?

No automated tools exist right now and everything must be done manually. Again, only do this as needed don't switch everything over unless you are using WinUI 3.0. I expect Microsoft will come up with something for WinUI 3.0 to automate this; however, a find and replace is very simple and only the .cs files will need to be changed. XAML -- if you are using the Windows.UI.Xaml controls -- will not need to be updated.

How come there are no Visual Studio templates for creating a new UWP application using WinUI 2.4? (I did notice that there are WinUI 3 preview templates on the marketplace)

UWP generally doesn't get updated anymore. I expect these types of things to come out with WinUI 3.0 over the next year or so. That said, adding the references is very easy and the whole process is documented here: https://docs.microsoft.com/en-us/windows/apps/winui/winui2/getting-started

[StephenLPeters]

There are quite a few bug fixes to the controls which exist in both name spaces, so I think that I would encourage you to take a look at this doc https://docs.microsoft.com/en-us/uwp/api/microsoft.ui.xaml.controls?view=winui-2.4, identify the controls which you are using from the Wux namespace and update to the Mux version to pick up those fixes. Unfortunately there is not a good tooling story for updating your app automatically.

[robloo]

As the app is already UWP, I'm assuming any bugs have already been worked around. I still wouldn't spend the time to transition all controls over unless you have the need (run across a bug and realize it's fixed in WinUI). If you do decide to use all the WinUI controls possible remember you are going to have to remove the namespace definitions in all the XAML files again when you transition to WinUI 3.0. You will also need to carefully manage the different usings in your .cs files which may not at first be as intuitive.

That said @StephenLPeters is from Microsoft so carries more weight. It's only my personal recommendation that if there isn't a need to use the new controls in WinUI 2.x, and your app is already working with vanilla UWP, I would wait to transition everything over when WinUI 3.0 comes around. Of course if you have a smaller-sized app this all might not matter.

[StephenLPeters]

I suspect that there are apps out there which don't have a work around for the system xaml bugs because they didn't realize that they were present. These are the type of issues I would hope to solve by suggesting people update to use the Winui versions. Of course this update process has a cost and for bigger projects it can be quite large so it is understandable if some app developers do not want to take on that project. And Rob is correct, a lot of this work would need to be (basically) repeated if/when you update to Winui 3.

I only suggest blanket updating because, depending on the scale of the testing you've done on your app, you may fix bugs you didn't know you had by updating. Of course, this has to be balanced with the development cost and technical debt the change would accrue.

[robloo]

@StephenLPeters Agree, a main point just to be more clear is WinUI 3.0 is expected to be ready for production by end of this year / early next. In my opinion that throws the cost/benefit in favor of waiting to adopt the changes in medium/large apps.

[cosminstirbu]

Thank you for your replies.

It seems that at this point, given that our codebase is fairly large and also that WinUI 3 is scheduled for a release at the beginning of 2021 it would only make sense to adopt WinUI 2.x for the following reasons:

• Leverage the new styles
• Replace an existing control that might be buggy
• Use a new control that is found only in WinUI 2.x

Thanks,
Cosmin

[kinex]

Can I start using WinUI gradually in my UWP app or do I need to convert the whole app to WinUI in one shot?

For example, I was planning to use TabView control from Windows Community Toolkit, but I noticed there a message "Please migrate to the "TabView" control from WinUI". So can I now include TabView from WinUI to my UWP app without converting the whole app to WinUI?

[Felix-Dev]

@kinex Yes, you can use WinUI's TabView while keeping the rest of your app using OS XAML. Simply use WinUI 2 for that: https://docs.microsoft.com/en-us/windows/apps/winui/winui2/getting-started

Once you've added the WinUI 2 library to your project, you can use then start using its TabView control. If you followed the above tutorial, then you will have a XAML namespace named "muxc" and can use that to access the TabView control: <muxc:TabView></muxc:TabView>

[StephenLPeters]

Do note however that Winui 2 includes updated styles for many of the in box xaml controls. So when you import the Winui 2 package you might notice the visuals of some of your controls update. The updated styles conform to the Windows fluent design system so we'd suggest using them, we've also done our best to try to make sure they wont break apps which update to them, however your mileage may vary.