Index of every page on this site: llms.txt
All skills
davidortinau avatar

/xamarin-android-migration

@79bb4bf
Run it yourself

**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).

Use this Skill: https://skilld.dev/gh/davidortinau/maui-skills/xamarin-android-migration

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈213 tokens for metadata: the name and description. ≈1.2k when used: this file. ≈1.5k more on demand in 1 file.

Description uses 10.7% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈853 characters, or 10.7%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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

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

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts2mo4 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    The skill is a technical guide for migrating Xamarin.Android applications to .NET for Android. It provides standard configuration templates, code migration steps, and development CLI commands. No security issues were detected.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

  • Runlayer8mo

    1/1 file flagged

Signed by skilld at 79bb4bf. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Steadyupdated 8 months ago

README badge

README badge for davidortinau/maui-skills/xamarin-android-migration