Introducing .NET MAUI Compatibility for the Xamarin Community Toolkit

Brandon Minnick

Note: This is a follow to last month’s announcement: The Future of Xamarin Community Toolkit

The Xamarin Community Toolkit team is excited to announce two new .NET MAUI-compatible versions of the toolkit:

• Xamarin.CommunityToolkit.MauiCompat
• Xamarin.CommunityToolkit.Markup.MauiCompat

These MauiCompat libraries align to latest release of Xamarin.CommunityToolkit; the main difference being that these are for your .NET MAUI apps, whereas Xamarin.CommunityToolkit is for your Xamrain.Forms apps.

Today’s MauiCompat release includes support for iOS and Android. Future MauiCompat releases will include support for iOS, Android, macOS and UWP.

Which Apps Should Use MauiCompat?

✅ Existing Xamarin.Forms apps migrating to .NET MAUI

The MauiCompat libraries are created as a helpful step in your migration from Xamarin.Forms to .NET MAUI. These libraries ensure that you can access all of the features of Xamarin.CommunityToolkit in your .NET MAUI apps without breaking changes, helping to make your migration to .NET MAUI easier.

We recommend eventually replacing Xamarin.CommunityToolkit.MauiCompat with the new .NET MAUI Toolkit, CommunityToolkit.Maui, to take advange of new features and optimizations (see comarison chart below).

❌ Brand new .NET MAUI apps

For new (aka greenfield) .NET MAUI apps, use the new .NET MAUI Community Toolkit, which is fully optimized for .NET MAUI, instead of Xamarin.CommunityToolkit.MauiCompat.

Xamarin.CommunityToolkit.MauiCompat vs CommunityToolkit.Maui

Getting Started With MauiCompat

Both MauiCompat libraries are available as a NuGet package that can be added to any .NET 6 project targeting net6.0-ios and net6.0-android:

1. Open existing project in Visual Studio

2. In the Visual Studio Package Manager Console, enter the following command:

   Install-Package Xamarin.CommunityToolkit.MauiCompat

   or

   Install-Package Xamarin.CommunityToolkit.Markup.MauiCompat

3. To add the namespace to the toolkit:

   • In your C# page, add:

     using Xamarin.CommunityToolkit;

     or

     using Xamarin.CommunityToolkit.Markup;

   • In your XAML page, add the namespace attribute:

     xmlns:xct="http://xamarin.com/schemas/2020/toolkit"

4. Register the renderer(s) you want to use in the Startup.cs file. You can either only register the renderer(s) you actually need, or register all the renderers that are inside of the Xamarin Community Toolkit. Have a look at the code snippet below how to do both.

public void Configure(IAppHostBuilder appBuilder)
{
    appBuilder
        .UseMauiApp<App>()
        .ConfigureMauiHandlers(handlers =>
        {
            // Register ALL handlers in the Xamarin Community Toolkit assembly
            handlers.AddCompatibilityRenderers(typeof(Xamarin.CommunityToolkit.UI.Views.MediaElementRenderer).Assembly)

            // Register just one handler for the control you need
            handlers.AddCompatibilityRenderer(typeof(Xamarin.CommunityToolkit.UI.Views.MediaElement), typeof(Xamarin.CommunityToolkit.UI.Views.MediaElementRenderer));
        });
}

5. Check out the rest of the documentation to learn more about implementing specific features: https://docs.microsoft.com/xamarin/community-toolkit/

Good to Know

We have released this package under the alpha tag. Because this MauiCompat package is being built alongside the preview of .NET MAUI, there are still some things that need to be etched out on both sides. We’re releasing this now so that we can get your feedback early on and make sure the MauiCompat Toolkit is ready to use by the time .NET MAUI is released.

Non-Renderer Controls

There are some controls that don’t require a (separate) renderer, i.e. Shield. Those controls are not supported at the moment. We have a good idea how to add support for this, it just hasn’t been realized yet. If you do try to use a “non-renderer” control, you will see an error messages which states that a handler hasn’t been found for type X.

However, this error will also come up when you didn’t register the renderer for the control you’re trying to use (see above), so make sure you have that in place.

Markup Should Just Work

The Markup package should just work as it doesn’t rely on renderers. We did make it compatible with all the current .NET MAUI changes and namespaces so you can continue enjoying the markup extensions as before.

Other Known Issues & Reporting Issues

In .NET MAUI there has been a change in the Color object. Therefore there might be some issues in that area, although that might not be apparent to you on the outside. Whenever you run into a NullReferenceException you might want to try setting all the color properties of a control to an explicit value and see if that resolves the issue. If not, please let us know what you’re seeing so we can have a look.

If you find any issues, please report them on the regular Xamarin.CommunityToolkit repository, but make sure that you mention that this is about the MauiCompat package just so we know where to look for issues.

Release Schedule

Going forward, we will release a MauiCompat NuGet package alongside each new release of Xamarin.CommunityToolkit and Xamarin.CommunityToolkit.Markup.

For example, the latest release of Xamarin.CommunityToolkit is v1.3.0-pre2, and thus today’s release of Xamarin.CommunityToolkit.MauiCompat is also v1.3.0-alpha2. The only minor difference here is the pre and alpha tag for now. This should be more in line in future releases.

To keep the MauiCompat releases packages aligned with Xamarin.CommunityToolkit, we follow these steps:

1. Branch from the latest Xamarin.CommunityToolkit Release (aka its Git Tag)
   • This ensures the logic in the MauiCompat libraries exactly matches the logic in the Xamarin.CommunityToolkit release
2. Replace the Xamarin.Forms dependency with the .NET MAUI dependency
   • <PackageReference Include="Xamarin.Forms" /> -> <UseMaui>true</UseMaui>
3. Update to .NET 6
   • <TargetFramework>netstandard2.1</TargetFramework> -> <TargetFrameworks>net6.0-ios;net6.0-android</TargetFramework>
4. Update the namespaces
   • using Xamarin.Forms -> using Microsoft.Maui

(There are also some references to Xamarin.Forms.* in specific files that we indiviually update to Mirosoft.Maui.*)

We’ve documented the steps we follow to convert Xamarin.CommunityToolkit to Xamarin.CommunityToolkit.MauiCompat, and you can find them here: https://github.com/xamarin/XamarinCommunityToolkit/blob/main/MauiCompatSteps.md

Summary

When migrating your existing Xamarin.Forms app to .NET MAUI, levarage these MauiCompat libraries. They contain the same logic as their Xamarin.CommunityToolkit counterpart, targeting .NET MAUI instead of Xamarin.Forms.

Eventually, you will want to migrate to the .NET MAUI Toolkit to take advantage of new features and optimizations, as we will sunset the MauiCompat libraries alongside Xamarin.Forms in November 2022

Brandon Minnick Developer Advocate, Developer Relations

Follow