Migration of Xamarin Libraries and Apps to .NET 6.0/7.0

30 Apr 2023 | net6.0 net7.0 xamarin

We are well into .NET6 and .NET7 release lifecycle and .NET8 coming up soon. Additionally end of life of Xamarin is coming increasingly closer, so I bet a lot of people are looking towards migrating to the newer bits.

I have already migrated every App I work on to NET7.0 and have done multiple releases to stores of these Apps. So wanted to share some insights with everyone.

1. Breaking changes

You maybe we aware that net{6|7|8}.0-ios targets are incompatible with Xamarin.iOS targets. The breaking changes primarily are how NFloat and related types are now handled. Instead of living directly in .NET 6.0, these types are now added implicitly using the NuGet package System.Runtime.InteropServices.NFloat.Internal. If you are already using .NET 6.0 you might have noticed this package gets pulled in, even though you have no other Package References. This makes Xamarin.iOS assemblies not forward compatible with the newer target frameworks. Hence, library authors need to migrate their projects to make them compatible.

I have done a couple of migrations, a huge one in MvvmCross which has a lot of target frameworks it targets. Migrated NukeProxy which is a iOS Binding Library, which had to be converted to using XCFramework instead of a Fat library. I have migrated a bunch of internal libraries and 6 Apps at work. So now I have a little bit of experience behind the belt.

2. Prerequisites

Make sure your .NET version is up to date. As of November .NET 7.0 is out and newer versions of Visual Studio for Mac will pull this the things described here should also be working if even if you are on .NET8.0 already, but also if you are for some reason on .NET6.0.

The bits for Android, iOS, macOS, mac catalyst etc. are no longer distributed with Visual Studio. Instead you will need to use a new feature in .NET to install a “workload” for each of these. This is super easy and much nicer in my opinion, instead of having to open a UI tool you can easily update and install these tools in the command-line. For instance if you want Android and iOS you do:

dotnet workload install android ios

You will need to install the appropriate workload for each Target Framework you intend to support in your library. If you are going to use .NET MAUI, then you might also want to install the maui maui-android maui-ios workloads.

3. Migrating a project to new SDK style project

The new SDK style project has been available to use for a very long time. The biggest advantage of these new project styles, is that you will not have to specify every single file in your project file that you want to compile. Instead the new style just picks up any know file types and makes some sane assumptions about the build actions for the files and adds them automatically. This makes working with csproj files much easier, as they are not polluted with loads of <Compile Include="folder/myfile.cs" /> definitions all over the place. The only things you would really have in these new csproj files is defining Target Framework, Package References and Project References. If you have other stuff, you may be doing something wrong.

If you compare the Playground.iOS csproj file in MvvmCross, it went from over 200 lines of code to 29, since the new SDK style projects are so more succinct.

The easiest way to migrate to the new project style and new TFM, is simply creating a new project and dragging over all your files, then adding all the project references and package references.

If you need inspiration of how a csproj file looks you can have some inspiration from some of the MvvmCross project files.

Android Library: MvvmCross RecyclerView csproj

Multi-target Library: MvvmCross Messenger Plugin csproj

4. Do I still need MSBuild.SDK.Extras for multi-targeting?

In MvvmCross I historically used the excellent MSBuild.SDK.Extras project to help with multi-targeting scenarios. However, after migrating projects to net6.0 I started having weird build issues. Migrating away from MSBuild.SDK.Extras resolved my issues. Your milage may vary, but it has helped me with a bunch of issues not to use it anymore.

If you are reading this and don’t know what it is, then you are not missing out on anything. It was just necessary with the older target frameworks to have a bunch of extra setup, which excellent community members such as Claire Novotny helped making for library authors to have a much nicer experience. However, it appears this is not necessary to use anymore.

5. Using Xamarin.Essentials?

If you are using Xamarin.Essentials, you may have heard that this is now moved over to MAUI.Essentials. However, not everyone are making Apps using MAUI, so you don’t really want to pull in everything from MAUI just to have access to the MAUI.Essentials API. MAUI.Essentials is not a NuGet package you pull in though. As of writing this post you can add MAUI.Essentials, by adding the following to your csproj file in a <PropertyGroup>:

<UseMauiEssentials>true</UseMauiEssentials>

Remember to initialize MAUI essentials on startup in your Activity or Application or View controller:

Microsoft.Maui.ApplicationModel.Platform.Init(this);

Read more about the migration in the Microsoft Docs

6. Change IntPtr to NativeHandle on iOS

Often when you are creating CollectionView or TableView cells among other views on iOS, you need to add constructors which historically used IntPtr in the constructor. This has changed now and you need to switch all these over to use NativeHandle or you will encounter issues at runtime, where it will complain about missing constructors.

7. My App crashes with PlatformNotSupported exception in System.Linq.Expression errors at runtime

There are places in net6.0 and net7.0 where some paths use code that requires JIT compilation. Such as when using parts of System.Linq.Expression which internally uses System.Reflection.Emit. This is supposed to be fixed in net8.0.

Read more here:

If you encounter such issues you will have to add the following to your iOS project:

<UseInterpreter>true</UseInterpreter>

You may also want to experiment with adding

<MtouchInterpreter>-all</MtouchInterpreter>

You can read more about this in Ryan Davis’s excellent blog post about improving build times

But UseInterpreter kicks in the Interpreter mode for your App and allows for some cool features, which are also described by Ryan Davis in his post about the mono interpreter. Among these emitting code, patching code at runtime and more, but more importantly fixes runtime crashes until libraries get patched.

8. I have a Binding Library what do I do with that?

Business as usual. However, I’ve found that switching over to output XCFramework libraries for the stuff you want to bind, is much easier to work with. Especially if you also want to support Mac Catalyst, then it is a must.

You still need to provide a ApiDefinition and Structs file. Specifically for these you need specific build actions in your csproj file:

<ItemGroup>
  <ObjcBindingApiDefinition Include="ApiDefinition.cs" />
  <ObjcBindingCoreSource Include="Structs.cs" />
</ItemGroup>

Then you can refer to your XCFrameworks like so:

<ItemGroup>
  <NativeReference Include="..\..\Output\NukeProxy.xcframework">
    <Kind>Framework</Kind>
    <SmartLink>False</SmartLink>
  </NativeReference>
  <NativeReference Include="..\..\Carthage\Build\Nuke.xcframework">
    <Kind>Framework</Kind>
    <SmartLink>False</SmartLink>
  </NativeReference>
</ItemGroup>

If you are still on .net6.0, you may have issues with BitCode being pulled in for some reason. Refer to this comment on GitHub to see how you can add extra stuff in your csproj to get rid of it. Supposedly it is fixed in .net7.0.

I think this is more or less what you need to know. Sure, this is not a complete migration guide, so you will have to try this yourself, but hopefully there are some things here that might you. If you have any questions, please do reach out on Discord, Mastodon, Twitter or in the comments below.

Related Posts