Xamarin Ios Migration

Xamarin.iOS / Xamarin.Mac / Xamarin.tvOS → .NET Migration

For SDK-style project templates, MSBuild property tables, RuntimeIdentifier conversion tables, and namespace mappings, see references/ios-migration-api.md.

Migration Workflow

1. Create new .NET for iOS/macOS/tvOS project (same name, copy code into it) 2. Update MSBuild properties (see references/ios-migration-api.md) 3. Move MinimumOSVersion from Info.plist → SupportedOSPlatformVersion in csproj 4. Copy code, resources, storyboards, entitlements 5. Update NuGet dependencies 6. Migrate binding libraries (if applicable) 7. Replace Xamarin.Essentials with <UseMauiEssentials>true</UseMauiEssentials> 8. Remove .dll.config files (not supported in .NET) 9. Delete bin//obj/, build, verify code signing, test on device

Strategy: Create a new project and copy code into it — don't edit the existing project file.

Critical Gotchas

⚠️ No Backward Compatibility for iOS/Mac NuGet Packages

Unlike Android, there is no backward compatibility with old Xamarin iOS/Mac TFMs. Packages targeting monotouch, xamarinios, xamarinios10, monomac, or xamarinmac will not work — they must be recompiled for net8.0-ios etc.

⚠️ CodeSigningKey → CodesignKey Rename

<!-- ❌ Old property name — silently ignored -->
<CodeSigningKey>Apple Distribution: My Company</CodeSigningKey>

<!-- ✅ Renamed property -->
<CodesignKey>Apple Distribution: My Company</CodesignKey>

Also rename MtouchEnableSGenConc → EnableSGenConc.

⚠️ No .dll.config or .exe.config Support

.dll.config and <dllmap> are not supported in .NET Core. Migrate configuration to appsettings.json, embedded resources, or platform preferences.

⚠️ watchOS Is Not Supported

Xamarin.watchOS has no .NET equivalent. Bundle Swift extensions with .NET for iOS apps instead.

⚠️ OpenGL (iOS) Is Not Supported

OpenTK is unavailable in .NET for iOS. Migrate to Metal or SceneKit.

⚠️ Linker Behavior Is Stricter

Update LinkDescription XML files if custom linker configuration was used. The linker in .NET is stricter and may trim symbols that the Xamarin linker preserved.

Platform-Specific Pitfalls

Binding Library Migration Tips

• Use SDK-style project format with net8.0-ios TFM
• The binding generator and API definitions work the same way
• Verify native frameworks are updated for the target iOS version
• Test thoroughly — binding edge cases are common in .NET migrations

NuGet Compatibility Decision

Build Troubleshooting

API Currency Warning

If your migrated app will also adopt .NET MAUI controls (e.g., via UseMaui), check the maui-current-apis skill for deprecated MAUI APIs to avoid (ListView, Frame, Device.*, etc.).

Quick Checklist

1. ☐ Created new .NET for iOS/macOS/tvOS project 2. ☐ Set TargetFramework to net8.0-ios (or -macos/-tvos) 3. ☐ Moved MinimumOSVersion → SupportedOSPlatformVersion in csproj 4. ☐ Converted MtouchArch → RuntimeIdentifier(s) 5. ☐ Converted HttpClientHandler → UseNativeHttpHandler 6. ☐ Renamed CodeSigningKey → CodesignKey 7. ☐ Renamed MtouchEnableSGenConc → EnableSGenConc 8. ☐ Copied source, resources, storyboards, entitlements 9. ☐ Updated NuGet dependencies (no backward compat with Xamarin TFMs!) 10. ☐ Added UseMauiEssentials + Platform.Init() if using Essentials 11. ☐ Removed .dll.config files 12. ☐ Deleted bin/ and obj/ folders 13. ☐ Verified code signing and provisioning 14. ☐ Tested on physical device

Xamarin.iOS / Xamarin.Mac / Xamarin.tvOS Migration API Reference

SDK-Style Project File Templates

.NET for iOS

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

.NET for macOS (Mac Catalyst)

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0-macos</TargetFramework>
    <OutputType>Exe</OutputType>
    <Nullable>enable</Nullable>
    <ImplicitUsings>true</ImplicitUsings>
    <SupportedOSPlatformVersion>10.15</SupportedOSPlatformVersion>
  </PropertyGroup>
</Project>

.NET for tvOS

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0-tvos</TargetFramework>
    <OutputType>Exe</OutputType>
    <Nullable>enable</Nullable>
    <ImplicitUsings>true</ImplicitUsings>
    <SupportedOSPlatformVersion>13.0</SupportedOSPlatformVersion>
  </PropertyGroup>
</Project>

For library projects, omit <OutputType> or set to Library.

Replace net8.0 with net9.0 or net10.0 as appropriate. Valid TFMs:

net8.0-ios, net8.0-macos, net8.0-tvos.

---

MSBuild Property Changes

---

MtouchArch → RuntimeIdentifier Conversion

iOS

Use RuntimeIdentifiers (plural) when targeting multiple architectures.

macOS

tvOS

---

HttpClientHandler Conversion

---

Info.plist Changes

Move MinimumOSVersion / LSMinimumSystemVersion from Info.plist to the project file:

<!-- BEFORE (Info.plist) -->
<key>MinimumOSVersion</key>
<string>13.0</string>

<!-- AFTER (csproj) -->
<PropertyGroup>
    <SupportedOSPlatformVersion>13.0</SupportedOSPlatformVersion>
</PropertyGroup>

Other Info.plist entries (display name, bundle identifier, permissions, etc.) remain in Info.plist.

---

NuGet Dependency Compatibility

Unlike Android, there is no backward compatibility with old Xamarin iOS/Mac

TFMs. Packages must be recompiled for net8.0-ios etc.

.NET Standard libraries without incompatible dependencies remain compatible.

---

Xamarin.Essentials Namespace Mapping

Essentials Initialization (iOS)

using Microsoft.Maui.ApplicationModel;

[Register("AppDelegate")]
public class AppDelegate : UIApplicationDelegate
{
    public override UIWindow? Window { get; set; }

    public override bool FinishedLaunching(UIApplication application, NSDictionary launchOptions)
    {
        Window = new UIWindow(UIScreen.MainScreen.Bounds);
        var vc = new UIViewController();
        Window.RootViewController = vc;

        Platform.Init(() => vc);

        Window.MakeKeyAndVisible();
        return true;
    }
}

App Actions Override

public override void PerformActionForShortcutItem(
    UIApplication application,
    UIApplicationShortcutItem shortcutItem,
    UIOperationHandler completionHandler)
{
    Platform.PerformActionForShortcutItem(application, shortcutItem, completionHandler);
}

---

Supported / Unsupported Project Types