xamarin-ios-migration（xamarin iOS 迁移）

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