Festlegen von Bedingungen zum Ausführen einer HintergrundaufgabeSet conditions for running a background task

Wichtige APIsImportant APIs

Erfahren Sie, wie Bedingungen festgelegt werden, die steuern, wann die Hintergrundaufgabe ausgeführt wird.Learn how to set conditions that control when your background task will run.

Manchmal müssen Hintergrundaufgaben bestimmte Bedingungen erfüllen, damit die Hintergrundaufgabe erfolgreich ausgeführt werden kann.Sometimes, background tasks require certain conditions to be met for the background task to succeed. Wenn Sie Ihre Hintergrundaufgabe registrieren, können Sie mit SystemConditionType eine oder mehrere Bedingungen angeben.You can specify one or more of the conditions specified by SystemConditionType when registering your background task. Die Bedingung wird nach dem Auslösen des Auslösers geprüft.The condition will be checked after the trigger has been fired. Die Hintergrundaufgabe wird dann in die Warteschlange eingereiht, aber Sie wird erst ausgeführt, wenn alle erforderlichen Bedingungen erfüllt sind.The background task will then be queued, but it will not run until all the required conditions are satisfied.

Durch das Einfügen von Bedingungen für Hintergrundaufgaben werden Akku Lebensdauer und CPU gespart, indem die Ausführung von Tasks unnötig verhindert wirdPutting conditions on background tasks saves battery life and CPU by preventing tasks from running unnecessarily. Wenn Ihre Hintergrundaufgabe z. B. nach einem Timer ausgeführt wird und eine Internetverbindung benötigt, fügen Sie die InternetAvailable-Bedingung zum TaskBuilder hinzu, bevor Sie die Aufgabe registrieren.For example, if your background task runs on a timer and requires Internet connectivity, add the InternetAvailable condition to the TaskBuilder before registering the task. So wird verhindert, dass die Aufgabe unnötig Systemressourcen nutzt und Akkulaufzeit beansprucht, da nur die Hintergrundaufgabe ausgeführt wird, wenn der Timer abgelaufen und das Internet verfügbar ist.This will help prevent the task from using system resources and battery life unnecessarily by only running the background task when the timer has elapsed and the Internet is available.

Es ist auch möglich, mehrere Bedingungen zu kombinieren, indem Sie addcondition mehrmals auf demselben Task Builderaufrufen.It is also possible to combine multiple conditions by calling AddCondition multiple times on the same TaskBuilder. Achten Sie darauf, keine in Konflikt stehenden Bedingungen wie UserPresent und UserNotPresent hinzuzufügen.Take care not to add conflicting conditions, such as UserPresent and UserNotPresent.

Erstellen eines SystemCondition-ObjektsCreate a SystemCondition object

In diesem Thema wird davon ausgegangen, dass Sie bereits einen Hintergrund Task mit Ihrer APP verknüpft haben und dass Ihre APP bereits Code enthält, der ein backgroundtaskbuilder -Objekt mit dem Namen " taskbuilder" erstellt.This topic assumes that you have a background task already associated with your app, and that your app already includes code that creates a BackgroundTaskBuilder object named taskBuilder. Wenn Sie zuerst eine Hintergrundaufgabe erstellen müssen, lesen Sie Erstellen und Registrieren einer Hintergrundaufgabe innerhalb von Prozessen oder Erstellen und Registrieren einer Hintergrundaufgabe außerhalb von Prozessen.See Create and register an in-process background task or Create and register an out-of-process background task if you need to create a background task first.

Dieses Thema gilt für Hintergrundaufgaben, die in einem Prozess außerhalb von Prozessen ausgeführt werden, sowie für solche, die im gleichen Prozess wie die Vordergrund-App ausgeführt werden.This topic applies to background tasks that run out-of-process as well as those that run in the same process as the foreground app.

Bevor Sie die Bedingung hinzufügen, erstellen Sie ein systemcondition -Objekt, das die Bedingung darstellt, die für die Durchführung einer Hintergrundaufgabe wirksam sein muss.Before adding the condition, create a SystemCondition object to represent the condition that must be in effect for a background task to run. Geben Sie im Konstruktor die Bedingung an, die mit einem systemconditiontype -Enumerationswert erfüllt werden muss.In the constructor, specify the condition that must be met with a SystemConditionType enumeration value.

Der folgende Code erstellt ein systemcondition -Objekt, das die interverschachteltavailable -Bedingung angibt:The following code creates a SystemCondition object that specifies the InternetAvailable condition:

SystemCondition internetCondition = new SystemCondition(SystemConditionType.InternetAvailable);
Windows::ApplicationModel::Background::SystemCondition internetCondition{
    Windows::ApplicationModel::Background::SystemConditionType::InternetAvailable };
SystemCondition ^ internetCondition = ref new SystemCondition(SystemConditionType::InternetAvailable);

Hinzufügen des SystemCondition-Objekts zur HintergrundaufgabeAdd the SystemCondition object to your background task

Um die Bedingung hinzuzufügen, rufen Sie die AddCondition-Methode für das BackgroundTaskBuilder-Objekt auf, und übergeben Sie das SystemCondition-Objekt an die Methode.To add the condition, call the AddCondition method on the BackgroundTaskBuilder object, and pass it the SystemCondition object.

Der folgende Code verwendet taskbuilder , um die interverschachteltavailable -Bedingung hinzuzufügen.The following code uses taskBuilder to add the InternetAvailable condition.

taskBuilder.AddCondition(internetCondition);
taskBuilder.AddCondition(internetCondition);
taskBuilder->AddCondition(internetCondition);

Registrieren Sie die Hintergrundaufgabe.Register your background task

Nun können Sie Ihre Hintergrundaufgabe mit der Register -Methode registrieren, und die Hintergrundaufgabe wird erst gestartet, wenn die angegebene Bedingung erfüllt ist.Now you can register your background task with the Register method, and the background task will not start until the specified condition is met.

Der folgende Code registriert die Aufgabe und speichert das resultierende BackgroundTaskRegistration-Objekt:The following code registers the task and stores the resulting BackgroundTaskRegistration object:

BackgroundTaskRegistration task = taskBuilder.Register();
Windows::ApplicationModel::Background::BackgroundTaskRegistration task{ recurringTaskBuilder.Register() };
BackgroundTaskRegistration ^ task = taskBuilder->Register();

Hinweis

Parameter für die Registrierung von Hintergrundaufgaben werden zum Zeitpunkt der Registrierung überprüft.Background task registration parameters are validated at the time of registration. Bei ungültigen Registrierungsparametern wird ein Fehler zurückgegeben.An error is returned if any of the registration parameters are invalid. Stellen Sie sicher, dass Ihre App problemlos mit Szenarien ohne erfolgreiche Registrierung von Hintergrundaufgaben zurechtkommt. Andernfalls stürzt die App unter Umständen ab, wenn sie so konzipiert ist, dass nach dem Versuch, eine Aufgabe zu registrieren, ein gültiges Registrierungsobjekt vorhanden sein muss.Ensure that your app gracefully handles scenarios where background task registration fails - if instead your app depends on having a valid registration object after attempting to register a task, it may crash.

Einfügen mehrerer Bedingungen für die HintergrundaufgabePlace multiple conditions on your background task

Zum Hinzufügen mehrerer Bedingungen ruft Ihre App die AddCondition -Methode mehrmals auf.To add multiple conditions, your app makes multiple calls to the AddCondition method. Diese Aufrufe müssen stattfinden, bevor die Aufgabenregistrierung wirksam wird.These calls must come before task registration to be effective.

Hinweis

Achten Sie darauf, dass Sie einer Hintergrundaufgabe keine Konflikt verursachenden Bedingungen hinzufügen.Take care not to add conflicting conditions to a background task.

Der folgende Code Ausschnitt zeigt mehrere Bedingungen im Zusammenhang mit dem Erstellen und Registrieren eines Hintergrund Tasks.The following snippet shows multiple conditions in the context of creating and registering a background task.

// Set up the background task.
TimeTrigger hourlyTrigger = new TimeTrigger(60, false);

var recurringTaskBuilder = new BackgroundTaskBuilder();

recurringTaskBuilder.Name           = "Hourly background task";
recurringTaskBuilder.TaskEntryPoint = "Tasks.ExampleBackgroundTaskClass";
recurringTaskBuilder.SetTrigger(hourlyTrigger);

// Begin adding conditions.
SystemCondition userCondition     = new SystemCondition(SystemConditionType.UserPresent);
SystemCondition internetCondition = new SystemCondition(SystemConditionType.InternetAvailable);

recurringTaskBuilder.AddCondition(userCondition);
recurringTaskBuilder.AddCondition(internetCondition);

// Done adding conditions, now register the background task.

BackgroundTaskRegistration task = recurringTaskBuilder.Register();
// Set up the background task.
Windows::ApplicationModel::Background::TimeTrigger hourlyTrigger{ 60, false };

Windows::ApplicationModel::Background::BackgroundTaskBuilder recurringTaskBuilder;

recurringTaskBuilder.Name(L"Hourly background task");
recurringTaskBuilder.TaskEntryPoint(L"Tasks.ExampleBackgroundTaskClass");
recurringTaskBuilder.SetTrigger(hourlyTrigger);

// Begin adding conditions.
Windows::ApplicationModel::Background::SystemCondition userCondition{
    Windows::ApplicationModel::Background::SystemConditionType::UserPresent };
Windows::ApplicationModel::Background::SystemCondition internetCondition{
    Windows::ApplicationModel::Background::SystemConditionType::InternetAvailable };

recurringTaskBuilder.AddCondition(userCondition);
recurringTaskBuilder.AddCondition(internetCondition);

// Done adding conditions, now register the background task.
Windows::ApplicationModel::Background::BackgroundTaskRegistration task{ recurringTaskBuilder.Register() };
// Set up the background task.
TimeTrigger ^ hourlyTrigger = ref new TimeTrigger(60, false);

auto recurringTaskBuilder = ref new BackgroundTaskBuilder();

recurringTaskBuilder->Name           = "Hourly background task";
recurringTaskBuilder->TaskEntryPoint = "Tasks.ExampleBackgroundTaskClass";
recurringTaskBuilder->SetTrigger(hourlyTrigger);

// Begin adding conditions.
SystemCondition ^ userCondition     = ref new SystemCondition(SystemConditionType::UserPresent);
SystemCondition ^ internetCondition = ref new SystemCondition(SystemConditionType::InternetAvailable);

recurringTaskBuilder->AddCondition(userCondition);
recurringTaskBuilder->AddCondition(internetCondition);

// Done adding conditions, now register the background task.
BackgroundTaskRegistration ^ task = recurringTaskBuilder->Register();

BemerkungenRemarks

Hinweis

Wählen Sie Bedingungen für Ihre Hintergrundaufgabe aus, sodass Sie nur bei Bedarf ausgeführt wird und nicht ausgeführt werden kann.Choose conditions for your background task so that it only runs when it's needed, and doesn't run when it shouldn't. Unter SystemConditionType finden Sie Beschreibungen der verschiedenen Bedingungen für Hintergrundaufgaben.See SystemConditionType for descriptions of the different background task conditions.