Xamarin.Essentials: Cross-Platform APIs for Mobile Apps

James Montemagno

When developing iOS and Android apps with Xamarin, developers can access every native platform API using C#. These bindings not only expose the platform APIs in C#, but add powerful C# features, such as async/await, events, delegates, and more. This is a huge advantage for developers, because they never have to leave C#, whether they’re writing shared business logic, user interface, or accessing native features. One key feature developers often look for when developing cross-platform apps with Xamarin is a way to access common native features from their shared code without having to write their own abstractions or find an open source plugin created by the community.

The dream of a single API to access features such as geolocation, sensors, secure storage, and more is now a reality for any application created with Xamarin with Xamarin.Essentials!

Xamarin.Essentials APIs

In our first preview, available today, Xamarin.Essentials APIs provide access to over 25 native features from a single cross-platform API library, which can be accessed from shared code no matter how the user interface is created. This means you can use Xamarin.Essentials APIs with a single Xamarin.Android app or a Xamarin.Forms app targeting iOS, Android, and UWP. Even though it’s packed with features, it’s still fully optimized for performance and minimal impact on app size, because the library takes full advantage of being linker safe. This means only the APIs and features you use will be included in your app and the rest will be removed when you compile your app.

The preview release, with the initial set of cross-platform APIs, can be installed in your apps through NuGet :

The initial set of APIs was based on feedback from Xamarin developers about what they wanted to see from a cross-platform API library. We will continue to add more over time.

Getting Started

It’s easy to start using Xamarin.Essentials APIs in any new or existing app in just a few easy steps:

  1. Open an existing project, or create a new project using the Blank App template under Visual Studio C# (Android, iPhone & iPad, or Cross-Platform).
  2. Add Xamarin.Essentials NuGet package to projects:
    1. Visual Studio: In the Solution Explorer panel, right click on the solution name and select Manage NuGet Packages. Search for Xamarin.Essentials and install the package into ALL projects including iOS, Android, UWP, and .NET Standard Libraries.
    2. Visual Studio for Mac: In the Solution Explorer panel, right click on the project name and select Add -> Add NuGet Packages…. Search for Xamarin.Essentials and install the package into ALL projects including iOS, Android, and .NET Standard Libraries.
  3. Add a reference to Xamarin.Essentials in any C# class to reference the APIs.
    using Xamarin.Essentials;
  4. Xamarin.Essentials requires small additional platform specific setup on Android projects to access specific features:

    Inside of the Android project’s MainLauncher or any Activity that is launched Xamarin.Essentials must be initialized in the OnCreate method:

    Xamarin.Essentials.Platform.Init(this, bundle);

    To handle runtime permissions on Android Xamarin.Essentials must receive any `OnRequestPermissionsResult`. Add the following code to all Activity classes:

    public override void OnRequestPermissionsResult(int requestCode, string[] permissions, [GeneratedEnum] Android.Content.PM.Permission[] grantResults)
        Xamarin.Essentials.Platform.OnRequestPermissionsResult(requestCode, permissions, grantResults);
        base.OnRequestPermissionsResult(requestCode, permissions, grantResults);

That’s it! You’re now ready to start using Xamarin.Essentials APIs in your app. Each API has been fully documented with code snippets that you can copy into your app.

Be sure to read to read our full Getting Started guide for additional details.

Build a Compass

During one of my sessions at Microsoft Build 2018 I showed how to combine Xamarin.Forms and Xamarin.Essentials APIs to build a cross-platform Compass in under 10 minutes. It’s as simple as adding a few images for the compass into the application and a small amount of user interface:





I was able to use the Compass API from Xamarin.Essentials in the code behind for this page in order to register for events when the compass changed and update text of the label and the image’s rotation in just a few lines of code:

using Xamarin.Forms;
using Xamarin.Essentials;

namespace MyCompass
    public partial class MainPage : ContentPage
		public MainPage()

            // Register for reading changes
            Compass.ReadingChanged += Compass_ReadingChanged;

        void Compass_ReadingChanged(object sender, CompassChangedEventArgs e)
            LabelInfo.Text = $"Heading: {e.Reading.HeadingMagneticNorth}";
            ImageArrow.Rotation = e.Reading.HeadingMagneticNorth;

        protected override void OnAppearing()

        protected override void OnDisappearing()

Just like that, a compass application is created! You can find the full source code and images on my GitHub.

What’s Next

Xamarin.Essentials has gone through rigorous testing, but we’re asking you to provide feedback during this short preview cycle. Please try out the library in your apps and report any issue that you may run into on the Xamarin.Essentials GitHub repository.

We see this library as a core fundamental piece of the Xamarin platform and know that it’s an essential building block for all developer and applications. As such, we will be integrating the Xamarin.Essentials NuGet package into every iOS, Android, and Xamarin.Forms template inside Visual Studio and Visual Studio for Mac, so developers have access to these APIs from the very beginning of their project.

See it Live

You can watch a full overview of Xamarin, Xamarin.Forms, and Xamarin.Essentials in my Building mobile apps with Visual Studio and Xamarin session from Microsoft Build 2018:

Xamarin University Guest Lecture

Join me on Thursday, June 7th 10:00 AM PST when I will host a LIVE guest lecture on Xamarin University covering all things Xamarin.Essentials in details and answering all questions. If you aren’t a Xamarin University subscriber simply sign up for a free account to get access to the guest lecture.


Learn More

You can browse through our full documentation that has a full overview of how to get started and how to use each and every feature of Xamarin.Essentials. We have also provided full API reference that can be fully browsed online to dive into the details of Xamarin.Essentials APIs.


Discussion is closed.

Feedback usabilla icon