Xamarin.Essentials: Cross-Platform APIs for Mobile Apps
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 :
- Accelerometer: Retrieve acceleration data of the device in three dimensional space.
- App Information: Find out information about the application.
- Battery: Easily detect battery level, source, and state.
- Clipboard: Quickly and easily set or read text on the clipboard.
- Compass: Monitor compass for changes.
- Connectivity: Check connectivity state and detect changes.
- Data Transfer: Send text and website Uris to other apps.
- Device Display Information: Get the device’s screen metrics and orientation.
- Device Information: Find out about the device with ease.
- Email: Easily send email messages.
- File System Helpers: Easily save files to app data.
- Flashlight: A simple way to turn the flashlight on/off.
- Geocoding: Easily geocode and reverse geocoding.
- Geolocation: Retrieve the device’s GPS location.
- Gyroscope: Retrieve rotation around the device’s three primary axes.
- Magnetometer: Detect device’s orientation relative to Earth’s magnetic field.
- Open Browser: Quickly and easily open a browser to a specific website.
- Phone Dialer: Open the phone dialer.
- Preferences: Quickly and easily add persistent preferences.
- Screen Lock: Keep the device screen awake.
- Secure Storage: Securely store data.
- SMS: Easily send SMS messages.
- Text-to-Speech: Vocalize text on the device.
- Version Tracking: Track the applications version and build numbers.
- Vibrate: Make the device vibrate.
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:
- Open an existing project, or create a new project using the Blank App template under Visual Studio C# (Android, iPhone & iPad, or Cross-Platform).
- Add Xamarin.Essentials NuGet package to projects:
- 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.
- 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.
- Add a reference to Xamarin.Essentials in any C# class to reference the APIs.
using Xamarin.Essentials; - 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()
{
InitializeComponent();
// 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()
{
base.OnAppearing();
Compass.Start(SensorSpeed.Ui);
}
protected override void OnDisappearing()
{
base.OnDisappearing();
Compass.Stop();
}
}
}
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.
Light
Dark
0 comments