バックグラウンド タスクを実行するための条件の設定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 で指定される条件を 1 つ以上指定することができます。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.

バックグラウンド タスクに条件を設定すると、タスクが不必要に実行されなくなるため、バッテリー残量と CPU 実行時間が節約できます。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.

また、同じTaskbuilderaddconditionを複数回呼び出すことによって、複数の条件を組み合わせることもできます。It is also possible to combine multiple conditions by calling AddCondition multiple times on the same TaskBuilder. UserPresentUserNotPresent など競合する条件を追加しないように注意してください。Take care not to add conflicting conditions, such as UserPresent and UserNotPresent.

SystemCondition オブジェクトを作るCreate a SystemCondition object

ここでは、既にバックグラウンド タスクがアプリと関連付けられており、アプリでは、taskBuilder という BackgroundTaskBuilder オブジェクトを作るためのコードが記述済みであることを前提とします。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.

次のコードでは、InternetAvailable 条件を指定する SystemCondition オブジェクトを作成します。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

条件を追加するには、BackgroundTaskBuilder オブジェクトで AddCondition メソッドを呼び出して、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

複数の条件を追加するには、アプリから メソッドを複数回呼び出します。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();

注釈Remarks

注意

必要なときにのみ実行されるようにバックグラウンドタスクの条件を選択します。そうしないと、実行されません。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.