xamarin-android-migration: Скилл миграции в .NET для Android

--- name: xamarin-android-migration description: > **WORKFLOW SKILL** - Guide for migrating Xamarin.Android native apps to .NET for Android. Covers SDK-style project conversion, target framework monikers, MSBuild property changes, AndroidManifest.xml updates, NuGet dependency compatibility, Android binding library migration, Xamarin.Essentials in native apps, .NET CLI support, and platform-specific gotchas. USE FOR: "migrate Xamarin.Android", "upgrade Xamarin.Android to .NET", "Xamarin.Android to .NET for Android", "Android project migration", "Android binding library migration", "convert Android project to SDK-style", "AndroidSupportedAbis to RuntimeIdentifiers". DO NOT USE FOR: migrating Xamarin.Forms apps (use xamarin-forms-migration), migrating Xamarin.iOS apps (use xamarin-ios-migration), creating new MAUI apps from scratch (use feature-specific MAUI skills). --- # Xamarin.Android → .NET for Android Migration For SDK-style project templates, MSBuild property tables, ABI conversion, namespace mappings, and CLI commands, see `references/android-migration-api.md`. > ⚠️ **Field-tested advice:** Android migration is significantly harder than iOS. > Expect more UI bugs, OEM-specific rendering differences, and issues not > reproducible on emulators. **Test on physical devices.** ## Migration Workflow 1. Create new .NET for Android project (`dotnet new android`) 2. Copy code and resources into the new project 3. Update MSBuild properties (see `references/android-migration-api.md`) 4. Update AndroidManifest.xml — remove `<uses-sdk>`, use csproj properties 5. Delete `Resource.designer.cs` (regenerated automatically) 6. Update NuGet dependencies 7. Migrate binding libraries (if applicable) 8. Replace Xamarin.Essentials with `<UseMauiEssentials>true</UseMauiEssentials>` 9. Handle encoding changes 10. Delete `bin/`/`obj/`, build, test on physical devices > **Strategy:** Create a new project and copy code into it — don't edit the existing project file in place. ## Critical Gotchas ### ⚠️ Remove `<uses-sdk>` from AndroidManifest.xml ```xml <!-- ❌ Xamarin-style — causes build warnings/errors --> <uses-sdk android:minSdkVersion="21" android:targetSdkVersion="33" /> <!-- ✅ Use MSBuild properties instead --> <TargetFramework>net8.0-android</TargetFramework> <SupportedOSPlatformVersion>21</SupportedOSPlatformVersion> ``` ### ⚠️ Delete `Resource.designer.cs` This file is auto-generated. Leftover copies from Xamarin cause duplicate symbol errors. **Delete it** — it will be regenerated. ### ⚠️ No `.dll.config` or `.exe.config` Support `.dll.config` and `<dllmap>` are not supported in .NET Core. If your app uses `System.Configuration.ConfigurationManager`, migrate to `appsettings.json` or platform preferences. ### ⚠️ Essentials: Override Permissions in Every Activity ```csharp // ❌ Forgetting this → permissions silently fail // ✅ Required in EVERY Activity that uses Essentials public override void OnRequestPermissionsResult( int requestCode, string[] permissions, Permission[] grantResults) { Platform.OnRequestPermissionsResult(requestCode, permissions, grantResults); base.OnRequestPermissionsResult(requestCode, permissions, grantResults); } ``` ### ⚠️ AndroidManifest.xml Location Changed `AndroidManifest.xml` is now in the **project root** (not `Properties/`). The SDK-style project finds it there by default. ## Platform-Specific Pitfalls | Pitfall | Impact | Mitigation | |---------|--------|------------| | OEM rendering differences | UI bugs not visible on emulators | Test on physical devices from multiple vendors | | Shadow rendering varies by OEM/API level | Inconsistent shadow appearance | Implement shadows in platform-specific handler code | | Android Wear references | Not supported in .NET for Android | Remove Wear project references | | `MAndroidI18n` removed | Encoding errors at runtime | Replace with `System.Text.Encoding.CodePages` NuGet | | `AotAssemblies` deprecated | Build warnings | Use `RunAOTCompilation` instead | | `jar2xml` not supported | Binding library build failures | Use default `class-parse` parser | | `DebugType=full` not supported | Build errors | Use default `portable` | ## NuGet Compatibility Note Android is unique: packages targeting `monoandroid` **still work** on .NET for Android. No recompilation needed for most Android-specific packages. This is NOT true for iOS/Mac. If no compatible version exists: 1. Recompile with .NET TFMs (if you own it) 2. Look for a preview .NET version 3. Replace with a .NET-compatible alternative ## 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 Android project (`dotnet new android`) 2. ☐ Set `TargetFramework` to `net8.0-android` (or later) 3. ☐ Set `SupportedOSPlatformVersion` for minimum SDK 4. ☐ Converted `AndroidSupportedAbis` → `RuntimeIdentifiers` 5. ☐ Removed `<uses-sdk>` from AndroidManifest.xml 6. ☐ Copied source, resources, and project properties 7. ☐ Deleted `Resource.designer.cs`, `bin/`, `obj/` 8. ☐ Updated NuGet dependencies 9. ☐ Added `UseMauiEssentials` + `Platform.Init()` if using Essentials 10. ☐ Overridden `OnRequestPermissionsResult` in every Activity 11. ☐ Replaced `MAndroidI18n` with `System.Text.Encoding.CodePages` 12. ☐ Verified AOT settings (`RunAOTCompilation`, not `AotAssemblies`) 13. ☐ Tested on physical Android device(s) from multiple vendors