Abrufen von AkkuinformationenGet battery information

** Wichtige APIs **** Important APIs **

Erfahren Sie, wie Sie mithilfe von APIs im Windows.Devices.Power-Namespace ausführliche Akkuinformationen erhaltenLearn how to get detailed battery information using APIs in the Windows.Devices.Power namespace. In einem Akkubericht (BatteryReport) werden der Ladezustand, die Kapazität und der Status eines Akkus oder Akkuaggregats beschrieben.A battery report (BatteryReport) describes the charge, capacity, and status of a battery or aggregate of batteries. In diesem Thema wird veranschaulicht, wie Ihre App Akkuberichte abrufen und über Veränderungen informiert werden kann.This topic demonstrates how your app can get battery reports and be notified of changes. Die Codebeispiele stammen aus der einfachen Akku-App, die am Ende dieses Themas angegeben wird.Code examples are from the basic battery app that's listed at the end of this topic.

Abrufen eines zusammengefassten AkkuberichtsGet aggregate battery report

Einige Geräte verfügen über mehr als einen Akku, und es ist nicht immer eindeutig, in welcher Form die einzelnen Akkus zur gesamten Energiekapazität des Geräts beitragen.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. An dieser Stelle wird die AggregateBattery-Klasse verwendet.This is where the AggregateBattery class comes in. AggregateBattery repräsentiert alle Akkucontroller, die mit dem Gerät verbunden sind. Damit kann ein zusammengefasstes BatteryReport-Objekt bereitgestellt werden.The aggregate battery represents all battery controllers connected to the device and can provide a single overall BatteryReport object.

Beachten Sie  ein Akku Klasse entspricht tatsächlich einen Akku-Controller.Note  A Battery class actually corresponds to a battery controller. Je nach Gerät kann der Controller auch am physischen Akku angeschlossen sein, und es kommt auch vor, dass er am Gehäuse des Geräts angeschlossen ist.Depending on the device, sometimes the controller is attached to the physical battery and sometimes it's attached to the device enclosure. So kann auch dann ein Akkuobjekt erstellt werden, wenn keine Akkus vorhanden sind.Thus, it's possible to create a battery object even when no batteries are present. In anderen Fällen kann für das Akkuobjekt null gelten.Other times, the battery object may be null.

Wenn Sie über ein zusammengefasstes Akkuobjekt verfügen, rufen Sie GetReport auf, um den entsprechenden BatteryReport abzurufen.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);
}

Abrufen von individuellen AkkuberichtenGet individual battery reports

Sie können auch ein BatteryReport-Objekt für individuelle Akkus erstellen.You can also create a BatteryReport object for individual batteries. Verwenden Sie GetDeviceSelector mit der FindAllAsync-Methode zum Abrufen einer Sammlung mit DeviceInformation-Objekten, die alle mit dem Gerät verbundenen Akkucontroller repräsentieren.Use GetDeviceSelector with the FindAllAsync method to obtain a collection of DeviceInformation objects that represent any battery controllers that are connected to the device. Erstellen Sie anschließend mit der Id-Eigenschaft des gewünschten DeviceInformation-Objekts ein entsprechendes Battery-Element mit der Methode FromIdAsync.Then, using the Id property of the desired DeviceInformation object, create a corresponding Battery with the FromIdAsync method. Rufen Sie zuletzt GetReport auf, um den individuellen Akkubericht abzurufen.Finally, call GetReport to get the individual battery report.

Dieses Beispiel zeigt, wie Sie einen Akkubericht für alle Akkus erstellen, die mit dem Gerät verbunden sind.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 */ }
    }
}

Zugreifen auf BerichtdetailsAccess report details

Das BatteryReport-Objekt liefert zahlreiche Akkuinformationen.The BatteryReport object provides a lot of battery information. Weitere Informationen finden Sie in der API-Referenz für die zugehörigen Eigenschaften: Status (eine BatteryStatus Enumeration), ChargeRateInMilliwatts, DesignCapacityInMilliwattHours, FullChargeCapacityInMilliwattHours, und RemainingCapacityInMilliwattHours.For more info, see the API reference for its properties: Status (a BatteryStatus enumeration), ChargeRateInMilliwatts, DesignCapacityInMilliwattHours, FullChargeCapacityInMilliwattHours, and RemainingCapacityInMilliwattHours. Dieses Beispiel enthält einige Eigenschaften des Akkuberichts, die von der einfachen Akku-App verwendet werden. Die App wird weiter unten in diesem Thema bereitgestellt.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() };
...
...

Anfordern von BerichtsaktualisierungenRequest report updates

Das Battery-Objekt löst das ReportUpdated-Ereignis aus, wenn sich Ladezustand, Kapazität oder Status des Akkus ändern.The Battery object triggers the ReportUpdated event when charge, capacity, or status of the battery changes. Dies geschieht für Statusänderungen in der Regel sofort, und für alle anderen Änderungen in regelmäßigen Abständen.This typically happens immediately for status changes and periodically for all other changes. Dieses Beispiel zeigt, wie Sie die Registrierung für Aktualisierungen des Akkuberichts durchführen.This example shows how to register for battery report updates.

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

Behandeln von BerichtsaktualisierungenHandle report updates

Bei einer Aktualisierung des Akkuberichts übergibt das ReportUpdated-Ereignis das entsprechende Battery-Objekt an die Ereignishandlermethode.When a battery update occurs, the ReportUpdated event passes the corresponding Battery object to the event handler method. Dieser Ereignishandler wird jedoch nicht über den UI-Thread aufgerufen.However, this event handler is not called from the UI thread. Sie müssen das Dispatcher-Objekt verwenden, um UI-Änderungen aufzurufen. Dies wird im folgenden Beispiel gezeigt.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();
            }
        });
    }
}

Beispiel: einfache Akku-AppExample: basic battery app

Testen Sie diese APIs, indem Sie die folgende einfache Akku-App in Microsoft Visual Studio erstellen.Test out these APIs by building the following basic battery app in Microsoft Visual Studio. Klicken Sie auf der Startseite von Visual Studio auf Neues Projekt, und erstellen Sie dann im Bereich mit den Vorlagen unter Visual C# > Windows > Universal eine neue App, indem Sie die Vorlage Leere App verwenden.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.

Öffnen Sie als Nächstes die Datei MainPage.xaml, und kopieren Sie den folgenden XML-Code in diese Datei, sodass der Originalinhalt ersetzt wird.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>

Wenn Ihre App nicht den Namen App1 hat, müssen Sie den ersten Teil des Klassennamens im vorhergehenden Codeausschnitt durch den Namespace Ihrer App ersetzen.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. Wenn Sie z. B. ein Projekt mit dem Namen BasicBatteryApp erstellt haben, ersetzen Sie x:Class="App1.MainPage" durch 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". Ersetzen Sie außerdem xmlns:local="using:App1" durch xmlns:local="using:BasicBatteryApp".You should also replace xmlns:local="using:App1" with xmlns:local="using:BasicBatteryApp".

Öffnen Sie als Nächstes die Datei MainPage.xaml.cs des Projekts, und ersetzen Sie den vorhandenen Code durch Folgendes.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();
                    }
                });
            }
        }
    }
}

Wenn Ihre App nicht den Namen App1 hat, müssen Sie den Namespace im vorherigen Beispiel durch den Namen ersetzen, den Sie für Ihr Projekt vergeben haben.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. Wenn Sie z. B. ein Projekt mit dem Namen BasicBatteryApp erstellt haben, ersetzen Sie den Namespace App1 durch den Namespace BasicBatteryApp.For example, if you created a project named BasicBatteryApp, you'd replace namespace App1 with namespace BasicBatteryApp.

Führen Sie schließlich Folgendes aus, um diese einfache Akku-App auszuführen: Klicken Sie im Menü Debuggen auf Debuggen starten, um die Projektmappe zu testen.Finally, to run this basic battery app: on the Debug menu, click Start Debugging to test the solution.

Tipp  zum Empfangen von numerischer Werten aus der BatteryReport Objekt, das Debuggen Ihrer app auf die lokalen Computer oder einer externen Gerät (z. B. eine 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). Beim Debuggen mit einem Geräteemulator gibt das BatteryReport-Objekt für die Kapazitäts- und Rateneigenschaften null zurück.When debugging on a device emulator, the BatteryReport object returns null to the capacity and rate properties.