Xamarin.Essentials: Battery
The Battery class lets you check the device's battery information and monitor for changes and provides information about the device's energy-saver status, which indicates if the device is running in a low-power mode. Applications should avoid background processing if the device's energy-saver status is on.
Get started
To start using this API, read the getting started guide for Xamarin.Essentials to ensure the library is properly installed and set up in your projects.
To access the Battery functionality the following platform specific setup is required.
The Battery permission is required and must be configured in the Android project. This can be added in the following ways:
Open the AssemblyInfo.cs file under the Properties folder and add:
[assembly: UsesPermission(Android.Manifest.Permission.BatteryStats)]
OR Update Android Manifest:
Open the AndroidManifest.xml file under the Properties folder and add the following inside of the manifest node.
<uses-permission android:name="android.permission.BATTERY_STATS" />
Or right click on the Android project and open the project's properties. Under Android Manifest find the Required permissions: area and check the Battery permission. This will automatically update the AndroidManifest.xml file.
Using Battery
Add a reference to Xamarin.Essentials in your class:
using Xamarin.Essentials;
Check current battery information:
var level = Battery.ChargeLevel; // returns 0.0 to 1.0 or 1.0 when on AC or no battery.
var state = Battery.State;
switch (state)
{
case BatteryState.Charging:
// Currently charging
break;
case BatteryState.Full:
// Battery is full
break;
case BatteryState.Discharging:
case BatteryState.NotCharging:
// Currently discharging battery or not being charged
break;
case BatteryState.NotPresent:
// Battery doesn't exist in device (desktop computer)
break;
case BatteryState.Unknown:
// Unable to detect battery state
break;
}
var source = Battery.PowerSource;
switch (source)
{
case BatteryPowerSource.Battery:
// Being powered by the battery
break;
case BatteryPowerSource.AC:
// Being powered by A/C unit
break;
case BatteryPowerSource.Usb:
// Being powered by USB cable
break;
case BatteryPowerSource.Wireless:
// Powered via wireless charging
break;
case BatteryPowerSource.Unknown:
// Unable to detect power source
break;
}
Whenever any of the battery's properties change an event is triggered:
public class BatteryTest
{
public BatteryTest()
{
// Register for battery changes, be sure to unsubscribe when needed
Battery.BatteryInfoChanged += Battery_BatteryInfoChanged;
}
void Battery_BatteryInfoChanged(object sender, BatteryInfoChangedEventArgs e)
{
var level = e.ChargeLevel;
var state = e.State;
var source = e.PowerSource;
Console.WriteLine($"Reading: Level: {level}, State: {state}, Source: {source}");
}
}
Devices that run on batteries can be put into a low-power energy-saver mode. Sometimes devices are switched into this mode automatically, for example, when the battery drops below 20% capacity. The operating system responds to energy-saver mode by reducing activities that tend to deplete the battery. Applications can help by avoiding background processing or other high-power activities when energy-saver mode is on.
You can also obtain the current energy-saver status of the device using the static Battery.EnergySaverStatus property:
// Get energy saver status
var status = Battery.EnergySaverStatus;
This property returns a member of the EnergySaverStatus enumeration, which is either On, Off, or Unknown. If the property returns On, the application should avoid background processing or other activities that might consume a lot of power.
The application should also install an event handler. The Battery class exposes an event that is triggered when the energy-saver status changes:
public class EnergySaverTest
{
public EnergySaverTest()
{
// Subscribe to changes of energy-saver status
Battery.EnergySaverStatusChanged += OnEnergySaverStatusChanged;
}
private void OnEnergySaverStatusChanged(EnergySaverStatusChangedEventArgs e)
{
// Process change
var status = e.EnergySaverStatus;
}
}
If the energy-saver status changes to On, the application should stop performing background processing. If the status changes to Unknown or Off, the application can resume background processing.