Xamarin to .NET MAUI Migration

This guide provides the information you need to convert your application, which was built with Telerik UI for Xamarin.Forms controls, to a .NET MAUI one, which uses the Telerik UI for .NET MAUI components. By migrating to .NET MAUI, you will be able to receive the latest features and mobile operating system support for your project.

Telerik UI for .NET MAUI does not provide a direct alternative to Xamarin.iOS or Xamarin.Android in .NET. However, migrating to .NET MAUI and switching to the Telerik UI for .NET MAUI controls ensures that you will receive the latest framework and UI controls updates.

Step 1: Xamarin.Forms to .NET MAUI Migration Steps

While you don't need to fully rewrite your existing Xamarin project, you will still need to make changes to ensure its smooth transition to .NET 8.0 and, thus, upgrade Xamarin to .NET MAUI.

The following list summarizes the required steps of the Xamarin to MAUI migration. For the detailed guide, go to the official Microsoft documentation on how to migrate your Xamarin.Forms application to the .NET SDK style.

Convert the projects from the .NET framework to the .NET SDK style.
Update the namespaces.
Update any incompatible NuGet packages.
Address any breaking API changes.
Run the converted application and verify that it functions correctly.

Step 2: Replace the Telerik References

Once your Xamarin.Forms app has been migrated to .NET MAUI, you’re ready to replace the Telerik UI for Xamarin references with the Telerik UI for .NET MAUI ones and, then, register the controls.

To reference the .NET MAUI controls, use wither of the following approaches:

Manually add the required Telerik packages to the solution. or 1.Reference the Telerik NuGet packages.

Manually Adding the Assemblies

Replace the Telerik Xamarin assemblies with the Telerik UI for .NET MAUI package, using the local NuGet feeds. To get the Telerik UI for .NET MAUI .nupkg file, download any of the following:

The .msi or .pkg automated installer.
The .zip file that contains the .nupkg file.
The Telerik.UI.for.Maui.[Version].nupkg file from your Telerik account.

When the .nupkg file is available on your machine, you are ready to set up the local NuGet feed. For the detailed guide on setting up the local NuGet package, go to the Local feeds official Microsoft topic.

Referencing the Telerik .NET MAUI NuGet Packages using the Telerik NuGet Server

When using the Telerik NuGet server, you can install the Telerik.UI.for.MAUI NuGet package in the .NET MAUI Application.

For the detailed guide on configuring the Telerik NuGet Server and installing the Telerik UI for .NET MAUI NuGet package, go to the article about installing Telerik UI for .NET MAUI with NuGet.

Step 3: Register the .NET MAUI Controls

Register the Telerik controls through the Telerik.Maui.Controls.Compatibility.UseTelerik extension method that will be called inside the CreateMauiApp method of the MauiProgram.cs file of your project:

1. Go to the MauiProgram.cs file and add the needed namespace:

using Telerik.Maui.Controls.Compatibility;

2. Call the UseTelerik() method inside the CreateMauiApp method:

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseTelerik()
            .UseMauiApp<App>()
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
            });

        return builder.Build();
    }
}

Step 4: Replace the Xamarin Components with Their .NET MAUI Counterparts

To complete the Xamarin to MAUI migration, replace the Telerik UI for Xamarin components with their Telerik UI for .NET MAUI counterparts.

Some of the Telerik .NET MAUI controls have dedicated migration articles. These articles provide tables describing the relevant API changes so you can review the differences between Xamarin and .NET MAUI.

Notes on Component Migration

Before you start, note the following:

You can directly replace some components, such as the DataGrid, ListView, Barcode, Button, and more, by changing their respective namespace. All Telerik UI for .NET MAUI controls use a common xmlns:telerik="http://schemas.telerik.com/2022/xaml/maui" telerik namespace.
Some components, such as the MaskedEntries, Entry, Pickers, and TabView, require API changes. For the detailed guide, go to their corresponding article on converting the Xamarin control to .NET MAUI, for example, the topic about migrating the Entry from Xamarin.Forms.

If you use components that are not yet available in Telerik UI for .NET MAUI, note that the team is constantly working on enriching the suite by adding more controls to it. To get more information about what is expected, refer to the following resources:

For more information on the planned releases, go to the Telerik UI for .NET MAUI Roadmap.
For logged issues and feature requests for new components, go to the Telerik UI for .NET MAUI Feedback Portal.
Alternatively, directly contact the team through the support ticketing system, the forums, or the Feedback Portal.

Migration Guides for .NET MAUI Components

The following list includes the links to the available Xamarin to MAUI migration guides for Telerik UI controls:

Step 5: Port Custom Renderers to Handlers

To customize the appearance and behavior of the native controls on each platform, Xamarin.Forms widely uses custom renderers and platform effects. In .NET MAUI, these renderers are replaced with handlers and, when migrating Xamarin to MAUI, you will need port the custom renderers to handlers.

For the detailed guide, go to the official Microsoft documentation on GitHub about how to migrate custom renderers to handlers.

Video Tutorial

The following video demonstrates how you can upgrade your Xamarin.Forms App to .NET MAUI