バックグラウンド タスクの登録のグループ化Group background task registration

重要な APIImportant APIs

BackgroundTaskRegistrationGroup クラスBackgroundTaskRegistrationGroup class

バックグラウンド タスクは、グループに登録できるようになりました。このグループは、論理的な名前空間と考えることができます。Background tasks can now be registered in a group, which you can think of as a logical namespace. このように分離することで、アプリの異なるコンポーネントや異なるライブラリが相互にバックグラウンド タスク登録に干渉しないようにできます。This isolation helps ensure that different components of an app, or different libraries, don’t interfere with each other’s background task registration.

アプリと、アプリで使用するフレームワーク (またはライブラリ) がバックグラウンド タスクを同じ名前で登録する場合、フレームワークのバックグラウンド タスク登録がアプリによって誤って削除される可能性があります。When an app and the framework (or library) it uses registers a background task with the same name, the app could inadvertently remove the framework's background task registrations. また、アプリの作成者も誤ってフレームワークとライブラリのバックグラウンド タスク登録を削除する可能性があります。アプリの作成者は、BackgroundTaskRegistration.AllTasks を使用して登録されているすべてのバックグラウンド タスクを解除できるからです。App authors could also accidently remove framework and library background task registrations because they could unregister all registered background tasks by using BackgroundTaskRegistration.AllTasks. グループを使用すると、バックグラウンド タスク登録を分離できるため、このようなことは発生しません。With groups, you can isolate your background task registrations so this doesn't happen.

グループの機能Features of groups

  • グループは、GUID で一意に識別できます。Groups can be uniquely identified by a GUID. また、デバッグ中に読みやすい、関連するフレンドリ名文字列を設定できます。They can also have an associated friendly name string which is easier to read while debugging.
  • 複数のバックグラウンド タスクをグループに登録できます。Multiple background tasks can be registered in a group.
  • グループに登録されているバックグラウンド タスクは、BackgroundTaskRegistration.AllTasks には表示されません。Background tasks registered in a group won't appear in BackgroundTaskRegistration.AllTasks. そのため、現在 BackgroundTaskRegistration.AllTasks を使用してタスクの登録を解除しているアプリでは、グループに登録したバックグラウンド タスクを誤って登録解除することはありません。Thus apps that currently use BackgroundTaskRegistration.AllTasks to unregister their tasks won't inadvertently unregister background tasks registered in a group. グループの一部として登録されているすべてのバックグラウンドトリガーの登録を解除する方法については 、以下の「グループのバックグラウンドタスクの登録解除 」を参照してください。See Unregister background tasks in a group below to see how to unregister all background triggers that have been registered as part of a group.
  • 各バックグラウンド タスク登録では、関連付けられているグループを判断するための Group プロパティが設定されます。Each Background Task Registration will have a Group property to determine which group it is associated with.
  • プロセス内のバックグラウンドタスクをグループに登録すると、アプリケーションではなく、backgroundactivation イベントを使用してアクティブ化が行われます。Registering In-Process background tasks with a group will cause the activation to go through BackgroundTaskRegistrationGroup.BackgroundActivated event instead of Application.OnBackgroundActivated.

グループにバックグラウンド タスクを登録するRegister a background task in a group

以下では、バックグラウンド タスクをグループの一部として登録する方法を示しています (この例では、タイム ゾーンの変更によってタスクがトリガーされます)。The following shows how to register a background task (triggered by a time zone change, in this example) as part of a group.

private const string groupFriendlyName = "myGroup";
private const string groupId = "3F2504E0-4F89-41D3-9A0C-0305E82C3301";
private const string myTaskName = "My Background Trigger";

public static void RegisterBackgroundTaskInGroup()
{
   BackgroundTaskRegistrationGroup group = BackgroundTaskRegistration.GetTaskGroup(groupId);
   bool isTaskRegistered = false;

   // See if this task already belongs to a group
   if (group != null)
   {
       foreach (var taskKeyValue in group.AllTasks)
       {
           if (taskKeyValue.Value.Name == myTaskName)
           {
               isTaskRegistered = true;
               break;
           }
       }
   }

   // If the background task is not in a group, register it
   if (!isTaskRegistered)
   {
       if (group == null)
       {
           group = new BackgroundTaskRegistrationGroup(groupId, groupFriendlyName);
       }

       var builder = new BackgroundTaskBuilder();
       builder.Name = myTaskName;
       builder.TaskGroup = group; // we specify the group, here
       builder.SetTrigger(new SystemTrigger(SystemTriggerType.TimeZoneChange, false));

       // Because builder.TaskEntryPoint is not specified, OnBackgroundActivated() will be raised when the background task is triggered
       BackgroundTaskRegistration task = builder.Register();
   }
}

グループのバックグラウンド タスクの登録を解除するUnregister background tasks in a group

以下では、グループの一部として登録されたバックグラウンド タスクの登録を解除する方法を示しています。The following shows how to unregister background tasks that were registered as part of a group. グループに登録されているバックグラウンド タスクは BackgroundTaskRegistration.AllTasks に表示されないため、グループを反復処理して、各グループに登録されたバックグラウンド タスクを見つけ、登録を解除する必要があります。Because background tasks registered in a group don't appear in BackgroundTaskRegistration.AllTasks, you must iterate through the groups, find the background tasks registered to each group, and unregister them.

private static void UnRegisterAllTasks()
{
    // Unregister tasks that are part of a group
    foreach (var groupKeyValue in BackgroundTaskRegistration.AllTaskGroups)
    {
        foreach (var groupedTask in groupKeyValue.Value.AllTasks)
        {
            groupedTask.Value.Unregister(true); // passing true to cancel currently running instances of this background task
        }
    }

    // Unregister tasks that aren't part of a group
    foreach(var taskKeyValue in BackgroundTaskRegistration.AllTasks)
    {
        taskKeyValue.Value.Unregister(true); // passing true to cancel currently running instances of this background task
    }
}

永続イベントを登録するRegister Persistent Events

インプロセス バックグラウンド タスクと一緒にバックグラウンド タスク登録グループを使用している場合、バックグラウンド アクティブ化は、Application オブジェクトと CoreApplication オブジェクトのいずれでもなく、グループのイベントに伝達されます。When using Background Task Registration Groups with in-process background tasks, the background activations are directed towards the group's event instead of the one on the Application or CoreApplication object. これにより、Application オブジェクトにすべてのアクティブ化コード パスを配置せずに、アプリ内の複数のコンポーネントでアクティブ化を処理できるようになります。This enables multiple components within your app to handle the activation rather than place all activation code paths in the Application object. 以下では、グループのバックグラウンド アクティブ化イベントの登録方法を示しています。The following shows how to register for the group's background activated event. まず、BackgroundTaskRegistration.GetTaskGroup を確認して、グループが既に登録されているかどうかを判断します。First check BackgroundTaskRegistration.GetTaskGroup to determine if the group has already been registered. 登録されていない場合、指定の ID とフレンドリ名で新しいグループを作成します。If not then create a new group with your id and friendly name. その後、グループの BackgroundActivated イベントにイベント ハンドラーを登録します。Then register an event handler to the BackgroundActivated event on the group.

void RegisterPersistentEvent()
{
    var group = BackgroundTaskRegistration.GetTaskGroup(groupId);
    if (group == null)
    {
        group = new BackgroundTaskRegistrationGroup(groupId, groupFriendlyName);
    }

    group.BackgroundActivated += MyEventHandler;
}