Premigration Analysis

A robust analysis of the requirements, effort, time, and resources is fundamental in every project. While you might have room for adjustments with new projects, migrating existing projects to more recent technologies could give you less freedom, especially if such projects are already in production. Your customers and stakeholders likely don’t care about the backing technology—they expect to have the same features or an improved version of your apps. For these reasons, doing a premigration analysis helps you understand if upgrading from Xamarin.Forms to .NET MAUI can give users what they expect. It’ll also tell you if there are any issues you need to fix. This chapter guides you through performing a premigration analysis, which you can extend according to your needs. All the points summarized in this chapter will be developed in the rest of the book.

Migrating C# code

As you read in Chapter 1, .NET MAUI is part of the .NET code base. In general, your existing C# code will work when brought from Xamarin.Forms to .NET MAUI. However, you might encounter the following exceptions:

• Code-breaking changes in the .NET API might require rewriting some code based on Mono. This is quite unlikely, but it can happen. The code editor in Visual Studio and the background compiler will quickly help you understand how your code should be changed.
• Some objects have different names or different members. An example is the Color class in Xamarin.Forms, which is referred to as Colors in .NET MAUI.
• .NET MAUI simplifies the way you access platform-specific features with a fully .NET-oriented approach, including an enhanced version of the Essentials API.

One difference is certainly in the platform namespaces. You must change namespace references if you manually migrate your code or with the help of Visual Studio’s code editing features. Table 2 shows the comparison of namespace names.

Table 2: Namespace comparison between Xamarin.Forms and .NET MAUI

In Xamarin.Forms, you had to install the Essentials library as a NuGet package if you wanted to take advantage of the cross-platform API that simplifies how you access platform-specific features. In .NET MAUI, it’s no longer required to install a separate library because Essentials is already part of the .NET codebase, and the new namespace structure already references it.

When you plan for migration, migrating C# code from your Xamarin.Forms solutions shouldn’t be an issue. Some changes can be there, but they’ll never completely halt your work.

Migrating XAML code

In general, the migration of your XAML code will also be relatively easy. Your existing code will work with limited modifications, except for the following:

• The ways Xamarin.Forms and .NET MAUI render layout views are totally different and require some code changes. This will be better explained in Chapter 5. Layouts in .NET MAUI have no default spacing values. Also, you’ll want to migrate existing StackLayout references to the new HorizontalStackLayout and VerticalStackLayout views, which can have an impact if you’ve used a lot of them.
• Some colors have the same name but different tones.
• There are known issues in .NET MAUI, such as gesture interaction on specific views, which might require workarounds.

There is also an important change related to XAML namespaces. In Xamarin.Forms, the root XAML namespace is the following:

xmlns="http://xamarin.com/schemas/2014/forms"

In .NET MAUI, the root namespace is the following:

xmlns="http://schemas.microsoft.com/dotnet/2021/maui"

Hence, any reference should be changed when porting your code. The key point of migrating XAML code will likely be time rather than complexity. Especially at the beginning, you might need to experiment with different ways to rework how you implement layouts. As for C# code, you’ll rarely find issues that completely halt your progress.

Libraries and third-party components

If your Xamarin.Forms projects use third-party libraries or components, you’ll need to consider when you plan to migrate. This is, without a doubt, the most critical part of your analysis. The key points you should consider are the following:

• Check if the .NET MAUI counterpart of a library is already available.
• If a library is readily available, check that it has the same features as the Xamarin.Forms version and understand any differences that could impact the upgraded project.
• If no counterpart is available, consider another third-party option. The impact here could be huge: licenses, different APIs, and a steep learning curve. There is no single answer, and this can be your decision alone.
• If a .NET MAUI counterpart is available but does not have feature parity at the time of migration, you’ll have limited alternatives. For example, you might need to communicate to your customers that you’re migrating to a new technology and that feature parity of your apps will be reached in some months. This can be business critical, so it’s something that you really need to plan for very carefully.

Chapters 6 and 10 provide detailed explanations and examples related to all these points.

Migrating icons and images

Migrating icons and images is another key point when planning a migration from Xamarin.Forms to .NET MAUI. As you know, .NET MAUI allows for a much simpler handling of images and icons, requiring only one .svg file rather than having several .png images in different resolutions for different operating systems. You have two main options:

Converting (or redesigning) images to the .svg format. In large companies, a professional designer usually converts these images using the appropriate tools, which can take quite a bit of time.

Reusing .png images. This isn’t the best option, as it’s not .NET MAUI-oriented. At the start of migration, it might be the fastest option. It might give you enough time to consider creating .svg images.

The first option is certainly recommended. After all, if you’re migrating, you probably want everything to be fresh in the new solution. But it requires time and the effort of a dedicated professional. The second choice is not the best, but it can give you the flexibility of shipping a first version while you rework images in the background. Again, there’s no single answer. You’ll need to find the right balance according to your resources.

Reusing fonts

If your existing Xamarin.Forms projects use custom fonts, they can be reused in .NET MAUI. The difference is in how fonts are stored in the solution folder and in how they’re registered. In Xamarin.Forms, you need to provide font files for each platform project and register them in XAML code. In .NET MAUI, you place font files into one folder and then register them in the C# code that’s executed at application startup. In .NET MAUI, handling fonts is simpler than in Xamarin.Forms, making this part of the migration very easy.

Migrating custom renderers

With custom renderers, Xamarin.Forms allows developers to customize the appearance and behavior of native controls by accessing platform APIs in C# code. .NET MAUI doesn’t have the concept of custom renderers, since it relies on handlers. Migrating custom renderers is probably the most complex part of the migration, at least from a technical perspective. You’ll need to consider the following:

• You might need to study to understand handlers in .NET MAUI.
• You should understand if .NET MAUI exposes APIs that can avoid the need for creating a handler. In fact, the new API surface allows for accessing native controls without the need for handlers in some cases.
• You should understand if the existing custom renderers can be converted to .NET MAUI handlers and, if not, search for an alternative, like a third-party library.

Note: Until .NET 7, developers were allowed to import custom renderer code into .NET MAUI projects to simplify the adoption of the new platform. However, in .NET 8, custom renderers are deprecated and can no longer be used.

Chapter 7 explains how to migrate a simple custom renderer from Xamarin.Forms to a .NET MAUI handler, but because this is really a crucial point, reading the migration guide from Microsoft is highly recommended.

Migrating broadcast messages

Broadcast messages allow for implementing the so-called publisher/subscriber pattern, and they’re generally used with the implementation of the MVVM pattern.

In Xamarin.Forms, broadcast messages are built upon the MessagingCenter class. With its methods, an object can send a message to notify subscribers of that message, which take actions accordingly. The MessagingCenter class was still available in .NET 6 and the very first release of .NET MAUI, but it was removed starting with .NET 7.

Now in .NET MAUI, you use a class called WeakReferenceMessenger, which is exposed by the Microsoft Community Toolkit MVVM library that ships as a NuGet package. In Chapter 8, you’ll see how to implement broadcast messages in .NET MAUI in practice. The point is that this migration can have an impact, especially if you have many messages. In fact, in Xamarin.Forms, a message is a string. In .NET MAUI, a message is an instance of a class that needs to be defined. There are ways to reduce the impact that will be covered in the appropriate chapter, but keep in mind that migrating broadcast messages can take a lot of time, even if not technically complex.

Migrating App Center analytics

Thousands of mobile apps used the Visual Studio App Center to collect analytics and diagnostics. If your apps also rely on the App Center usage metrics engine, the first consideration is that Microsoft will be retiring the App Center in 2026. The official announcement can be found on the App Center retirement page. You‘ll want to use one of the alternatives listed on the retirement page as you are migrating. If you need more time to evaluate the best alternative option and you want to keep the usage metrics on App Center as long as it’s available, there’s some good news. You can keep using the same app secrets in .NET MAUI and won’t lose the analytics history. Chapter 10 describes this in detail.

Addressing known issues

As you know, one of the goals of .NET MAUI is making the migration from Xamarin.Forms as simple as possible. The way it’s been designed makes it possible to reuse most of your code. Since .NET MAUI was built from the ground up, some known issues could affect your porting. Chapter 12 describes some of the issues you might encounter when moving XAML and C# code from Xamarin.Forms to MAUI. Some of these issues might be unexpected, but we’ll talk about how to implement workarounds. It’s a good idea to bookmark the Issues page on GitHub, which is updated with known issues, comments, proposals, and solutions.

About UI tests

If your Xamarin.Forms projects include automated UI tests that you’d like to migrate to .NET MAUI, the process is a bit complex. No equivalent platform to the Xamarin.UITest framework is available for .NET MAUI, and Microsoft suggests using Appium and Nunit. The implications for your project are significant, since you’ll need to redesign and recreate your UI tests. If UI tests are a plus but not mandatory, you can take more time to investigate. On the other hand, this could be a huge problem if your company requires automated UI tests for quality assurance. Due to the complexity of this topic, UI test migration cannot be covered in this ebook. Microsoft has created a page in the documentation that provides an introduction to testing .NET MAUI apps with Appium and Nunit.

Getting started with migration

As a developer, you have two options to start the migration process:

• Use the .NET Upgrade Assistant for .NET MAUI command-line tool from Microsoft.
• Create a blank .NET MAUI solution and manually port your code step-by-step.

The next paragraphs explain the two options in more detail, and you’ll understand why the second option is likely the best approach.

Introducing the .NET Upgrade Assistant for .NET MAUI

The .NET Upgrade Assistant for .NET MAUI is a command-line tool that aims to simplify the creation of a .NET MAUI solution based on a Xamarin.Forms one. This tool can be installed from the command line as follows:

> dotnet tool install -g upgrade-assistant

Note: The next steps describe how to run the Upgrade Assistant tool, but for now, don’t run it against the sample project we created before you complete this whole section.

When you’re ready, go to the folder of the project you intend to migrate and type the following command:

> upgrade-assistant upgrade

At startup, the Upgrade Assistant will ask you to specify if you want to perform an in-place update without making a copy of the original project or if you want a side-by-side. This just means making a copy of the original project and working on the copy. The second option is preferable to avoid potential problems. The tool performs the following tasks over an existing Xamarin.Forms project:

• Creating a .NET MAUI solution.
• Converting platform projects, such as Xamarin.iOS and Xamarin.Android, into convenient code files and folders that fit into the .NET MAUI SDK style.
• Updating the target framework in the project file.
• Adjusting the project properties.
• Replacing the Xamarin.Forms and Xamarin.Essentials NuGet packages with the .NET MAUI library.
• If installed, replacing the Xamarin.CommunityToolkit NuGet package with the .NET MAUI Community Toolkit.
• Replacing namespace references with the appropriate ones (see Table 2).

While you commonly find information about what this tool does, the following is a list of things that this tool doesn’t do (at the time of this writing):

• Migrate XAML namespace references.
• Check for .NET MAUI counterparts of third-party libraries and components.
• Migrate 100% of your code appropriately.
• Add the new solution to source control.
• Convert custom renderers to handlers.
• Replace broadcast messages.
• Convert images.

As you can see, the Upgrade Assistant simplifies the solution setup, but it’s far from being a complete migration tool.

Creating a blank .NET MAUI solution

Creating a blank .NET MAUI solution is a good option because the project is set up from zero, all fresh with no pending edits or references. You’ll need to manually update libraries and migrate your code and all the other resources, but you’ll be 100% sure there are no code and reference conflicts. You’ll be sure all the namespaces are referenced properly, including XAML namespaces. You’ll need to migrate many code parts manually (like custom renderers and broadcast messages), but you’d also need to do this after running the Upgrade Assistant.

In this book, creating a blank .NET MAUI solution is the approach of choice, but you’re free to experiment with both options. Whatever you choose for your solution setup, you’ll need to translate all the topics described in this chapter into development tasks. This is covered in the next few chapters.

Chapter summary

This chapter provided guidance on the most critical and relevant aspects that you need to consider when approaching the migration of Xamarin.Forms projects to .NET MAUI. You’ve seen the simpler parts, such as migrating C# and XAML code, reusing fonts, and migrating analytics. You’ve seen the more complex parts, such as upgrading libraries, custom renderers, and broadcast messages. Finally, you learned that a completely new approach should be used for automated UI tests. In the next chapter, you’ll start migrating the Xamarin.Forms project created in Chapter 2, with a practical understanding of what this chapter just summarized.