# 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](https://www.telerik.com/maui-ui#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.

<CtaPanelMauiOverview></CtaPanelMauiOverview>

> important 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 9.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 [migrating a Xamarin.Forms application to the .NET SDK-style project format](https://docs.microsoft.com/en-us/dotnet/maui/get-started/migrate).

1. Convert the projects from the .NET framework to the .NET SDK style.
2. Update the namespaces.
3. Update any incompatible NuGet packages.
4. Address any breaking API changes.
5. 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 either of the following approaches:

1. 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 official Microsoft guide for [hosting packages in local NuGet feeds](https://docs.microsoft.com/en-us/nuget/hosting-packages/local-feeds).

### 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 packages from NuGet](https://www.telerik.com/maui-ui/documentation/get-started/quickstart).

## 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:

```C#
using Telerik.Maui.Controls.Compatibility;
```

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

```C#
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, 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](https://www.telerik.com/maui-ui/documentation/controls/entry/migrate-from-xamarin).

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 product roadmap](https://www.telerik.com/support/whats-new/maui-ui/roadmap).
* For logged issues and feature requests for new components, go to the [Telerik UI for .NET MAUI feedback portal](https://feedback.telerik.com/maui).
* Alternatively, directly contact the team through the [Telerik technical support ticketing system](https://www.telerik.com/account/support-center/contact-us/technical-support?pid=2338), the [Telerik UI for .NET MAUI community forums](https://www.telerik.com/forums/maui), or the [Telerik UI for .NET MAUI feedback portal](https://feedback.telerik.com/maui).

### Migration Guides for .NET MAUI Components

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

* [Migrate the Accordion control from Xamarin to .NET MAUI](https://www.telerik.com/maui-ui/documentation/controls/accordion/xamarin-migration)
* [Migrate the AutoComplete control from Xamarin to .NET MAUI](https://www.telerik.com/maui-ui/documentation/controls/autocomplete/xamarin-migration)
* [Migrate the BadgeView control from Xamarin to .NET MAUI](https://www.telerik.com/maui-ui/documentation/controls/badgeview/xamarin-migration)
* [Migrate the Barcode control from Xamarin to .NET MAUI](https://www.telerik.com/maui-ui/documentation/controls/barcode/xamarin-migration)
* [Migrate the Border control from Xamarin to .NET MAUI](https://www.telerik.com/maui-ui/documentation/controls/border/xamarin-migration)
* [Migrate the BusyIndicator control from Xamarin to .NET MAUI](https://www.telerik.com/maui-ui/documentation/controls/busyindicator/xamarin-migration)
* [Migrate the Button control from Xamarin to .NET MAUI](https://www.telerik.com/maui-ui/documentation/controls/button/xamarin-migration)
* [Migrate the Calendar control from Xamarin to .NET MAUI](https://www.telerik.com/maui-ui/documentation/controls/calendar/xamarin-migration)
* [Migrate the Chart control from Xamarin to .NET MAUI](https://www.telerik.com/maui-ui/documentation/controls/chart/xamarin-migration)
* [Migrate the CheckBox control from Xamarin to .NET MAUI](https://www.telerik.com/maui-ui/documentation/controls/checkbox/xamarin-migration)
* [Migrate the ComboBox control from Xamarin to .NET MAUI](https://www.telerik.com/maui-ui/documentation/controls/combobox/xamarin-migration)
* [Migrate the Conversational UI (Chat) control from Xamarin to .NET MAUI](https://www.telerik.com/maui-ui/documentation/controls/chat/xamarin-migration)
* [Migrate the DataForm control from Xamarin to .NET MAUI](https://www.telerik.com/maui-ui/documentation/controls/dataform/xamarin-migration)
* [Migrate the DataGrid control from Xamarin to .NET MAUI](https://www.telerik.com/maui-ui/documentation/controls/datagrid/xamarin-migration)
* [Migrate the DatePicker control from Xamarin to .NET MAUI](https://www.telerik.com/maui-ui/documentation/controls/datepicker/xamarin-migration)
* [Migrate the DateTimePicker control from Xamarin to .NET MAUI](https://www.telerik.com/maui-ui/documentation/controls/datetimepicker/xamarin-migration)
* [Migrate the Entry control from Xamarin to .NET MAUI](https://www.telerik.com/maui-ui/documentation/controls/entry/migrate-from-xamarin)
* [Migrate the ImageEditor control from Xamarin to .NET MAUI](https://www.telerik.com/maui-ui/documentation/controls/imageeditor/migrate-from-xamarin)
* [Migrate the ListPicker control from Xamarin to .NET MAUI](https://www.telerik.com/maui-ui/documentation/controls/listpicker/xamarin-migration)
* [Migrate the MaskedEntry control from Xamarin to .NET MAUI](https://www.telerik.com/maui-ui/documentation/controls/maskedentry/migrate-from-xamarin)
* [Migrate the ProgressBar control from Xamarin to .NET MAUI](https://www.telerik.com/maui-ui/documentation/controls/progressbar/migrate-from-xamarin)
* [Migrate the RichTextEditor control from Xamarin to .NET MAUI](https://www.telerik.com/maui-ui/documentation/controls/richtexteditor/migrate-from-xamarin)
* [Migrate the Scheduler control from Xamarin to .NET MAUI](https://www.telerik.com/maui-ui/documentation/controls/scheduler/migrate-from-xamarin)
* [Migrate the SignaturePad control from Xamarin to .NET MAUI](https://www.telerik.com/maui-ui/documentation/controls/signaturepad/migrate-from-xamarin)
* [Migrate the SlideView control from Xamarin to .NET MAUI](https://www.telerik.com/maui-ui/documentation/controls/slideview/xamarin-migration)
* [Migrate the TemplatedPicker control from Xamarin to .NET MAUI](https://www.telerik.com/maui-ui/documentation/controls/templatedpicker/xamarin-migration)
* [Migrate the TimePicker control from Xamarin to .NET MAUI](https://www.telerik.com/maui-ui/documentation/controls/timepicker/xamarin-migration)
* [Migrate the TimeSpanPicker control from Xamarin to .NET MAUI](https://www.telerik.com/maui-ui/documentation/controls/timespanpicker/xamarin-migration)
* [Migrate the TreeView control from Xamarin to .NET MAUI](https://www.telerik.com/maui-ui/documentation/controls/treeview/xamarin-migration)

## 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 [porting Xamarin custom renderers to .NET MAUI handlers](https://github.com/dotnet/maui/wiki/Porting-Custom-Renderers-to-Handlers).

## Video Tutorial

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

For a written migration path, follow this article's [Xamarin.Forms migration steps](https://www.telerik.com/maui-ui/documentation/migrate-to-net-maui#step-1-xamarinforms-to-net-maui-migration-steps), [Telerik reference replacement](https://www.telerik.com/maui-ui/documentation/migrate-to-net-maui#step-2-replace-the-telerik-references), [control registration](https://www.telerik.com/maui-ui/documentation/migrate-to-net-maui#step-3-register-the-net-maui-controls), [component migration guides](https://www.telerik.com/maui-ui/documentation/migrate-to-net-maui#migration-guides-for-net-maui-components), and [renderer-to-handler guidance](https://www.telerik.com/maui-ui/documentation/migrate-to-net-maui#step-5-port-custom-renderers-to-handlers). These instructions are related topic documentation, not a verbatim transcript of the video.

<iframe width="560" height="315" src="https://www.youtube.com/embed/-AeFIjW0Jgc" title="One of the questions the .NET MAUI team has heard the most is What do I have to do to my Xamarin app to upgrade?" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

## See Also

* [Explore Telerik UI for .NET MAUI Sample Applications](https://www.telerik.com/maui-ui/documentation/demos-and-sample-apps/overview)

<VideoMetadata 
 name="Upgrading your Xamarin Forms App to .NET MAUI | DevReach 2023"
 description="One of the questions the .NET MAUI team has heard the most is What do I have to do to my Xamarin app to upgrade? Good news - it's a really straightforward process! Join Maddy Montaquila, .NET MAUI PM, as she demystifies the upgrade process and shows you the tools you can use to upgrade your app so you can leverage the magic of MAUI in no time!"
 thumbnail-url="https://img.youtube.com/vi/-AeFIjW0Jgc/maxresdefault.jpg"
 upload-date="2023-11-22T00:00:00Z"
 duration="PT52M22S"
 content-url="https://youtu.be/-AeFIjW0Jgc"
 embed-url="https://www.youtube.com/embed/-AeFIjW0Jgc">
</VideoMetadata>
