Windows Community Toolkit 8.0 Pre-release
The Windows Community Toolkit 8.0 Pre-release
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.
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 🔍
- Unified Namespace
- Available Packages
- New Projects
- Existing Projects
- What about the current repository?
- Feedback & Contributing
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)!
Be sure in Visual Studio to check the “Include prerelease” checkbox next to the NuGet Package Manager search box.
Then search for either
CommunityToolkit.WinUI (Windows App SDK), depending on your target platform, and one of the packages listed below should appear. Today’s release is version
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
.WinUI. for the Windows App SDK corresponding to
- Animations – WinUI 2/UWP – WinUI 3/WindowsAppSDK
- Behaviors ✨ – WinUI 2/UWP – WinUI 3/WindowsAppSDK ✨
- Collections – WinUI 2/UWP – WinUI 3/WindowsAppSDK
- Controls – All the following packages are under the
CommunityToolkit.WinUI.Controlsnamespace (see above):
- CameraPreview 💻 – WinUI 2/UWP – WinUI 3/WindowsAppSDK
- HeaderedControls ✨ – WinUI 2/UWP – WinUI 3/WindowsAppSDK ✨
- ImageCropper 💻 – WinUI 2/UWP – WinUI 3/WindowsAppSDK
- LayoutTransformControl – WinUI 2/UWP – WinUI 3/WindowsAppSDK
- MetadataControl – WinUI 2/UWP – WinUI 3/WindowsAppSDK
- Primitives – WinUI 2/UWP – WinUI 3/WindowsAppSDK
- RadialGauge 💻🎨✨ – WinUI 2/UWP – WinUI 3/WindowsAppSDK ✨
- RangeSelector 🎨 – WinUI 2/UWP – WinUI 3/WindowsAppSDK
- RichSuggestBox 💻🎨 – WinUI 2/UWP – WinUI 3/WindowsAppSDK
- Segmented ✨ – WinUI 2/UWP – WinUI 3/WindowsAppSDK ✨
- SettingsControls ✨ – WinUI 2/UWP – WinUI 3/WindowsAppSDK ✨
- Sizers 🎨✨ – WinUI 2/UWP – WinUI 3/WindowsAppSDK ✨
- TokenizingTextBox 🎨 – WinUI 2/UWP – WinUI 3/WindowsAppSDK
- Converters – WinUI 2/UWP – WinUI 3/WindowsAppSDK
- DeveloperTools – WinUI 2/UWP – WinUI 3/WindowsAppSDK
- Extensions – WinUI 2/UWP – WinUI 3/WindowsAppSDK
- Helpers – WinUI 2/UWP – WinUI 3/WindowsAppSDK
- Lottie 💻 – WinUI 2/UWP – WinUI 3/WindowsAppSDK
- Media 💻 – WinUI 2/UWP – WinUI 3/WindowsAppSDK
- Triggers – WinUI 2/UWP – WinUI 3/WindowsAppSDK
‘✨’ 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!
✨ Did you know that just using this latest preview version and providing feedback is a way of contributing? ✨
- In Visual Studio, right-click your application project (for Uno you can use the common Class Library Project), and select “Manage NuGet Packages“.
- Select a package above based on your target framework. For UWP/Uno.UI/WinUI2, use
.Uwp.packages or for WindowsAppSDK/Uno.WinUI/WinUI3, use
- Find that package in the search box (be sure ‘Include Prerelease’ is checked).
- Click ‘Install’ on the right-hand side. You should see the version number starting with
- 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!
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.
- Identify if you’re using UWP/Uno.UI based packages or WindowsAppSDK/Uno.WinUI based packages by looking at your application’s csproj file.
Uno.Microsoft.Toolkit.Uwppackages will map to
Uno.CommunityToolkit.WinUIpackages will map to
- 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.
- 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
- 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
.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).
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.
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.
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.batfile 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
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.