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
- Create new .NET for iOS/macOS/tvOS project (same name, copy code into it)
- Update MSBuild properties (see
references/ios-migration-api.md)
- Move
MinimumOSVersion from Info.plist → SupportedOSPlatformVersion in csproj
- Copy code, resources, storyboards, entitlements
- Update NuGet dependencies
- Migrate binding libraries (if applicable)
- Replace Xamarin.Essentials with
<UseMauiEssentials>true</UseMauiEssentials>
- Remove
.dll.config files (not supported in .NET)
- 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
| Pitfall |
Impact |
Mitigation |
| iOS/Mac NuGet packages not backward-compatible |
Build failures for packages targeting xamarinios |
Recompile or find .NET-compatible alternatives |
CodeSigningKey silently ignored |
App fails to sign but no clear error |
Rename to CodesignKey |
MtouchArch not converted |
Wrong architecture targeted |
Convert to RuntimeIdentifier(s) — see reference tables |
MinimumOSVersion left in Info.plist |
Ignored — uses csproj value |
Move to SupportedOSPlatformVersion |
| Entitlements path wrong |
Build succeeds but runtime failures |
Verify CodesignEntitlements points to correct file |
.dll.config files present |
Silently ignored at runtime |
Remove and migrate to alternatives |
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
| Situation |
Action |
| You own the package |
Recompile with .NET TFMs |
| Package has preview .NET version |
Use preview |
| No compatible version |
Replace with .NET-compatible alternative |
| .NET Standard library (no platform deps) |
✅ Still works |
Build Troubleshooting
| Issue |
Fix |
| Namespace not found |
Most UIKit namespaces are unchanged — verify against .NET for iOS API surface |
| Linker errors |
Update LinkDescription XML files — linker is stricter in .NET |
| Code signing failure |
Verify CodesignKey, CodesignProvision, CodesignEntitlements |
| Entitlements mismatch |
Ensure entitlements file matches provisioning profile |
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
- ☐ Created new .NET for iOS/macOS/tvOS project
- ☐ Set
TargetFramework to net8.0-ios (or -macos/-tvos)
- ☐ Moved
MinimumOSVersion → SupportedOSPlatformVersion in csproj
- ☐ Converted
MtouchArch → RuntimeIdentifier(s)
- ☐ Converted
HttpClientHandler → UseNativeHttpHandler
- ☐ Renamed
CodeSigningKey → CodesignKey
- ☐ Renamed
MtouchEnableSGenConc → EnableSGenConc
- ☐ Copied source, resources, storyboards, entitlements
- ☐ Updated NuGet dependencies (no backward compat with Xamarin TFMs!)
- ☐ Added
UseMauiEssentials + Platform.Init() if using Essentials
- ☐ Removed
.dll.config files
- ☐ Deleted
bin/ and obj/ folders
- ☐ Verified code signing and provisioning
- ☐ Tested on physical device
1---2name: xamarin-ios-migration3description: >4 **WORKFLOW SKILL** - Guide for migrating Xamarin.iOS, Xamarin.Mac, and Xamarin.tvOS native apps to5 .NET for iOS, .NET for macOS, and .NET for tvOS. Covers SDK-style project6 conversion, target framework monikers, MSBuild property changes, Info.plist7 updates, iOS binding library migration, Xamarin.Essentials in native apps,8 NuGet dependency compatibility, and code signing changes.9 USE FOR: "migrate Xamarin.iOS", "upgrade Xamarin.iOS to .NET",10 "Xamarin.iOS to .NET for iOS", "iOS project migration", "Xamarin.Mac migration",11 "tvOS migration", "iOS binding library migration", "MtouchArch to RuntimeIdentifier",12 "Apple project migration".13 DO NOT USE FOR: migrating Xamarin.Forms apps (use xamarin-forms-migration),14 migrating Xamarin.Android apps (use xamarin-android-migration),15 creating new MAUI apps from scratch (use feature-specific MAUI skills).16---1718# Xamarin.iOS / Xamarin.Mac / Xamarin.tvOS → .NET Migration1920For SDK-style project templates, MSBuild property tables, RuntimeIdentifier conversion tables, and namespace mappings, see `references/ios-migration-api.md`.2122## Migration Workflow23241. Create new .NET for iOS/macOS/tvOS project (same name, copy code into it)252. Update MSBuild properties (see `references/ios-migration-api.md`)263. Move `MinimumOSVersion` from Info.plist → `SupportedOSPlatformVersion` in csproj274. Copy code, resources, storyboards, entitlements285. Update NuGet dependencies296. Migrate binding libraries (if applicable)307. Replace Xamarin.Essentials with `<UseMauiEssentials>true</UseMauiEssentials>`318. Remove `.dll.config` files (not supported in .NET)329. Delete `bin/`/`obj/`, build, verify code signing, test on device3334> **Strategy:** Create a new project and copy code into it — don't edit the existing project file.3536## Critical Gotchas3738### ⚠️ No Backward Compatibility for iOS/Mac NuGet Packages3940Unlike 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.4142### ⚠️ `CodeSigningKey` → `CodesignKey` Rename4344```xml45<!-- ❌ Old property name — silently ignored -->46<CodeSigningKey>Apple Distribution: My Company</CodeSigningKey>4748<!-- ✅ Renamed property -->49<CodesignKey>Apple Distribution: My Company</CodesignKey>50```5152Also rename `MtouchEnableSGenConc` → `EnableSGenConc`.5354### ⚠️ No `.dll.config` or `.exe.config` Support5556`.dll.config` and `<dllmap>` are not supported in .NET Core. Migrate configuration to `appsettings.json`, embedded resources, or platform preferences.5758### ⚠️ watchOS Is Not Supported5960Xamarin.watchOS has **no .NET equivalent**. Bundle Swift extensions with .NET for iOS apps instead.6162### ⚠️ OpenGL (iOS) Is Not Supported6364OpenTK is unavailable in .NET for iOS. Migrate to Metal or SceneKit.6566### ⚠️ Linker Behavior Is Stricter6768Update `LinkDescription` XML files if custom linker configuration was used. The linker in .NET is stricter and may trim symbols that the Xamarin linker preserved.6970## Platform-Specific Pitfalls7172| Pitfall | Impact | Mitigation |73|---------|--------|------------|74| iOS/Mac NuGet packages not backward-compatible | Build failures for packages targeting `xamarinios` | Recompile or find .NET-compatible alternatives |75| `CodeSigningKey` silently ignored | App fails to sign but no clear error | Rename to `CodesignKey` |76| `MtouchArch` not converted | Wrong architecture targeted | Convert to `RuntimeIdentifier(s)` — see reference tables |77| `MinimumOSVersion` left in Info.plist | Ignored — uses csproj value | Move to `SupportedOSPlatformVersion` |78| Entitlements path wrong | Build succeeds but runtime failures | Verify `CodesignEntitlements` points to correct file |79| `.dll.config` files present | Silently ignored at runtime | Remove and migrate to alternatives |8081## Binding Library Migration Tips8283- Use SDK-style project format with `net8.0-ios` TFM84- The binding generator and API definitions work the same way85- Verify native frameworks are updated for the target iOS version86- **Test thoroughly** — binding edge cases are common in .NET migrations8788## NuGet Compatibility Decision8990| Situation | Action |91|-----------|--------|92| You own the package | Recompile with .NET TFMs |93| Package has preview .NET version | Use preview |94| No compatible version | Replace with .NET-compatible alternative |95| .NET Standard library (no platform deps) | ✅ Still works |9697## Build Troubleshooting9899| Issue | Fix |100|-------|-----|101| Namespace not found | Most UIKit namespaces are unchanged — verify against .NET for iOS API surface |102| Linker errors | Update `LinkDescription` XML files — linker is stricter in .NET |103| Code signing failure | Verify `CodesignKey`, `CodesignProvision`, `CodesignEntitlements` |104| Entitlements mismatch | Ensure entitlements file matches provisioning profile |105106## API Currency Warning107108If 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.).109110## Quick Checklist1111121. ☐ Created new .NET for iOS/macOS/tvOS project1132. ☐ Set `TargetFramework` to `net8.0-ios` (or `-macos`/`-tvos`)1143. ☐ Moved `MinimumOSVersion` → `SupportedOSPlatformVersion` in csproj1154. ☐ Converted `MtouchArch` → `RuntimeIdentifier(s)`1165. ☐ Converted `HttpClientHandler` → `UseNativeHttpHandler`1176. ☐ Renamed `CodeSigningKey` → `CodesignKey`1187. ☐ Renamed `MtouchEnableSGenConc` → `EnableSGenConc`1198. ☐ Copied source, resources, storyboards, entitlements1209. ☐ Updated NuGet dependencies (no backward compat with Xamarin TFMs!)12110. ☐ Added `UseMauiEssentials` + `Platform.Init()` if using Essentials12211. ☐ Removed `.dll.config` files12312. ☐ Deleted `bin/` and `obj/` folders12413. ☐ Verified code signing and provisioning12514. ☐ Tested on physical device
davidortinau