Tips & Tricks on Upgrading Xamarin.iOS & Xamarin.Android to .NET for iOS & Android

James Montemagno

There has never been a better time to update & migrate your Xamarin.iOS and Xamarin.Android apps to the latest version of .NET. The update process for most apps should be quick and when you are finished you will be able to take advantage of the latest features of .NET 7 including C# 11 and the new project system. In addition, iOS & Android apps built against .NET 6 and .NET 7 have large performance improvements and developer productivity features as they take advantage of build system enhancements. The team has just released upgrade documentation for apps, so go head over there for a full walkthrough. In this blog, I will walk you through some tips & tricks to get started with your update.

If you are looking to update and migrate your Xamarin.Forms based applications then skip this blog and follow the self-guided documentation that outlines out to manually update or take advantage of the .NET Upgrade Assistant.

Work in a Branch

Before you start your update process it is a good idea to work in a branch if you are using git! This will ensure you can easily roll back and iterate over time if you have a complex project.

Analyze NuGet Packages

The first step in the upgrade process is to check your NuGet packages in your projects. You will need to ensure that they have been updated and re-compiled against .NET 6 or .NET 7 for iOS and Android.

Consider my Xamarin.Android app that I am looking to update, it has references to AndroidX, Material Design, Xamarin.Essentials, and a few of my own libraries:

<ItemGroup>
  <PackageReference Include="Xamarin.AndroidX.AppCompat" Version="1.6.0.1" />
  <PackageReference Include="Xamarin.Google.Android.Material" Version="1.7.0.2" />
  <PackageReference Include="Xamarin.Essentials" Version="1.7.4" />
  <PackageReference Include="Plugin.InAppBilling" Version="6.7.0" />
  <PackageReference Include="MonkeyCache.FileStore" Version="1.5.2" />
</ItemGroup>

You can browse NuGet.org to find your packages and see what frameworks they support. In the case of Xamarin.AndroidX.AppCompat we can see that it supports both monoandroid12.0 (Xamarin.Android) and net6.0-android31.0 (compiled against .NET 6).

Note: For Xamarin.Android projects it is recommended to migrate from Android Support Libraries as they are not supported in .NET 6+ Android projects. You can do this by migrating to AndroidX by following the migration guide documentation.

In this case, this library is fully compatible with the latest versions of .NET for Android. If the version of a NuGet package isn’t compatible with the latest framework you may need to update to a new version or find a replacement. Monkey Cache for example only supports only supported Xamarin apps in version 1.5.2, but version 2.0.1 was recompiled against .NET 6 and will be compatible.

Update Project Files

Android and iOS are now integrated directly into .NET. This means that they have have new Target Framework Monikers of net7.0-android and net7.0-ios. They also use the new .NET SDK project style. This means the configuration inside of your projects .csproj has been greatly simplified. The next step in the process is to unload your Android and iOS Projects. The easiest thing to do is delete all of the content inside of it and add the new base SDK style project settings:

Android:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net7.0-android</TargetFramework>
    <OutputType>Exe</OutputType>
  </PropertyGroup>
</Project>

iOS:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net7.0-ios</TargetFramework>
    <OutputType>Exe</OutputType>
  </PropertyGroup>
</Project>

Notice here that there is no longer the need to manually reference individual files, resources, or compilation settings for Debug or Release. The project system is automatically configured to use defaults. You can always update these settings with the new project settings dialog.

Before reloading the project it is a good idea to manually delete the obj and bin folders for the project.

Android: Delete Resource.designer.cs

In Xamarin.Android projects a Resource.designer.cs file was generated when resources changed and added into the Resources folder. This file is no longer needed and can be deleted as they are auto generated as a code generation step.

Delete AssemblyInfo.cs

Similar to the Resource.designer.cs the AssemblyInfo.cs file is automatically generated based on project settings. These files can be deleted from the Properties folder for both iOS and Android.

Note: You may have had permission settings in your Android project’s AssemblyInfo.cs file. You can leave these and remove everything else, or move them to another file.

Xamarin.Essentials to .NET MAUI Essentials

Xamarin.Essentials was a fundamental library for nearly every Xamarin application. If you were using this NuGet package, you will want to remove it as Xamarin.Essentials is now part of .NET MAUI. The team has worked hard to ensure that while it comes pre-configured with every .NET MAUI application, it is still available to all iOS and Android apps built with .NET.

<PropertyGroup>
  <UseMauiEssentials>true</UseMauiEssentials>
</PropertyGroup>

Once you update to .NET MAUI Essentials, you will need to update any using Xamarin.Essentials; using statements to the new .NET MAUI Essentials namespaces, which you can find in the documentation.

Add & Update NuGet Packages

Going back to the NuGet packages that we previously analyzed, now we can add them back into our project. For our Android app we will move over and update the packages to the latest versions that are compatible, and remove the reference to Xamarin.Essentials:

<ItemGroup>
    <PackageReference Include="Xamarin.AndroidX.AppCompat" Version="1.6.0.1" />
    <PackageReference Include="Xamarin.Google.Android.Material" Version="1.7.0.2" />
    <PackageReference Include="Plugin.InAppBilling" Version="6.7.0" />
    <PackageReference Include="MonkeyCache.FileStore" Version="2.0.1" />
</ItemGroup>

Project References

If you reference any other .NET Standard libraries you can add them as a project reference. Any Xamarin.iOS or Xamarin.Android class library or binding library will also need to be updated to the new formats and then added back as references. You may want to consider updating your .NET Standard libraries to .NET 6 or .NET 7 to take advantage of the latest features of .NET and C#!

Use New Features

There are several enhancements to the project system that help you easily manage app settings. Now, you can manage your app versions, supported platform versions, app identifiers, and more!

Here are a few settings you can add to your ProjectGroup in your project:

<ApplicationTitle>MyApp</ApplicationTitle>
<SupportedOSPlatformVersion>21</SupportedOSPlatformVersion>
<ApplicationId>com.companyname.myapp</ApplicationId>
<ApplicationVersion>1</ApplicationVersion>
<ApplicationDisplayVersion>1.0</ApplicationDisplayVersion>

Once these are added you can remove them from your AndroidManifest.xml and Info.plist. Additionally, you can remove the <uses-sdk/> node from the AndroidManifest.xml as these are now outlined with these settings. There are many more options that you can find on documentation for Android and documentation for iOS

Additionally, you may want to consider turning on implicit usings and enabling nullable reference types

    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>

Summary

I hope that you found this upgrade guide nifty on getting your Xamarin.iOS and Xamarin.Android apps updated to the latest version of iOS & Android for .NET. I tried to cover a lot of tips & tricks, but be sure to read the full migration documentation for even more.

For more information on the performance improvements be sure to browse through the amazing blog posts from Jonathan Peppers on .NET 6 improvements and .NET 7 improvements.

I also have uploaded full before and after code samples available on my GitHub.

Don’t forget to read through the Xamarin support policy to make sure you plan your upgrade and migration.

James Montemagno Principal Manager, Tech PM, Developer Community

Follow