Xamarin.iOS binding project migration

Article
05/07/2024

To migrate a Xamarin.iOS binding library to a .NET for iOS binding library:

In Visual Studio, create a new iOS Binding Library project with the same name as your Xamarin.iOS binding project:

Screenshot of creating an iOS Binding Library project in Visual Studio.

Open the project file to confirm that you have a .NET SDK-style project:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0-ios</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>true</ImplicitUsings>
    <IsBindingProject>true</IsBindingProject>
  </PropertyGroup>

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

Note

The project file for an iOS binding library is similar to the project file for an iOS class library.

Add your native library, or native framework, to the project as a native reference. Then update the binding project file with the <NativeReference> item from your Xamarin.iOS binding project:
```
<ItemGroup>
    <NativeReference Include="libXMBindingLibraryUniversal.a">
        <Kind>Static</Kind>
        <ForceLoad>True</ForceLoad>
    </NativeReference>
</ItemGroup>
```
Copy the API definition from your Xamarin.iOS binding project to your .NET for iOS binding project.
Copy any additional required code from your Xamarin.iOS binding project to your .NET for iOS binding project.
In your .NET for iOS binding project, replace any unsupported APIs with their .NET for iOS equivalents. For more information, see Unsupported APIs.

Unsupported APIs

The following Xamarin.iOS APIs have changed.

System.nint and System.nunit

The System.nint and System.nuint types aren't available in .NET for iOS. Instead, they're replaced with the nint and nuint types, which map to System.IntPtr and System.UIntPtr respectively. Code that uses the System.nint and System.nuint types won't compile and should be replaced with the nint and nuint types. In addition, code that overloads on System.IntPtr and nint, and System.UIntPtr and nuint won't compile. In this scenario, rename or remove one of the overloads.

System.nfloat

The System.nfloat type isn't available in .NET for iOS. Instead, it's replaced with the System.Runtime.InteropServices.NFloat type. Modify any code that refers to System.nfloat to use nfloat or the fully qualified type name.

NSObject.Handle type change

In .NET for iOS, the NSObject.Handle and INativeObject.Handle properties have changed type from System.IntPtr to a ObjCRuntime.NativeHandle struct. This means that many parameters and return values will need to change type. For example:

All objects that inherit from Foundation.NSObject that have ClassHandle or Handle properties of type IntPtr should change their property type to ObjCRuntime.NativeHandle.
All objects that inherit from Foundation.NSObject or ObjCRuntime.DisposableObject that have constructors that previously took a System.IntPtr, or a System.IntPtr and a bool, should change the IntPtr references to ObjcRuntime.NativeHandle.

There are implicit conversions between System.IntPtr and ObjCRuntime.NativeHandler, so after making this type change most code should compile without further changes.

Model.AutoGeneratedName

The Model.AutoGeneratedName property isn't available in .NET for iOS. In Xamarin.iOS, this property specified whether the Objective-C type name for the model should be automatically generated. In .NET for iOS, autogenerating the Objective-C type name from the model is the default and only behavior that's available.

Share via