Задание условий выполнения фоновой задачиSet conditions for running a background task

Важные APIImportant APIs

Узнайте, как задать условия, которые управляют запуском выполнения фоновой задачи.Learn how to set conditions that control when your background task will run.

Иногда для успешного выполнения фоновых задач требуется соблюдение определенных условий.Sometimes, background tasks require certain conditions to be met for the background task to succeed. При регистрации фоновой задачи можно указать одно или несколько условий, определяемых типом SystemConditionType.You can specify one or more of the conditions specified by SystemConditionType when registering your background task. Условие будет проверяться после срабатывания триггера.The condition will be checked after the trigger has been fired. Фоновая задача затем помещается в очередь и выполняется только при соблюдении всех требуемых условий.The background task will then be queued, but it will not run until all the required conditions are satisfied.

Настройка условий для фоновых задач продлевает время работы от батареи и сокращает нагрузку ЦП, так как препятствует запуску задач без необходимости.Putting conditions on background tasks saves battery life and CPU by preventing tasks from running unnecessarily. Например, если фоновая задача запускается по таймеру и требует подключения к Интернету, перед регистрацией задачи добавьте условие InternetAvailable в TaskBuilder.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. Это помогает избежать ненужного использования системных ресурсов или заряда батареи, запуская выполнение фоновой задачи только при срабатывании таймера и наличии доступа к Интернету.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.

Можно также объединить несколько условий, вызвав аддкондитион несколько раз в одном таскбуилдер.It is also possible to combine multiple conditions by calling AddCondition multiple times on the same TaskBuilder. Следите за тем, чтобы не добавить конфликтующие условия, например UserPresent и UserNotPresent.Take care not to add conflicting conditions, such as UserPresent and UserNotPresent.

Создание объекта SystemConditionCreate a SystemCondition object

Для работы с этим разделом вы должны иметь связанную с приложением фоновую задачу, а ваше приложение должно содержать код, который создает объект BackgroundTaskBuilder с именем taskBuilder.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. Если сначала нужно создать фоновую задачу, выполните инструкции из раздела Создание и регистрация фоновой задачи, выполняемой в процессе или Создание и регистрация фоновой задачи, выполняемой вне процесса.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.

Этот раздел применяется к фоновым задачам, которые выполняются вне процесса или в том же процессе, что и приложение переднего плана.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.

Прежде чем добавлять само условие, создайте объект SystemCondition для представления условия, которое должно соблюдаться для запуска задачи.Before adding the condition, create a SystemCondition object to represent the condition that must be in effect for a background task to run. Задайте в конструкторе необходимое для выполнения условие с помощью значения перечисления SystemConditionType.In the constructor, specify the condition that must be met with a SystemConditionType enumeration value.

Следующий код создает объект SystemCondition, указывающий условие InternetAvailable: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);

Добавление объекта SystemCondition в фоновую задачуAdd the SystemCondition object to your background task

Чтобы добавить условие, вызовите метод AddCondition применительно к объекту BackgroundTaskBuilder и передайте его объекту SystemCondition.To add the condition, call the AddCondition method on the BackgroundTaskBuilder object, and pass it the SystemCondition object.

В следующем коде используется taskBuilder для добавления условия InternetAvailable.The following code uses taskBuilder to add the InternetAvailable condition.

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

Регистрация фоновой задачиRegister your background task

Теперь вы можете зарегистрировать свою фоновую задачу с помощью метода Register, при этом фоновая задача запускается только при соблюдении заданного условия.Now you can register your background task with the Register method, and the background task will not start until the specified condition is met.

В следующем коде регистрируется задача и сохраняется полученный в результате объект BackgroundTaskRegistration: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();

Примечание

Параметры регистрации фоновых задач проверяются во время регистрации.Background task registration parameters are validated at the time of registration. Если какие-либо из параметров регистрации недопустимы, возвращается ошибка.An error is returned if any of the registration parameters are invalid. Убедитесь, что ваше приложение корректно обрабатывает сценарии, в которых регистрация фоновой задачи завершается ошибкой. Если работа вашего приложения зависит от наличия допустимого объекта регистрации после попытки регистрации задачи, то оно может дать сбой.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.

Размещение в фоновой задаче нескольких условийPlace multiple conditions on your background task

Чтобы добавить несколько условий, приложение многократно вызывает метод AddCondition .To add multiple conditions, your app makes multiple calls to the AddCondition method. Чтобы быть эффективными, такие вызовы должны предшествовать регистрации задачи.These calls must come before task registration to be effective.

Примечание

Следите за тем, чтобы не добавлять конфликтующие условия в фоновую задачу.Take care not to add conflicting conditions to a background task.

В следующем фрагменте кода показано несколько условий в контексте создания и регистрации фоновой задачи.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();

RemarksRemarks

Примечание

Выберите условия для фоновой задачи так, чтобы она выполнялась только при необходимости и не выполнялась.Choose conditions for your background task so that it only runs when it's needed, and doesn't run when it shouldn't. Обзор различных условий выполнения фоновых задач см. в разделе SystemConditionType.See SystemConditionType for descriptions of the different background task conditions.