メンテナンス トリガーの使用Use a maintenance trigger

重要な APIImportant APIs

デバイスが接続されているときに、MaintenanceTrigger クラスを使って軽量のコードをバックグラウンドで実行する方法について説明します。Learn how to use the MaintenanceTrigger class to run lightweight code in the background while the device is plugged in.

メンテナンス トリガー オブジェクトを作るCreate a maintenance trigger object

この例は、デバイスが接続されているときにアプリを拡張するためにバックグラウンドで実行できる軽量のコードがあることを前提にしています。This example assumes that you have lightweight code you can run in the background to enhance your app while the device is plugged in. ここでは主に、SystemTrigger に似た MaintenanceTrigger について扱います。This topic focuses on the MaintenanceTrigger, which is similar to SystemTrigger.

バックグラウンド タスク クラスの作成について詳しくは、「インプロセス バックグラウンド タスクの作成と登録」または「アウトプロセス バックグラウンド タスクの作成と登録」をご覧ください。More information on writing a background task class is available in Create and register an in-process background task or Create and register an out-of-process background task.

新しい MaintenanceTrigger オブジェクトを作成します。Create a new MaintenanceTrigger object. 2 つ目のパラメーター (OneShot) では、メンテナンス タスクを一度だけ実行するか、定期的に実行を続けるかを指定します。The second parameter, OneShot, specifies whether the maintenance task will run only once or continue to run periodically. OneShot を true に設定する場合は、1 つ目のパラメーター (FreshnessTime) に、バックグラウンド タスクをスケジュールするまで待機する時間 (分単位) を指定します。If OneShot is set to true, the first parameter (FreshnessTime) specifies the number of minutes to wait before scheduling the background task. OneShot を false に設定する場合は、FreshnessTime でバックグラウンド タスクを実行する間隔を指定します。If OneShot is set to false, FreshnessTime specifies how often the background task will run.

注意

場合FreshnessTimeがバック グラウンド タスクの登録を試みているときに例外がスローに未満、15 分に設定します。If FreshnessTime is set to less than 15 minutes, an exception is thrown when attempting to register the background task.

このコード例では、1 時間に 1 回実行するトリガーを作成します。This example code creates a trigger that runs once an hour.

uint waitIntervalMinutes = 60;
MaintenanceTrigger taskTrigger = new MaintenanceTrigger(waitIntervalMinutes, false);
uint32_t waitIntervalMinutes{ 60 };
Windows::ApplicationModel::Background::MaintenanceTrigger taskTrigger{ waitIntervalMinutes, false };
unsigned int waitIntervalMinutes = 60;
MaintenanceTrigger ^ taskTrigger = ref new MaintenanceTrigger(waitIntervalMinutes, false);

(省略可能) 条件の追加(Optional) Add a condition

  • いつタスクを実行するかを制御するバックグラウンド タスクの条件を必要に応じて作成します。If necessary, create a background task condition to control when the task runs. 条件を指定すると、条件が満たされるまではバックグラウンド タスクが実行されないようにすることができます。詳しくは「バックグラウンド タスクを実行するための条件の設定」をご覧ください。A condition prevents your background task from running until the condition is met - for more information, see Set conditions for running a background task

次の例では、インターネットが利用できる場合 (またはインターネットが利用できるようになった場合) にメンテナンスが実行されるように、条件を InternetAvailable に設定します。In this example, the condition is set to InternetAvailable so that maintenance runs when the Internet is available (or when it becomes available). 指定できるバックグラウンド タスク条件の一覧については、「SystemConditionType」をご覧ください。For a list of possible background task conditions, see SystemConditionType.

次のコードでは、メンテナンス タスク ビルダーに条件を追加します。The following code adds a condition to the maintenance task builder:

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

バックグラウンド タスクの登録Register the background task

  • バックグラウンド タスクの登録関数を呼び出してバックグラウンド タスクを登録します。Register the background task by calling your background task registration function. バックグラウンド タスクの登録について詳しくは、「バックグラウンド タスクの登録」をご覧ください。For more information on registering background tasks, see Register a background task.

次のコードでは、メンテナンス タスクを登録します。The following code registers the maintenance task. entryPoint と指定しているので、バックグラウンド タスクとアプリを異なるプロセスで実行するように想定されていることに注意してください。Note that it assumes your background task runs in a separate process from your app because it specifies entryPoint. バックグラウンド タスクとアプリを同じプロセスで実行する場合は、entryPoint を指定しません。If your background task runs in the same process as your app, you do not specify entryPoint.

string entryPoint = "Tasks.ExampleBackgroundTaskClass";
string taskName   = "Maintenance background task example";

BackgroundTaskRegistration task = RegisterBackgroundTask(entryPoint, taskName, taskTrigger, exampleCondition);
std::wstring entryPoint{ L"Tasks.ExampleBackgroundTaskClass" };
std::wstring taskName{ L"Maintenance background task example" };

Windows::ApplicationModel::Background::BackgroundTaskRegistration task{
    RegisterBackgroundTask(entryPoint, taskName, taskTrigger, exampleCondition) };
String ^ entryPoint = "Tasks.ExampleBackgroundTaskClass";
String ^ taskName   = "Maintenance background task example";

BackgroundTaskRegistration ^ task = RegisterBackgroundTask(entryPoint, taskName, taskTrigger, exampleCondition);

注意

デスクトップ以外のすべてのデバイス ファミリでは、デバイスのメモリが少なくなった場合、バックグラウンド タスクが終了することがあります。For all device families except desktop, if the device becomes low on memory, background tasks may be terminated. メモリ不足の例外が検出されないか、検出されてもアプリによって処理されない場合、バックグラウンド タスクは、警告や OnCanceled イベントの発生なしに終了します。If an out of memory exception is not surfaced, or the app does not handle it, then the background task will be terminated without warning and without raising the OnCanceled event. こうすることで、フォアグラウンドのアプリのユーザー エクスペリエンスが保証されます。This helps to ensure the user experience of the app in the foreground. バックグラウンド タスクは、このシナリオを処理できるように設計する必要があります。Your background task should be designed to handle this scenario.

注意

ユニバーサル Windows プラットフォーム アプリを呼び出す必要があります RequestAccessAsync バック グラウンドのトリガーの種類のいずれかを登録する前にします。Universal Windows Platform apps must call RequestAccessAsync before registering any of the background trigger types.

アプリに対する更新プログラムのリリース後にユニバーサル Windows アプリが引き続き適切に実行されるようにするには、更新後にアプリが起動する際に、RemoveAccessRequestAccessAsync の順に呼び出す必要があります。To ensure that your Universal Windows app continues to run properly after you release an update to your app, you must call RemoveAccess and then call RequestAccessAsync when your app launches after being updated. 詳しくは、「バックグラウンド タスクのガイドライン」をご覧ください。For more information, see Guidelines for background tasks.

注意

バックグラウンド タスクの登録パラメーターは登録時に検証されます。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.