Upgrading to Xamarin.Essentials from Plugins

Xamarin.Essentials is a new official library from Microsoft (that I worked on) that provides developers with over 30 cross-platform APIs for their mobile apps to tap into to access native features. Yes, this may sound similar to Plugins for Xamarin, but it is an evolution that is super optimized for each plaform, provides a consistent API, and is super crazy well documented. And of course it is completely open source on GitHub!

Why Upgrade?

A lot of developers have asked me why they should upgrade their apps, that have been using Plugins for a long time, to Xamarin.Essentials. Here is my list:

1. This is an OFFICIAL package from the Xamarin team at Microsoft.
2. It is super optimized and Linker Safe!
3. All of your favorite plugins are there.
4. Only has 1 assembly to help boost your app's startup time.
5. Super consistent API across all features.
6. Because it is awesome and super well tested.

Also because I upgraded one of my apps and it reduced that app's assemblies from 47 to 35 and even reduced the application size from 22.7MB to 22.2MB! Because it is crazy optimized!

With Xamarin.Essentials we started over from the beginning and we were able to craft new APIs for features, which means it wasn't just a copy and paste of plugins out there. We re-thought each and every API, optimized them with new code paths for each platform, integrated unit tests and samples, and documented the heck out of them.

This means if you are moving from Plugins to Essentials there is a tiny bit of work you need to do.

Getting Started

We have a great Getting Started Guide that outlines everything you need to know on how to install the NuGet package that you need. Be aware that since it is a single NuGet package this means on Android we DO NOT automatically add permissions, so read the docs on each API to see what you need to add.

The APIs!

I will try to cover as many of my Plugins as I can, but I am sure I will miss some of them. Here we go!

Settings

My settings plugin was not only my first plugin that I ever created, but it also is my most popular plugin with over 1.4 Million NuGet installs over the years. Xamarin.Essentials replaces and upgrades it with the Preferences API. The APIs are extremely similar, but fixes a lot of small things that had been lingering around in my code. It is a very smooth transition as they both use the same default locations to store preferences and even allow for a specific name to be passed in.

Preferences API Access

• Plugin: CrossSettings.Current.
• Essentials: Preferences.

Preferences API

• GetValueOrDefault -> Get
• AddOrUpdateValue -> Set

The key difference here is that Set simply is a method void call and saves the value every time.

While the new preferences API saves to the same places it doesn't support all of the value types that the Settings Plugin does like decimals. I should have never supported these as I have to store them as string, but you can convert it easily like this:

public decimal MyDecimal
{
   get 
  {
       var savedDecimal = Preferences.Get("mykey",  Convert.ToString(0, CultureInfo.InvariantCulture));
       return Convert.ToDecimal(savedDecimal, CultureInfo.InvariantCulture)
   } 
   set { Preferences.Set("mykey", Convert.ToString(value, CultureInfo.InvariantCulture)); }
}

In addition to the core APIs you could also open the app settings page on the device. This can now be done in the AppInfo API of Essentials:

• CrossSettings.Current.OpenAppSettings(); -> AppInfo.OpenSettings();

Connectivity Plugin

Oh connectivity plugin... I love you! My second most popular plugin out there that has helped developers detect if there is an internet connection for several years. This is also an easy one as many of the APIs are packed into Xamarin.Essentials Connectivity API. There is a little bit of setup for permissions that you should do if you want to check connection types.

Connectivity API Access

• Plugin: CrossConnectivity.Current.
• Essentials: Connectivity.

Connectivity API

• IsConnected -> NetworkAccess (now returns an enum)
• ConnectionTypes -> Profiles
• ConnectivityChanged & ConnectivityTypeChanged -> ConnectivityChanged (all rolled into 1 nice event)

So you can replace this:

if (!CrossConnectivity.Current.IsConnected)
{
    //we are offline
}

with this:

if (Connectivity.NetworkAccess != NetworkAccess.Internet)
{
    //we are offline
}

APIs that don't exist

• IsReachable & IsRemoteReachable: You can read my full analysis on GitHub as to why we did not include this, but long story short I should have never included these. It really makes no sense to try to ping a site to see if it is there instead of just making the web request.
• Bandwidth: Never really was a need and super inconsistent.

App Version / Version Tracking

I simply love our App Info API that gives you all sorts of info about your application. You may have been using other plugins such as DeviceInfo or VersionTracking, but you can just use AppInfo now:

App Info API Access

• Essentials: AppInfo.

App Info API

• Name
• PackageName
• VersionString
• BuildString

There is also a new Version Tracking API that is nearly a 1 to 1 replacement for the old plugin.

Version Tracking API Access

• Plugin: CrossVersionTracking.Current.
• Essentials: VersionTracking.

Version Tracking API

• Track(); -> Track();
• IsFirstLaunchEver -> IsFirstLaunchEver
• IsFirstLaunchForVersion -> IsFirstLaunchForCurrentVersion
• IsFirstLaunchForBuild -> IsFirstLaunchForCurrentBuild
• CurrentVersion -> CurrentVersion
• PreviousVersion -> PreviousVersion
• FirstInstalledVersion -> FirstInstalledVersion
• VersionHistory -> VersionHistory
• CurrentBuild -> CurrentBuild
• PreviousBuild -> PreviousVersion
• FirstInstalledBuild -> FirstInstalledBuild
• BuildHistory -> BuildHistory

There are a lot of enhancements to this API including that it just uses the built-in Preferences API instead of serialization and file IO.

Share Plugin

The share plugin kept growing and started to add tons of APIs for no good reason including opening the browser or setting text on the clipboard. Don't worry though because Xamarin.Essentials has a Data Transfer, Clipboard, and Browser API built right in!

API Access

• Plugin: CrossShare.Current.
• Essentials: Browser.
• Essentials: Clipboard.
• Essentials: DataTransfer. (this is Share)

Browser API

• OpenBrowser -> OpenAsync
• BrowserOptions -> BrowserLaunchType (no current open to specify colors)

Clipboard API

• SetClipboardText -> SetText
• NEW API -> GetTextAsync

Data Transfer API

• Share -> RequestAsync
• Pass in a ShareTextRequest which specifies text or a uri.

Device Information

I loved to hate my Device Info plugin becaues it had a lot of great ideas and a lot of bad ideas such as the original implementation of ID and a bunch of other random methods. This has all been fixed with Xamarin.Essentials and the Device Information API, and the addition of the Device Display API that adds the ability to get information about the device's screen metrics, which is very nifty.

API Access

• Plugin: CrossDeviceInfo.Current.
• Essentials: DeviceInfo.

DeviceInfo API

• Model -> Model
• Manufacturer -> Manufacturer
• DeviceName -> Name
• Version -> VersionString
• AppVersion -> Now: AppInfo.VersionString
• AppBuild -> Now AppInfo.BuildString
• Platform -> Platform
• Idiom -> Idiom
• IsDevice -> DeviceType

Geolocator

Another popular plugin of mine that was originally brought over from the old Xamarin.Mobile code base. Xamarin.Essentials has built this API from the ground up on each platform and really thought about what developers need from this API. That is why there are actually two APIs that developers can use and a standardization on what a Location and Placemark is. So hopefully any other APIs could start using these. The first API is Geolocation which is how to get the cached location or current location on the device. Also Geocoding enables getting the Placemark for a Location. As of right now there is no tracking of location changes, but that is on the roadmap.

API Access

• Plugin: CrossGeolocator.Current.
• Essentials: Geolocation.
• Essentials: Geocoding.

Geolocation API

• GetLastKnownLocationAsync -> GetLastKnownLocationAsync
• GetPositionAsync -> GetLocationAsync

Geocoding API

• GetAddressesForPositionAsync -> GetPlacemarksAsync
• GetPositionsForAddressAsync -> GetLocationsAsync

Text-to-Speech

My plugin has gone under a lot of changes over the year and I have learned a lot that went into the new Text-to-Speech API in Xamarin.Essentials.

API Access

• Plugin: CrossTextToSpeech.Current.
• Essentials: TextToSpeech.

Text to Speech API

• Speak -> SpeakAsync
• GetInstalledLanguages -> GetLocalesAsync

Vibrate

Another simple tranisition to the Vibrate API and even adds some new methods. For Android be sure to setup permissions correctly in your Android Manifest.

API Access

• Plugin: CrossVibrate.Current.
• Essentials: Vibration.

Vibration API

• Vibration -> Vibrate
• NEW API -> Cancel

Battery

When you need to check the battery status of the device the Battery API is for you! We also have a new Power API that will help you detect if the device is in power saver mode too!

API Access

• Plugin: CrossBattery.Current.
• Essentials: Battery.

Battery API

• RemainingChargePercent -> ChargeLevel (0 to 1.0)
• Status -> State
• PowerSource -> PowerSource
• BatteryChanged -> BatteryChanged

Wrapping Up

If you made it this far then I am impressed and want to give you a big hug! Xamarin.Essentials is pretty fantastic and I hope that you see how easy it is to change over from Plugins, that it has the ability to shrink your app size and help with startup time by reducing your total assemblies in your app.

One thing to note is that my plugins aren't going away any time soon. Many of them will go into maintenance mode as I push developers towards Xamarin.Essentials. The key difference is that many of my plugins for better or worse support a lot of different platforms that aren't supported yet in Essentials.

There are also some plugins that I plan on supporting long term as they provide functionality not yet in Essentials such as Permissions and Store Review or features that aren't planned at all such as IniApp Billing.