Windows Community Toolkit 💗 WinUI 3

Today, we’re releasing an update to the Windows Community Toolkit compatible with WinUI 3 and Project Reunion 0.5 for Desktop apps built with .NET 5!

The Windows Community Toolkit is a collection of helpers, extensions, and custom controls. It simplifies and demonstrates common developer task for building UWP and .NET apps for Windows 10, and now for WinUI 3 as well! It’s a part of the .NET Foundation.

The Windows Community Toolkit team has been working alongside the WinUI team to report issues and ensure the Toolkit works on WinUI 3! We’ve been doing the same with the Win2D team as well!

So, we’re happy to say this Toolkit release not only supports WinUI 3, but supports Win2D as well! Now you can leverage the majority of amazing effect animations we’ve added in our 7.0.0 release in your WinUI 3 apps as well. (Edit: Our 7.1.2 release supports the 1.0 version of the Windows App SDK.)

What is WinUI 3?

At Ignite 2019 Microsoft released the first bits of Windows UI Library (WinUI) version 3 (a.k.a. WinUI 3), an evolution of the UWP/XAML platform, that decouples the XAML UI framework from the Windows OS. It is shipped in its whole as a NuGet package, effectively allowing developers to support new features of XAML on older versions of Windows 10 without the need of end-users to upgrade their OS. You can see the latest road map here.

Package Identity and Renaming

As part of this release, we’re introducing a new Package Root for the Windows Community Toolkit on NuGet: CommunityToolkit.*. We’ve updated our namespaces and packages from Microsoft.Toolkit.Uwp.* to now be CommunityToolkit.WinUI.*. We’re making this migration now as part of our WinUI 3 update, as having our package identity allows us to better maintain our packages and their ownership with the community. In the future, it also allows us more flexibility to work with other groups and technologies to share branding and ownership of packages.

Originally, as part of our prior previews we were using an “8.0.0” version moniker. The packages we shipped on NuGet today have been reset to align without current 7.0 release. Moving forward, the version of the WinUI packages will align to the same version of the current UWP packages that contain the same feature set. Therefore, when we ship a 7.1 of the UWP packages, there will be an equivalent set of 7.1 packages for WinUI 3. This allows us the flexibility to move our feature set forward with semantic versioning for as long as we need to maintain two sets of packages, one for UWP and one for WinUI 3. This will continue until a time in the future when we feel the community can move to WinUI 3 in full; at which point we will deprecate our UWP packages and move to developing for WinUI 3 only. Don’t worry, we’ll make sure to give folks a heads-up before this happens, as we expect this to be at least a year down the line.

As part of the eventual transition out of the Microsoft.Toolkit.* identity, we’ll be moving our .NET Standard based packages as well to CommunityToolkit.*. In the interim, we’ll be shipping equivalent versions of these packages under both identities; however, if you’re migrating or starting to use WinUI 3 you should also use the same rooted CommunityToolkit.* packages. Our base .NET Standard package Microsoft.Toolkit will become CommunityToolkit.Common. If you’re a .NET only project, we suggest you migrate to the new package identities in the near future, it should just be a matter of updating your NuGet configuration and using the same types from the new namespaces.

Getting Started with WinUI 3

If you’d like to get started with using the Toolkit for WinUI 3 Desktop development, the rest of this article shows you how!

Requirements

• Visual Studio 2019 16.10 Preview (.NET and UWP Workloads)
• .NET 5 – (should be included in VS download)
• ⚠ Uninstall the WinUI 3 Preview 4 Project Templates VSIX

⚠ Be sure to start by following the initial getting started guidance for Project Reunion here.

Working with the Toolkit

1. You’ll want to start a new C# WinUI 3 Desktop project, by following these instructions first. We’ll use “Project Name” as a placeholder below for whatever you named your project.
2. (Optional) You should be able to run the “Project Name (Package)” project and see the blank app start if your WinUI 3 environment is setup correctly.
3. Right-click your other application “Project Name” project, and select “Manage NuGet Packages…“
4. Click on Browse, find a Toolkit package you’d like to add such as “CommunityToolkit.WinUI.UI.Controls“
5. Click “Install” and accept the license prompts.
6. (Skip this step if using 1.0-preview3 or later.) Modify your project with the following based on your target framework: (See .NET SDK 5.0.200 and 5.0.104 can’t load default styles of custom controls – See Issue microsoft-ui-xaml/issues/4414, this should be resolved with an upcoming .NET update in April.)

<ItemGroup>
  <!-- If you are targeting 18362 -->
  <FrameworkReference Update="Microsoft.Windows.SDK.NET.Ref" RuntimeFrameworkVersion="10.0.18362.16" />
  <FrameworkReference Update="Microsoft.Windows.SDK.NET.Ref" TargetingPackVersion="10.0.18362.16" />
</ItemGroup>

OR

<ItemGroup>
  <!-- If you are targeting 19041 -->
  <FrameworkReference Update="Microsoft.Windows.SDK.NET.Ref" RuntimeFrameworkVersion="10.0.19041.16" />
  <FrameworkReference Update="Microsoft.Windows.SDK.NET.Ref" TargetingPackVersion="10.0.19041.16" />
</ItemGroup>

7. Go to your MainWindow.xaml and paste in some Toolkit code, like our UniformGrid example from our Sample App:

    <controls:UniformGrid 
            FirstColumn="1"
            Orientation="Horizontal"
            Rows="0"
            Columns="0">
        <Border Background="AliceBlue" 
                Grid.Row="1" Grid.Column="1" 
                Grid.RowSpan="2" 
                Grid.ColumnSpan="2">
            <TextBlock Text="1"/>
        </Border>
        <Border Background="Cornsilk">
            <TextBlock Text="2"/>
        </Border>
        <Border Background="DarkSalmon">
            <TextBlock Text="3"/>
        </Border>
        <Border Background="Gainsboro">
            <TextBlock Text="4"/>
        </Border>
        <Border Background="LightBlue">
            <TextBlock Text="5"/>
        </Border>
        <Border Background="MediumAquamarine">
            <TextBlock Text="6"/>
        </Border>
        <Border Background="MistyRose">
            <TextBlock Text="7"/>
        </Border>
        <Border Background="LightCyan">
            <TextBlock Text="8"/>
        </Border>
        <Border Background="Salmon">
            <TextBlock Text="9"/>
        </Border>
        <Border Background="Goldenrod">
            <TextBlock Text="10"/>
        </Border>
        <Border Background="Pink">
            <TextBlock Text="11"/>
        </Border>
    </controls:UniformGrid>

Don’t forget the xmlns:controls="using:CommunityToolkit.WinUI.UI.Controls" in your Page tag!

(And if you replace the existing template’s XAML remove the event handler in the code-behind!)

8. Hit F5 and Voila! 🎉🎉🎉

Known Issues/Limitations

• Be sure to also read the Windows App SDK/WinUI 3 Release Notes for Known Issues.
• The Windows Community Toolkit for WinUI 3 packages are currently only geared towards .NET 5 Desktop development. The toolkit has been tested against the ‘UWP’ sandboxed versions of WinUI as well, but won’t ship a public package until the latest .NET tooling is supported for that environment. (See tracking on dotnet and the WinUI 3 Roadmap.) If you’re an existing UWP app today, we recommend you leverage the WinUI 2.x library and styles with our existing Microsoft.Toolkit.Uwp.* packages in the meantime.
• Certain APIs will not work when running in an unpackaged application, the SystemInformation helper for instance has some issues. Please open an issue on our GitHub with details if you encounter issues.
• ThemeListener is not working due to APIs being removed in Project Reunion Preview 4, see their known issue list in link below.
• GridSplitter cursor doesn’t change discussed here because of changes to CoreWindow and Cursor property.
• When using Win2D you may get DllNotFoundExceptions, you can continue past these. See more in their changelog.
• ⚠ See .NET SDK 5.0.200 and 5.0.104 can’t load default styles of custom controls – Issue microsoft-ui-xaml/issues/4414

Contribute and Share

As a general reminder, you can see the latest features we have to offer by installing the Windows Community Toolkit Sample App from the Microsoft Store (it links to each doc page too). If you would like to contribute, please join us on GitHub and checkout our new Wiki! To follow the conversation on Twitter, use the #WindowsCommunityToolkit hashtag or join us in our UWP Community Discord channel!

Happy coding! <🦙/>

Update 5/12/2021 – Modified sample above to use FrameworkReference 10.0.*.16 to support ProjectReunion 0.5.6 release with our 7.0.2 packages.

Update 10/28/2021 – We have shipped 7.1.1-preview3 packages supporting our 7.1.1 Toolkit release and the Windows App SDK 1.0-preview3 release. If you find any issues, please join our discussion on GitHub.

Update 1/11/2022 – On 11/30/2021 we released the 7.1.2 update which supports the Windows App SDK 1.0 release. This blog has been updated to call out that info at the start and links have been updated to current locations for documentation for the Windows App SDK. The article title was also updated to include the new SDK name. Original Title: “Windows Community Toolkit for Project Reunion 0.5”, the url with this original title has not been modified.