Adopting Xamarin.Essentials: One Package to Replace Custom Platform Code

The problem: repeated platform implementations

Every Xamarin.Forms team eventually writes the same boilerplate: a DependencyService for secure storage, a custom renderer for geolocation, a platform-specific helper for connectivity checks. Each implementation lives in the iOS and Android projects, duplicates logic, and breaks when OS APIs change. Xamarin.Essentials was built to collapse that 80% of common device capabilities into a single NuGet package with a static C# API.

How the library works

Xamarin.Essentials uses a bait-and-switch model. The compile-time contract is a .NET Standard 2.0 assembly; at runtime each platform loads a tiny implementation that forwards calls to the native OS — CoreLocation on iOS, LocationManager on Android, Windows.Devices.Geolocation on UWP. You install one package, call Xamarin.Essentials.Platform.Init in MainActivity.OnCreate (Android) and FinishedLaunching (iOS), then use the static classes directly from shared code. No linker configuration is usually required because the assemblies are already trimmed for the used APIs.

Worked example: secure storage and last known location

Replace a custom ISecureStore interface and two platform implementations with three lines of shared code:

// Shared project (e.g., ViewModel or service)
using Xamarin.Essentials;

public async Task SaveTokenAsync(string token)
    => await SecureStorage.SetAsync("auth_token", token);

public async Task<string> GetTokenAsync()
    => await SecureStorage.GetAsync("auth_token");

public async Task<Location> GetLastLocationAsync()
    => await Geolocation.GetLastKnownLocationAsync();

On Android, ensure AndroidX is enabled (required since Essentials 1.7). On iOS, the Keychain entry uses the default access group; if your app uses multiple Keychain groups or runs an App Extension, add the keychain-access-groups entitlement and configure the group in Entitlements.plist.

Permissions are also unified. Requesting location while-in-use becomes:

var status = await Permissions.RequestAsync<Permissions.LocationWhenInUse>();
if (status == PermissionStatus.Granted) {
    var loc = await Geolocation.GetLastKnownLocationAsync();
}

No platform-specific permission rationale dialogs — Essentials shows the system prompt automatically.

Trade-offs and current limitations

• Coverage gap: Essentials exposes ~30 APIs (geolocation, secure storage, connectivity, sensors, app info, file helpers). It does not cover advanced Bluetooth LE GATT, background fetch, or platform-specific UI extensions. Those still require custom code or community plugins.
• Android background location: Continuous background updates on Android 10+ need ACCESS_BACKGROUND_LOCATION and a foreground service. Essentials does not create the service; you must implement it yourself.
• Maintenance mode: The package receives critical bug fixes only. No new platform features will be added. The long-term path is .NET MAUI, where the same APIs live under Microsoft.Maui.Essentials.
• AndroidX requirement: Projects still on legacy Android support libraries must migrate to AndroidX before upgrading to Essentials 1.7+.

Actionable next steps

1. Create a test Xamarin.Forms project, add Xamarin.Essentials NuGet, initialize in both platform projects, and run await Geolocation.GetLastKnownLocationAsync() and SecureStorage.SetAsync("token", "value") on iOS simulator and Android emulator.
2. Confirm the installed version matches the latest 1.7.x release on NuGet.
3. Run the linker analyzer in Release: dotnet build -p:RunLinkerAnalyzer=true to verify no Essentials APIs are stripped.
4. Review the official migration guide (learn.microsoft.com/dotnet/maui/migration/xamarin-forms-essentials) to map namespaces from Xamarin.Essentials.* to Microsoft.Maui.Essentials.* for future MAUI adoption.

Adopting Xamarin.Essentials today removes a maintenance burden for the most common device features and gives you a clear, low-friction migration path when you move to .NET MAUI.