Xamarin Android Migration

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

<!-- ❌ 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

// ❌ 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

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

Xamarin.Android Migration API Reference

SDK-Style Project File Template

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0-android</TargetFramework>
    <SupportedOSPlatformVersion>21</SupportedOSPlatformVersion>
    <OutputType>Exe</OutputType>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <ApplicationId>com.companyname.myapp</ApplicationId>
    <ApplicationVersion>1</ApplicationVersion>
    <ApplicationDisplayVersion>1.0</ApplicationDisplayVersion>
  </PropertyGroup>
</Project>

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

Replace net8.0-android with net9.0-android or net10.0-android as needed.

---

MSBuild Property Changes

ABI → RuntimeIdentifier Conversion

<!-- Xamarin.Android -->
<AndroidSupportedAbis>armeabi-v7a;arm64-v8a;x86;x86_64</AndroidSupportedAbis>

<!-- .NET for Android -->
<RuntimeIdentifiers>android-arm;android-arm64;android-x86;android-x64</RuntimeIdentifiers>

---

AndroidManifest.xml Changes

Remove <uses-sdk> from AndroidManifest.xml. Use MSBuild properties instead:

<!-- BEFORE (Xamarin.Android AndroidManifest.xml) -->
<uses-sdk android:minSdkVersion="21" android:targetSdkVersion="33" />

<!-- AFTER (.NET for Android csproj) -->
<PropertyGroup>
    <TargetFramework>net8.0-android</TargetFramework>  <!-- targetSdkVersion -->
    <SupportedOSPlatformVersion>21</SupportedOSPlatformVersion>  <!-- minSdkVersion -->
</PropertyGroup>

---

NuGet Dependency Compatibility

Android is unique: NuGet packages targeting monoandroid still work on .NET for Android.

.NET Standard libraries without incompatible dependencies are also compatible.

---

Binding Library Migration

For binding libraries, create a new project and copy bindings:

dotnet new android-bindinglib --output MyJavaBinding

Key changes:

• Use SDK-style project format
• @(InputJar), @(EmbeddedJar), or @(LibraryProjectZip) auto-enable

$(AllowUnsafeBlocks)

• AndroidClassParser defaults to class-parse (no jar2xml)

---

Xamarin.Essentials Namespace Mapping

Essentials Initialization

using Microsoft.Maui.ApplicationModel;

[Activity(Label = "@string/app_name", MainLauncher = true)]
public class MainActivity : Activity
{
    protected override void OnCreate(Bundle? savedInstanceState)
    {
        base.OnCreate(savedInstanceState);
        Platform.Init(this, savedInstanceState);
    }
}

Override OnRequestPermissionsResult in every Activity:

public override void OnRequestPermissionsResult(int requestCode, string[] permissions, Permission[] grantResults)
{
    Platform.OnRequestPermissionsResult(requestCode, permissions, grantResults);
    base.OnRequestPermissionsResult(requestCode, permissions, grantResults);
}

---

Encoding Changes

Replace MAndroidI18n with the System.Text.Encoding.CodePages NuGet package:

// At app startup
System.Text.Encoding.RegisterProvider(System.Text.CodePagesEncodingProvider.Instance);

---

AOT Compilation

Release builds default to profiled AOT:

<PropertyGroup Condition="'$(Configuration)' == 'Release'">
    <RunAOTCompilation>true</RunAOTCompilation>
    <AndroidEnableProfiledAot>true</AndroidEnableProfiledAot>
</PropertyGroup>

To disable AOT, explicitly set both to false.

---

.NET CLI Commands

Note: dotnet build produces a runnable .apk/.aab directly (unlike desktop

.NET where publish is typically needed). Inside IDEs, the Install target handles

deployment instead.