Migration Guide from v7 to v8

Removed Features 🦴

The Toolkit is huge! It’s had a lot of features added over the course of the last 7 years. Unfortunately, this means we couldn’t migrate everything in this initial transition. Also, some features may not be available on all platforms due to platform limitations or unimplemented APIs.

If there’s a feature from the Toolkit that wasn’t migrated (and not listed below), open a discussion to garner support for future migration or to get information on contributing to migrate it for everyone.

The following is a partial list of known things which are not included in this release:

• AdaptiveGridView – has been superseded by UniformGridLayout for ItemsRepeater.
• DataGrid – is a project of its own with over 30k lines of code. This was originally contributed by a community member, but complexity has ballooned into near un-maintainability and we are working on a leaner and more flexible DataTable experiment over in Windows Community Toolkit Labs.
  • You can safely use the 7.x DataGrid alongside the newer 8.x packages, as it has no dependencies on the toolkit itself.
• DropShadowPanel – has been replaced by our own Attached Shadows in the Extensions and Media package.
• Expander – is part of WinUI now.
• InAppNotification – has been replaced by the StackedNotificationsBehavior in our Behaviors package to build on top of the platform InfoBar control.
• MarkdownTextBlock – had a custom Markdown Parser and couldn't be properly ported because of this. However, we've worked with the community to build a replacement in WCT Labs based on the excellent Markdig library, and this is available from the Labs Preview Feed.
• Menu – is part of WinUI now, see MenuBar.
• Notification helpers – have migrated to the Windows App SDK, see their documentation here to get started. Direct issues to the WindowsAppSDK repository.
• RadialGradientBrush – is part of WinUI now.
• RadialProgressBar – is part of WinUI now, see ProgressRing documentation and set IsIndeterminate to false.
• XAML Islands Helpers – The tooling in this repository is no longer maintained. XAML Islands is part of the Windows App SDK and shipped in v1.4. Direct issues to the WindowsAppSDK.

Migration Notes 🚚

Be sure to read the rest of the breaking change notes above! 😉

🔥🐉 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!

Most UI controls have their own package now under CommunityToolkit.<Uwp|WinUI>.Controls.* (see next section below); we’re working to have a meta package again, but do not have one at this time.

For individual grouped control packages of 7.x, you can find the following changes:

• From Controls.Core:
  • DropShadowPanel has been replaced with Attached Shadows in the Extensions and Media packages.
  • InAppNotification is now the StackedNotificationsBehavior for WinUI’s InfoBar in the Behaviors package.
  • Menu is part of WinUI now, see MenuBar.
  • RadialProgressBar is part of WinUI’s ProgressRing now, IsIndeterminate=“False”.
• From Controls.Layout:
  • Expander is part of WinUI now.
  • GridSplitter is part of the Sizers package, it’s also been entirely re-written, but with defaults should look/behave the same, if not better!
  • “Headered” controls are part of the HeaderedControls package, HeaderedItemsControl now uses ItemsPresenter‘s Header and Footer new, Orientation has been removed, customize the ItemsPanel instead.
• For parts of the Uwp/WinUI and Uwp/WinUI.UI packages, look for our Collections, Converters, Extensions, Helpers, and Triggers packages.

Other controls either have their own package or have not been migrated yet. Search and then open a discussion if you need assistance.

Dual packages for UWP and WinUI 🎭

The package names have been aligned, while UWP and WinUI 3 had to remain in separate packages.

UWP

• If you're using UWP, you were using the Microsoft.Toolkit.Uwp.UI.* packages.
• Uninstall these and install the new 8.x packages under CommunityToolkit.Uwp.*.

WinAppSdk / WinUI 3

• If you're using WinUI 3 via the WinAppSdk, you were using the CommunityToolkit.WinUI.UI.* packages.
• Uninstall these and install the new 8.x packages under CommunityToolkit.WinUI.*.

One namespace to rule them all 💍

We've cleaned things up for you, and we've kept it simple enough that you can find-and-replace your way to the new packages.

In 8.x, the namespaces between UWP and WinAppSdk were merged, and the redundant *.UI.* in our package names was removed.

• If you're on UWP, update all toolkit usings and xmlns from Microsoft.Toolkit.Uwp.UI.* to the new CommunityToolkit.WinUI.* namespace.
• If you're on WinAppSdk / WinUI 3, update all toolkit usings and xmlns from CommunityToolkit.WinUI.UI.* to the new CommunityToolkit.WinUI.* namespace.

Regardless of which package you use, the namespaces for code within the packages are now unified into a root of CommunityToolkit.WinUI.* for all platforms.

This ensures that if you target multiple platforms or migrate between them, no code referencing the Toolkit needs to change, just the package!

Uno Platform now supported 🎉

If you weren't using Uno Platform, you can skip this step.

Uno Platform is now supported out of the box by the Windows Community Toolkit and Windows Community Toolkit Labs.

Previously, Uno Platform had its own fork of the toolkit. In your project, this fork was referenced behind a conditional.

In WinUI 3, this may have looked like:

<ItemGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows'">
  <PackageReference Include="CommunityToolkit.WinUI.UI.Controls" Version="7.1.2" />
  <!-- more community toolkit references here -->
</ItemGroup>

<ItemGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) != 'windows'">
  <PackageReference Include="Uno.CommunityToolkit.WinUI.UI.Controls" Version="7.1.200" />
  <!-- more uno community toolkit references here -->
</ItemGroup>

and similar for the UWP packages.

These are no longer necessary. When you update to v8, you can remove references to the Uno fork and all Condition statements around the 8.x packages, simplifying to:

<ItemGroup>
  <PackageReference Include="CommunityToolkit.WinUI.Animations" Version="8.0.240109" />
  <!-- more community toolkit references here -->
</ItemGroup>

or, for UWP:

<ItemGroup>
  <PackageReference Include="CommunityToolkit.Uwp.Animations" Version="8.0.240109" />
  <!-- more community toolkit references here -->
</ItemGroup>

Since the Community Toolkit now supports Uno Platform out of the box, you can use the same packages across all platforms.

Note on non-Windows platform compatibility

While all packages are supported for UWP and WinAppSDK, this is not the case for Uno Platform.

The Uno Platform "polyfills" many Windows APIs, but not all. Some components (like Media) rely heavily on Composition APIs that are not yet supported by Uno, and so the Media package does not have the Uno-powered MultiTargets enabled as the component would be broken out of the box.

In cases like this, we would rather disable the package for Uno than to enable it and have it not work. To fill these functional gaps, we encourage seeking or helping to build an Uno-compatible alternative.

In limited cases, packages may have partial support for Uno where the TargetFramework is enabled but not all Toolkit code is expected to work out of the box.

• The only package in this scenario right now is Animations, which has a special FrameworkLayer abstraction that enables AnimationBuilder and CustomAnimation on Uno-powered MultiTargets, but doesn't extend to ImplicitAnimationSet or Connected Animations. See #319 for tracking.

The majority of controls are supported on all platforms, as this is the default.

If you find a package that doesn't work as expected on Uno, please open an issue or discussion to let us know.

Migration trouble?

If you're having trouble migrating, open a discussion or issue on GitHub and we'll help you out. We're also available in the Windows App Community Discord for real-time help.