设置后台任务的运行条件

重要的 API

了解如何设置控制何时运行后台任务的条件。

有时,后台任务还需要满足某些条件,才可以使后台任务继续进行。 你可以在注册后台任务时指定由 SystemConditionType 指定的一个或多个条件。 引发触发器之后将检查条件。 后台任务将进入队列,但必须先满足所有所需条件才会运行。

对后台任务设置条件可阻止任务不必要地运行,从而节省电池电量和 CPU。 例如,如果你的后台任务在计时器上运行并要求 Internet 连接,请在注册该任务之前将 InternetAvailable 条件添加到 TaskBuilder。 仅当计时器时间过去以及 Internet 可用时运行后台任务,这有助于防止任务不必要地使用系统资源和电池使用时间。

还可以通过在同一 TaskBuilder 上多次调用 AddCondition 组合多个条件。 注意不要添加冲突条件,如 UserPresentUserNotPresent

创建 SystemCondition 对象

本主题假定你的后台任务已与你的应用关联,并且你的应用已包含用于创建名为 taskBuilderBackgroundTaskBuilder 对象的代码 如果需要先创建一个后台任务,请参阅创建和注册进程内后台任务创建和注册进程外后台任务

本主题适用于在进程外运行的后台任务以及在前台应用所在的同一进程中运行的那些后台任务。

添加该条件之前,创建一个代表该条件的 SystemCondition 对象,该对象必须实际用于运行后台任务。 在构造函数中,通过提供一个 SystemConditionType 枚举值指定必须满足的条件。

以下代码创建一个 SystemCondition 对象,该对象将指定 InternetAvailable 条件:

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

向你的后台任务中添加 SystemCondition 对象

若要添加条件,请在 BackgroundTaskBuilder 对象上调用 AddCondition 方法,并向其传递 SystemCondition 对象。

以下代码使用 taskBuilder 添加 InternetAvailable 条件。

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

注册后台任务

现在即可使用 Register 方法注册后台任务,该后台任务必须先满足指定的条件才能启动。

以下代码注册该任务并存储所生成的 BackgroundTaskRegistration 对象:

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

注意

后台任务注册参数在注册时验证。 如果有任何注册参数无效,则会返回一个错误。 确保你的应用能够流畅地处理后台任务注册失败的情况,否则,如果你的应用依赖于在尝试注册任务后具备有效注册对象,则它可能会崩溃。

在后台任务上放置多个条件

若要添加多个条件,你的应用需要多次调用 AddCondition 方法。 任务注册生效之前,必须进行这些调用。

注意

小心不要向后台任务中添加冲突的条件。

以下代码段在创建和注册后台任务的上下文中显示多个条件。

// 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();

注解

注意

为你的后台任务选择条件,以便它仅在需要时运行,不在不应该运行时运行。 有关不同后台任务条件的描述,请参阅 SystemConditionType