Obtener información sobre la bateríaGet battery information

** API importantes **** Important APIs **

Aprende a obtener información detallada sobre la batería mediante las API del espacio de nombres Windows.Devices.Power.Learn how to get detailed battery information using APIs in the Windows.Devices.Power namespace. Un informe de batería (BatteryReport) describe la carga, la capacidad y el estado de la batería o agregado de baterías.A battery report (BatteryReport) describes the charge, capacity, and status of a battery or aggregate of batteries. Este tema muestra cómo tu aplicación puede obtener informes de batería y recibir notificaciones de cambios.This topic demonstrates how your app can get battery reports and be notified of changes. Los ejemplos de código provienen de la aplicación de batería básica que aparece al final de este tema.Code examples are from the basic battery app that's listed at the end of this topic.

Obtener un informe de un conjunto de bateríasGet aggregate battery report

Algunos dispositivos tienen más de una batería y no siempre resulta obvio saber cómo contribuye cada una de ellas a la capacidad de energía global del dispositivo.Some devices have more than one battery and it's not always obvious how each battery contributes to the overall energy capacity of the device. Aquí es donde entra en acción la clase AggregateBattery.This is where the AggregateBattery class comes in. El agregado de baterías representa todos los controladores de la batería conectados al dispositivo y puede proporcionar un único objeto BatteryReport general.The aggregate battery represents all battery controllers connected to the device and can provide a single overall BatteryReport object.

Nota:    Una clase de batería corresponde realmente a un controlador de batería.Note  A Battery class actually corresponds to a battery controller. Según el dispositivo, unas veces se adjunta el controlador a la batería física y otras a la carcasa del dispositivo.Depending on the device, sometimes the controller is attached to the physical battery and sometimes it's attached to the device enclosure. Por tanto, es posible crear un objeto de batería, incluso cuando no hay baterías presentes.Thus, it's possible to create a battery object even when no batteries are present. Otras veces, el objeto de batería puede ser null.Other times, the battery object may be null.

Una vez tengas un objeto del agregado de batería, llama a GetReport para obtener la clase BatteryReport correspondiente.Once you have an aggregate battery object, call GetReport to get the corresponding BatteryReport.

private void RequestAggregateBatteryReport()
{
    // Create aggregate battery object
    var aggBattery = Battery.AggregateBattery;

    // Get report
    var report = aggBattery.GetReport();

    // Update UI
    AddReportUI(BatteryReportPanel, report, aggBattery.DeviceId);
}

Obtener informes de batería individualesGet individual battery reports

También puedes crear un objeto BatteryReport para baterías individuales.You can also create a BatteryReport object for individual batteries. Usa GetDeviceSelector con el método FindAllAsync para obtener una colección de objetos DeviceInformation que representen los controladores de la batería que están conectados al dispositivo.Use GetDeviceSelector with the FindAllAsync method to obtain a collection of DeviceInformation objects that represent any battery controllers that are connected to the device. A continuación, mediante la propiedad Id del objeto DeviceInformation que quieras usar, crea la clase Battery correspondiente con el método FromIdAsyn.Then, using the Id property of the desired DeviceInformation object, create a corresponding Battery with the FromIdAsync method. Por último, llama a GetReport para obtener el informe de batería.Finally, call GetReport to get the individual battery report.

Este ejemplo muestra cómo crear un informe de batería para todas las baterías conectadas al dispositivo.This example shows how to create a battery report for all batteries connected to the device.

async private void RequestIndividualBatteryReports()
{
    // Find batteries 
    var deviceInfo = await DeviceInformation.FindAllAsync(Battery.GetDeviceSelector());
    foreach(DeviceInformation device in deviceInfo)
    {
        try
        {
        // Create battery object
        var battery = await Battery.FromIdAsync(device.Id);

        // Get report
        var report = battery.GetReport();

        // Update UI
        AddReportUI(BatteryReportPanel, report, battery.DeviceId);
        }
        catch { /* Add error handling, as applicable */ }
    }
}

Detalles del informe de accesoAccess report details

El objeto BatteryReport proporciona mucha información sobre la batería.The BatteryReport object provides a lot of battery information. Para obtener más información, consulta la referencia de la API acerca de sus propiedades: Status (una enumeración BatteryStatus), ChargeRateInMilliwatts, DesignCapacityInMilliwattHours, FullChargeCapacityInMilliwattHours y RemainingCapacityInMilliwattHours.For more info, see the API reference for its properties: Status (a BatteryStatus enumeration), ChargeRateInMilliwatts, DesignCapacityInMilliwattHours, FullChargeCapacityInMilliwattHours, and RemainingCapacityInMilliwattHours. Este ejemplo muestra algunas de las propiedades del informe de batería que usa la aplicación de batería básica, la cual se proporciona más adelante en este tema.This example shows some of the battery report properties used by the basic battery app, that's provided later in this topic.

...
TextBlock txt3 = new TextBlock { Text = "Charge rate (mW): " + report.ChargeRateInMilliwatts.ToString() };
TextBlock txt4 = new TextBlock { Text = "Design energy capacity (mWh): " + report.DesignCapacityInMilliwattHours.ToString() };
TextBlock txt5 = new TextBlock { Text = "Fully-charged energy capacity (mWh): " + report.FullChargeCapacityInMilliwattHours.ToString() };
TextBlock txt6 = new TextBlock { Text = "Remaining energy capacity (mWh): " + report.RemainingCapacityInMilliwattHours.ToString() };
...
...

Solicitar actualizaciones de informeRequest report updates

El objeto Battery desencadena el evento ReportUpdated cuando cambia el estado de la batería, la capacidad o la carga.The Battery object triggers the ReportUpdated event when charge, capacity, or status of the battery changes. Generalmente esto sucede de forma inmediata para los cambios de estado y periódicamente para los demás cambios.This typically happens immediately for status changes and periodically for all other changes. Este ejemplo muestra cómo registrarse para recibir las actualizaciones del informe de batería.This example shows how to register for battery report updates.

...
Battery.AggregateBattery.ReportUpdated += AggregateBattery_ReportUpdated;
...

Controlar las actualizaciones del informeHandle report updates

Cuando se produce una actualización de la batería, el evento ReportUpdated pasa el correspondiente objeto Battery al método del controlador de eventos.When a battery update occurs, the ReportUpdated event passes the corresponding Battery object to the event handler method. Sin embargo, no se llama al controlador de eventos desde el subproceso de la interfaz de usuario.However, this event handler is not called from the UI thread. Tendrás que usar el objeto Dispatcher para invocar cualquier cambio en la interfaz de usuario, tal y como se muestra en este ejemplo.You'll need to use the Dispatcher object to invoke any UI changes, as shown in this example.

async private void AggregateBattery_ReportUpdated(Battery sender, object args)
{
    if (reportRequested)
    {

        await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
        {
            // Clear UI
            BatteryReportPanel.Children.Clear();


            if (AggregateButton.IsChecked == true)
            {
                // Request aggregate battery report
                RequestAggregateBatteryReport();
            }
            else
            {
                // Request individual battery report
                RequestIndividualBatteryReports();
            }
        });
    }
}

Ejemplo: aplicación de batería básicaExample: basic battery app

Prueba estas API mediante la creación de la siguiente aplicación de batería básica en Microsoft Visual Studio.Test out these APIs by building the following basic battery app in Microsoft Visual Studio. En la página de inicio de Visual Studio, haz clic en Nuevo proyecto y, a continuación, en las plantillas Visual C# > Windows > Universal; crea una nueva aplicación usando la plantilla Aplicación vacía.From the Visual Studio start page, click New Project, and then under the Visual C# > Windows > Universal templates, create a new app using the Blank App template.

Después abre el archivo MainPage.xaml y copia el siguiente XML en el archivo (y reemplaza su contenido original).Next, open the file MainPage.xaml and copy the following XML into this file (replacing its original contents).

<Page
    x:Class="App1.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:App1"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d">

    <StackPanel Background="{ThemeResource ApplicationPageBackgroundThemeBrush}" >
        <StackPanel VerticalAlignment="Center" Margin="15,30,0,0" >
            <RadioButton x:Name="AggregateButton" Content="Aggregate results" GroupName="Type" IsChecked="True" />
            <RadioButton x:Name="IndividualButton" Content="Individual results" GroupName="Type" IsChecked="False" />
        </StackPanel>
        <StackPanel Orientation="Horizontal">
        <Button x:Name="GetBatteryReportButton" 
                Content="Get battery report" 
                Margin="15,15,0,0" 
                Click="GetBatteryReport"/>
        </StackPanel>
        <StackPanel x:Name="BatteryReportPanel" Margin="15,15,0,0"/>
    </StackPanel>
</Page>

Si el nombre de la aplicación no es App1, deberás reemplazar la primera parte del nombre de la clase en el fragmento anterior por el espacio de nombres de tu aplicación.If your app isn't named App1, you'll need to replace the first part of the class name in the previous snippet with the namespace of your app. Por ejemplo, si creaste un proyecto denominado BasicBatteryApp, reemplazarías x:Class="App1.MainPage" por x:Class="BasicBatteryApp.MainPage".For example, if you created a project named BasicBatteryApp, you'd replace x:Class="App1.MainPage" with x:Class="BasicBatteryApp.MainPage". También deberás reemplazar xmlns:local="using:App1" por xmlns:local="using:BasicBatteryApp".You should also replace xmlns:local="using:App1" with xmlns:local="using:BasicBatteryApp".

A continuación, abre el archivo MainPage.xaml.cs del proyecto y reemplaza el código existente por el siguiente.Next, open your project's MainPage.xaml.cs file and replace the existing code with the following.

using System;
using Windows.UI.Xaml;
using Windows.UI.Xaml.Controls;
using Windows.UI.Xaml.Media;
using Windows.Devices.Enumeration;
using Windows.Devices.Power;
using Windows.UI.Core;

namespace App1
{
    public sealed partial class MainPage : Page
    {
        bool reportRequested = false;
        public MainPage()
        {
            this.InitializeComponent();
            Battery.AggregateBattery.ReportUpdated += AggregateBattery_ReportUpdated;
        }


        private void GetBatteryReport(object sender, RoutedEventArgs e)
        {
            // Clear UI
            BatteryReportPanel.Children.Clear();


            if (AggregateButton.IsChecked == true)
            {
                // Request aggregate battery report
                RequestAggregateBatteryReport();
            }
            else
            {
                // Request individual battery report
                RequestIndividualBatteryReports();
            }

            // Note request
            reportRequested = true;
        }

        private void RequestAggregateBatteryReport()
        {
            // Create aggregate battery object
            var aggBattery = Battery.AggregateBattery;

            // Get report
            var report = aggBattery.GetReport();

            // Update UI
            AddReportUI(BatteryReportPanel, report, aggBattery.DeviceId);
        }

        async private void RequestIndividualBatteryReports()
        {
            // Find batteries 
            var deviceInfo = await DeviceInformation.FindAllAsync(Battery.GetDeviceSelector());
            foreach(DeviceInformation device in deviceInfo)
            {
                try
                {
                // Create battery object
                var battery = await Battery.FromIdAsync(device.Id);

                // Get report
                var report = battery.GetReport();

                // Update UI
                AddReportUI(BatteryReportPanel, report, battery.DeviceId);
                }
                catch { /* Add error handling, as applicable */ }
            }
        }


        private void AddReportUI(StackPanel sp, BatteryReport report, string DeviceID)
        {
            // Create battery report UI
            TextBlock txt1 = new TextBlock { Text = "Device ID: " + DeviceID };
            txt1.FontSize = 15;
            txt1.Margin = new Thickness(0, 15, 0, 0);
            txt1.TextWrapping = TextWrapping.WrapWholeWords;

            TextBlock txt2 = new TextBlock { Text = "Battery status: " + report.Status.ToString() };
            txt2.FontStyle = Windows.UI.Text.FontStyle.Italic;
            txt2.Margin = new Thickness(0, 0, 0, 15);

            TextBlock txt3 = new TextBlock { Text = "Charge rate (mW): " + report.ChargeRateInMilliwatts.ToString() };
            TextBlock txt4 = new TextBlock { Text = "Design energy capacity (mWh): " + report.DesignCapacityInMilliwattHours.ToString() };
            TextBlock txt5 = new TextBlock { Text = "Fully-charged energy capacity (mWh): " + report.FullChargeCapacityInMilliwattHours.ToString() };
            TextBlock txt6 = new TextBlock { Text = "Remaining energy capacity (mWh): " + report.RemainingCapacityInMilliwattHours.ToString() };

            // Create energy capacity progress bar & labels
            TextBlock pbLabel = new TextBlock { Text = "Percent remaining energy capacity" };
            pbLabel.Margin = new Thickness(0,10, 0, 5);
            pbLabel.FontFamily = new FontFamily("Segoe UI");
            pbLabel.FontSize = 11;

            ProgressBar pb = new ProgressBar();
            pb.Margin = new Thickness(0, 5, 0, 0);
            pb.Width = 200;
            pb.Height = 10;
            pb.IsIndeterminate = false;
            pb.HorizontalAlignment = HorizontalAlignment.Left;

            TextBlock pbPercent = new TextBlock();
            pbPercent.Margin = new Thickness(0, 5, 0, 10);
            pbPercent.FontFamily = new FontFamily("Segoe UI");
            pbLabel.FontSize = 11;

            // Disable progress bar if values are null
            if ((report.FullChargeCapacityInMilliwattHours == null)||
                (report.RemainingCapacityInMilliwattHours == null))
            {
                pb.IsEnabled = false;
                pbPercent.Text = "N/A";
            }
            else
            {
                pb.IsEnabled = true;
                pb.Maximum = Convert.ToDouble(report.FullChargeCapacityInMilliwattHours);
                pb.Value = Convert.ToDouble(report.RemainingCapacityInMilliwattHours);
                pbPercent.Text = ((pb.Value / pb.Maximum) * 100).ToString("F2") + "%";
            }

            // Add controls to stackpanel
            sp.Children.Add(txt1);
            sp.Children.Add(txt2);
            sp.Children.Add(txt3);
            sp.Children.Add(txt4);
            sp.Children.Add(txt5);
            sp.Children.Add(txt6);
            sp.Children.Add(pbLabel);
            sp.Children.Add(pb);
            sp.Children.Add(pbPercent);
        }

        async private void AggregateBattery_ReportUpdated(Battery sender, object args)
        {
            if (reportRequested)
            {

                await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
                {
                    // Clear UI
                    BatteryReportPanel.Children.Clear();


                    if (AggregateButton.IsChecked == true)
                    {
                        // Request aggregate battery report
                        RequestAggregateBatteryReport();
                    }
                    else
                    {
                        // Request individual battery report
                        RequestIndividualBatteryReports();
                    }
                });
            }
        }
    }
}

Si la aplicación no se llama App1, tendrás que cambiar el nombre del espacio de nombres en el ejemplo anterior por el nombre de tu proyecto.If your app isn't named App1, you'll need to rename the namespace in the previous example with the name you gave your project. Por ejemplo, si creaste un proyecto denominado BasicBatteryApp, reemplazarías el espacio de nombres App1 por BasicBatteryApp.For example, if you created a project named BasicBatteryApp, you'd replace namespace App1 with namespace BasicBatteryApp.

Por último, para ejecutar esta aplicación de batería básica: en el menú Depurar, haz clic en Iniciar depuración para probar la solución.Finally, to run this basic battery app: on the Debug menu, click Start Debugging to test the solution.

Sugerencia    Para recibir valores numéricos del objeto BatteryReport , depure la aplicación en el equipo local o en un dispositivo externo (como un Windows Phone).Tip  To receive numeric values from the BatteryReport object, debug your app on the Local Machine or an external Device (such as a Windows Phone). Al depurar en un emulador de dispositivo, el objeto BatteryReport devuelve null a las propiedades de capacidad y velocidad.When debugging on a device emulator, the BatteryReport object returns null to the capacity and rate properties.