Telerik blogs
XamarinT2 Light_1200x303

In this article we take a look at Xamarin.Essentials, Microsoft's official cross-platform library for accessing native features in your Xamarin apps.

Xamarin.Forms makes creating a beautiful and functional mobile app possible straight out of the box. Sooner or later, though, you’ll want access to some native functionality of the device. You may need access to the device’s precise location, or maybe to detect a device shake or open the phone dialer.

Of course, Xamarin has access to all of the native APIs that you need, and it’s pretty straightforward to drop down into native code through Dependency Services—although you’ll need some pretty deep knowledge of the underlying platform for some tasks.

That’s where Xamarin.Essentials comes in. It’s an official NuGet package from Xamarin that gives you access to over 30 features across iOS, Android and UWP, all from your shared C# code.

Getting up and running with Xamarin Essentials couldn’t be easier. Simply add the NuGet package, add a little setup code for Android, and it’s ready to use.

Xamarin.Essentials currently offers the following features:

  • Accelerometer: Retrieve acceleration data of the device in three-dimensional space.
  • App Information: Find out information about the application.
  • Barometer: Monitor the barometer for pressure changes.
  • Battery: Easily detect battery level, source, and state.
  • Clipboard: Quickly and easily set or read text on the clipboard.
  • Color Converters: Helper methods for System.Drawing.Color.
  • Compass: Monitor compass for changes.
  • Connectivity: Check connectivity state and detect changes.
  • Detect Shake: Detect a shake movement of the device.
  • 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: Geocode and reverse geocode addresses and coordinates.
  • Geolocation: Retrieve the device’s GPS location.
  • Gyroscope: Track rotation around the device’s three primary axes.
  • Launcher: Enables an application to open a URI by the system.
  • Magnetometer: Detect device’s orientation relative to Earth’s magnetic field.
  • MainThread: Run code on the application’s main thread.
  • Maps: Open the maps application to a specific location.
  • Open Browser: Quickly and easily open a browser to a specific website.
  • Orientation Sensor: Retrieve the orientation of the device in three-dimensional space.
  • Phone Dialer: Open the phone dialer.
  • Platform Extensions: Helper methods for converting Rect, Size, and Point.
  • Preferences: Quickly and easily add persistent preferences.
  • Secure Storage: Securely store data.
  • Share: Send text and website uris to other apps.
  • SMS: Create an SMS message for sending.
  • Text-to-Speech: Vocalize text on the device.
  • Unit Converters: Helper methods to convert units.
  • Version Tracking: Track the applications version and build numbers.
  • Vibrate: Make the device vibrate.

Let’s get started by building a cross-platform app that uses a few device features. It’s going to be a handy little compass app with a battery level indicator—perfect for demonstrating some simple cross platform services.

File -> New Project

We’ll start by creating a new Xamarin.Forms cross-platform project for iOS and Android. In this case just create a new Blank app using .NET Standard for your “Code Sharing Strategy.” We’ll call the app “Lost.”

Creating a new Xamarin.Forms project

Once the scaffolded project is ready, right-click on the solution and choose “Manage NuGet Packages for Solution.” Search for Xamarin.Essentials under Browse, and install the latest version into all of the projects.

Handling Permissions

Android requires a little setup code for handling permissions requests. Not all the Xamarin.Essentials features require this, but it’s good practice to put it in so you don’t have to come back to it later when you are wondering why something isn’t working.

Firstly, Xamarin.Essentials needs to be initialized in the OnCreate of any activity where it is used, just after the baseOnCreate call:

base.OnCreate(savedInstanceState); 
Xamarin.Essentials.Platform.Init(this, savedInstanceState); // add this line

Finally, to handle runtime permissions, Xamarin.Essentials needs to receive any OnRequestPermissionsResult, so add the following to the 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); 
}

Resources

The final bit of set up for this particular project is to add a compass rose image. The app is going to display our current direction, so I created a quick version of a compass rose that we can rotate rather than just showing some text. Place the image in the usual spots—Drawable folders for Android and Resources for iOS. Of course, for a real app, you are going to want to create the correctly sized images and pop them in the various Drawable folders.

Displaying Our Direction

Open up MainPage.xaml and replace the default StackPanel content with some markup for displaying our compass:

<StackLayout Margin="100"
             HorizontalOptions="FillAndExpand"
             VerticalOptions="FillAndExpand">
   <Image x:Name="CompassRose" 
          Source="compass_rose.jpg"
          RotationX="50">
   </Image>
</StackLayout>

I’ve added some RotationX to the image for a bit of fun. This tilts the image forward to make it look a little three-dimensional.

In the code-behind, we are going to add some event handling code for the direction change and update the RotationZ of the image as the direction changes. We have to do a quick calculation when rotating the image because the point is to keep N facing North, but that’s really all there is to it.

public partial class MainPage : ContentPage
{
  SensorSpeed _sensorSpeed = SensorSpeed.UI;

  public MainPage()
  {
    InitializeComponent();

    Compass.ReadingChanged += Compass_ReadingChanged;
    Compass.Start(_sensorSpeed);
  }

  private void Compass_ReadingChanged(object sender, CompassChangedEventArgs e)
  {
    var data = e.Reading;
    CompassRose.Rotation = Convert.ToDouble(-1 * data.HeadingMagneticNorth);
  }
}

Don’t forget to add a using statement for Xamarin.Essentials at the top of your file.

Let’s hit F5 to run the app and see how that looks!

Once the emulator is up and running, open up the extended tools so we can manipulate the device in three dimensions. Angle the device so that it appears how you would hold it naturally, and check out how the compass rose moves when you adjust the Z-Rotation of the emulator. If we’ve got it right, the compass should move opposite to how you are turning the device, keeping the N pointing at magnetic North.

The working compass

Adding a Battery Level Indicator

The second bit of functionality we’ll add is a simple battery level indicator. Update the XAML on MainPage.xaml to include a label for the percentage display:

<StackLayout Margin="100"
             HorizontalOptions="FillAndExpand"
             VerticalOptions="FillAndExpand">
  <Image x:Name="CompassRose" 
         Source="compass_rose.jpg"
         RotationX="50">
  </Image>
  <Label x:Name="BatteryLevel"
         FontSize="Large"
         FontAttributes="Bold"
         HorizontalOptions="FillAndExpand"
         HorizontalTextAlignment="Center"
         VerticalOptions="CenterAndExpand">
  </Label>
</StackLayout>

Now, in the code-behind we’ll subscribe to battery level changes and update the label appropriately:

Battery.BatteryInfoChanged += Battery_BatteryInfoChanged;
private void Battery_BatteryInfoChanged(object sender, BatteryInfoChangedEventArgs e)
{
  BatteryLevel.Text = $"{Convert.ToInt16(e.ChargeLevel * 100)}%";
}

Now hit F5 to see the app in action and you should run into a little issue.

Permissions required

You can see that using the Xamarin.Essentials plugin doesn’t mean we are exempt from handling permissions correctly on each of the platforms. The exceptions are well worded and helpful, though, so it doesn’t leave much doubt about what we need to do.

Right-click on the Android project and open the project properties. Under Android Manifest, find Required Permissions and make sure that the BATTERY_STATS permission is selected.

For iOS, there are no additional steps required.

Run the app in the emulator again, and you can see that the app is monitoring for battery level changes and updating the label as they occur.

The working battery level

Explore the Rest

In this article we’ve looked at just two of the many features implemented in Xamarin.Essentials and seen just how easy it is to access them in a fully cross-platform way.

Take a look at the official docs to get all the guides you need to implement features from shared code in any Xamarin.Forms, iOS, Android or UWP app.

Read More about Xamarin Essentials

Want to keep reading about Xamarin Essentials features? Check out these guides that will help you understand how to use and implement some key functionalities.


NigelFerrissey
About the Author

Nigel Ferrissey

Nigel Ferrissey is a software developer based in Brisbane, Australia. Nigel has been writing software for as long as he can remember and specializes in .NET, frontend and Xamarin. When he's not writing code, you can find him writing about Xamarin at www.xamarininsider.com or pursuing his other passion, Fender guitars.

Related Posts

Comments

Comments are disabled in preview mode.