August 23rd, 2023

Windows Community Toolkit 8.0 Pre-release

Michael Hawker
Michael Hawker
Senior Software Engineer

The Windows Community Toolkit 8.0 Pre-release

Windows Community Toolkit Logo and Components

We’re thrilled to announce the first official pre-release packages for the Windows Community Toolkit 8.0 have been released to NuGet.org! 🎉🎉🎉 This blog is going to provide a brief overview of how to get started using these preview packages and how to provide feedback.

This has been a culmination of nearly two years of work in understanding how we can better maintain the Toolkit, make it easier to contribute to, target multiple platforms with a single codebase, and still maintain a high quality bar!

If you’re still new to the Toolkits, you can find an introduction video to them here.

With this single-codebase, our components will work for WinUI 2 on UWP, the Windows App SDK + WinUI 3, and Uno Platform (using WinUI 2 or 3)!!!

Note though, even with our upcoming official release, some features may not be available on all platforms due to platform limitations or unimplemented APIs. Our initial focus has been on UWP and Windows App SDK compatibility, followed by Web Assembly (WASM). If you find an issue on a particular platform, please let us know, but we may defer you to the underlying platform’s repository if an API is missing.

If you’d like additional information about some of the things referred to in this blog, be sure to read our previous update here.

At a Glance 🔍

One namespace to rule them all 💍

Regardless of which new package you use (see below), the namespaces for code within the packages are now unified with a root of CommunityToolkit.WinUI.*. This ensures that if you target multiple platforms or migrate between them, no code referencing the Toolkit needs to change (just the package)!

Available Packages

Be sure in Visual Studio to check the “Include prerelease” checkbox next to the NuGet Package Manager search box.

Then search for either CommunityToolkit.Uwp or CommunityToolkit.WinUI (Windows App SDK), depending on your target platform, and one of the packages listed below should appear. Today’s release is version 8.0.230823-rc.

If you’re using Uno Platform, the same package can be used across your various platform heads now! Just be sure to select the package that corresponds to the target of your Windows platform head, either .Uwp. or .WinUI. for the Windows App SDK corresponding to Uno.UI and Uno.WinUI respectively.

‘✨’ denotes new or updated packages/features from version 7.1.

‘🎨’ denotes updated XAML styling from version 7.1.

‘💻’ denotes packages which only target UWP/WindowsAppSDK. However, its absence does not imply that every feature will work across all platforms (see note in introduction).

🔥🐉 Note: Mixing and matching these new 8.0 packages with existing Windows Community Toolkit 7.x packages, especially UI controls, can lead to issues with the namespace changes and dependencies on common code (like the Visual Tree extensions). If there’s something that we haven’t yet ported but you need, open a discussion to let us know or claim it and contribute!

New Projects

✨ Did you know that just using this latest preview version and providing feedback is a way of contributing? ✨

If you want to try our pre-release packages in a new UWP, Windows App SDK, or Uno Platform project, you can use the following instructions:

  1. In Visual Studio, right-click your application project (for Uno you can use the common Class Library Project), and select “Manage NuGet Packages“.
  2. Select a package above based on your target framework. For UWP/Uno.UI/WinUI2, use .Uwp. packages or for WindowsAppSDK/Uno.WinUI/WinUI3, use .WinUI. packages.
  3. Find that package in the search box (be sure ‘Include Prerelease’ is checked).
  4. Click ‘Install’ on the right-hand side. You should see the version number starting with 8.0.
  5. For UWP/Uno.UI, be sure the WinUI 2 Theme Resources have been set up, if you’re using any UI Controls.

And that should be it!

Existing Projects

If you have an existing project that is using the Windows Community Toolkit 7.1 packages, there’s a few changes you’ll need to make.

  1. Identify if you’re using UWP/Uno.UI based packages or WindowsAppSDK/Uno.WinUI based packages by looking at your application’s csproj file.
    • Microsoft.Toolkit.Uwp or Uno.Microsoft.Toolkit.Uwp packages will map to CommunityToolkit.Uwp.
    • CommunityToolkit.WinUI or Uno.CommunityToolkit.WinUI packages will map to CommunityToolkit.WinUI.
  2. Remove the old 7.1 packages from your project and add the new packages. For Uno projects, you can remove references from all platform projects and instead include a single reference in your Class Library project.
  3. Update all usings and xmlns includes to use the new base namespace of CommunityToolkit.WinUI.*. Note that the .UI. part of namespaces and packages has been removed. For UWP/Uno.UI based projects, this should be Microsoft.Toolkit.Uwp.* currently.
  4. If you have trouble locating a component or API, search the new repository to see which package it resides in. This will match the csproj file name in the components/*/src/ directory. We’ll provide a better mapping guide in the future.

That should be it!

We recommend that if you’re also migrating between UWP and WindowsAppSDK, you perform the Toolkit migration first. Once that’s complete and working, no other changes will need to be made to Toolkit code when migrating to the Windows App SDK. However, we do recommend switching package references from the .Uwp. to .WinUI. versions as a final step. By matching the proper packages, it allows migrating to Uno Platform for your project without requiring additional changes to Toolkit-based code (for packages that support Uno Platform).

For further information, if you’re also upgrading to WinUI 3, see platform documentation here or Uno’s documentation here.

What about the current repository?

The Toolkit has grown a lot since its inception, both in terms of the amount of code and the number of people using it. As we bring over components, we want to ensure they’re working across our supported platforms, well-documented, showcased with samples, thoroughly tested, and up-to-date with the latest Windows design language.

As part of this effort, we created Windows Community Toolkit Labs as a place where we can incubate and iterate over new ideas, try things out without worry, see what gets used by the community, and then decide to bring them into the main repository when they’re ready and well-tested.

We’ve brought over the most commonly used controls from the existing codebase already, but this won’t include everything even when we reach the stable 8.0 release. Future releases may include more, with a mix of new and prior components. Some things are even in the platform now, so we want to work on providing better guidance on how to utilize built-in equivalents for prior Toolkit components.

Based on feedback from our community in our new repository, we will be archiving the existing WindowsCommunityToolkit repository to provide better access to its codebase for future migrations. This should allow us to migrate issues and discussions as needed as well to our new repository and Windows Community Toolkit Labs.

Feedback & Contributing

Not sure how to get started contributing? Don’t worry! Did you know that just providing feedback on what we’re doing and our new components is contributing?!?

Join in our discussion about this 8.0 prerelease on GitHub here. We’re also active on Discord in the UWP Community server #community-toolkit channel here.

You can also reach out on Social Media with the #WindowsCommunityToolkit hashtag. Find us at @XAMLLlama, @XAMLLlama@hachyderm.io, @Niels9001, and @Arlodottxt@fosstodon.org.

If you’re interested in contributing documentation or code, here are a few extra steps:

  • Take a look at our repository and clone it.
  • Use the OpenSolution.bat file for a component and try to build it following the steps in the readme.
  • Back on GitHub, find an unclaimed TODO item for a component.
  • Comment to chime in with what you’d like to do, and we can help you get started toward your first Pull Request (PR)!

About Uno Platform

Uno Platform Logo

For those new to Uno Platform – it allows for creation of pixel-perfect, single-source C# and XAML apps which run natively on Windows, iOS, Android, macOS, Linux and Web via WebAssembly. It offers Figma integration for design-development handoff, and a set of extensions to bootstrap your projects. Uno Platform is free and Open Source (Apache 2.0) and available on GitHub.

🙋‍♂️ Not sure how to get started with WinUI 3, in general? Check out our video from .NET Conf.

Category
ifdef-Windows
Topics
.NETUno PlatformUWPWindows Community ToolkitWindowsAppSDKWinUI3

Author

Michael Hawker
Michael Hawker
Senior Software Engineer

Michael A. Hawker, a.k.a. XAML Llama, is a Senior Software Engineer for the Apps, Partners, and Store (APS) team at Microsoft. APS focuses on driving the ISV ecosystem through technical engagement with partners and industry as well as providing essential first party experiences. Michael is the maintainer of the Windows Community Toolkit and prior “App Ninja”. He is also the creator of XAML Studio, a Microsoft Garage project.

1 comment

Discussion is closed. Login to edit/delete existing comments.

Newest
Newest Popular Oldest
  • Georgi Hadzhigeorgiev

    Cool, can’t wait for final release, thanks!

Read next