Get Started with Xamarin.Essentials

Pre-release NuGet

Xamarin.Essentials provides a single cross-platform API that works with any iOS, Android, or UWP application that can be accessed from shared code no matter how the user interface is created.

Platform Support

Xamarin.Essentials supports the following platforms and operating systems:

Platform Version
Android 4.4 (API 19) or higher
iOS 10.0 or higher
UWP 10.0.16299.0 or higher

Installation

Xamarin.Essentials is available as a NuGet package that can be added to any existing or new project using Visual Studio.

  1. Download and install Visual Studio with the Visual Studio tools for Xamarin.

  2. Open an existing project, or create a new project using the Blank App template under Visual Studio C# (Android, iPhone & iPad, or Cross-Platform). Important: If adding to a UWP project ensure Build 16299 or higher is set in the project properties.

  3. Add the Xamarin.Essentials NuGet package to each project:

    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 Android, iOS, UWP, and .NET Standard libraries.

    Tip

    Check the Include prerelease box while the Xamarin.Essentials NuGet is in preview.

  4. Add a reference to Xamarin.Essentials in any C# class to reference the APIs.

    using Xamarin.Essentials;
    
  5. Xamarin.Essentials requires platform-specific setup:

    Xamarin.Essentials supports a minimum Android version of 4.4, corresponding to API level 19, but the target Android version for compiling must be 8.1, corresponding to API level 27. (In Visual Studio, these two versions are set in the Project Properties dialog for the Android project, in the Android Manifest tab. In Visual Studio for Mac, they're set in the Project Options dialog for the Android project, in the Android Application tab.)

    Xamarin.Essentials installs version 27.0.2.1 of the Xamarin.Android.Support libraries that it requires. Any other Xamarin.Android.Support libraries that your application requires should also be updated to version 27.0.2.1 using the NuGet package manager. All Xamarin.Android.Support libraries used by your application should be the same, and should be at least version 27.0.2.1. Refer to the troubleshooting page if you have issues adding the Xamarin.Essentials NuGet or updating NuGets in your solution.

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

    protected override void OnCreate(Bundle savedInstanceState) {
        //...
        base.OnCreate(savedInstanceState);
        Xamarin.Essentials.Platform.Init(this, savedInstanceState); // add this line to your code
        //...
    

    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);
    }
    
  6. Follow the Xamarin.Essentials guides that enable you to copy and paste code snippets for each feature.

Xamarin.Essentials - Cross-Platform APIs for Mobile Apps (video)

Other Resources

We recommend developers new to Xamarin visit Getting Started with Xamarin Development.

Visit the Xamarin.Essentials GitHub Repository to see the current source code, what is coming next, run samples, and clone the repository. Community contributions are welcome!

Browse through the API documentation for every feature of Xamarin.Essentials.