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

重要な APIImportant APIs

ほとんどのバックグラウンド タスクを安全に登録できる再利用可能な関数の作成方法について説明します。Learn how to create a function that can be re-used to safely register most background tasks.

このトピックは、インプロセスのバックグラウンド タスクとアウトプロセスのバックグラウンド タスクの両方に適用されます。This topic is applicable to both in-process background tasks and out-of-process background tasks. このトピックの説明では、登録する必要があるバックグラウンド タスクが既に存在すると想定します。This topic assumes that you already have a background task that needs to be registered. (バックグラウンド タスクの作成方法について詳しくは、「Create and register a background task that runs out-of-process (アウトプロセスで実行されるバックグラウンド タスクの作成と登録)」または「Create and register an in-process background task (インプロセスのバックグラウンド タスクの作成と登録)」をご覧ください)。(See Create and register a background task that runs out-of-process or Create and register an in-process background task for information about how to write a background task).

このトピックは、バックグラウンド タスクを登録するユーティリティ関数の作り方を順に説明します。This topic walks through a utility function that registers background tasks. このユーティリティ関数は、二重登録による問題を防ぐために、同じタスクが登録されていないかどうかをチェックしたうえでタスクを登録します。バックグラウンド タスクにシステムの条件を適用することができます。This utility function checks for existing registrations first before registering the task multiple times to avoid problems with multiple registrations, and it can apply a system condition to the background task. ここで紹介しているユーティリティ関数は、それ自体で完結した実用的なコード例となっています。The walkthrough includes a complete, working example of this utility function.

注:Note  

ユニバーサル Windows アプリは、どの種類のバックグラウンド トリガーを登録する場合でも、先に RequestAccessAsync を呼び出す必要があります。Universal Windows 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, you must call RemoveAccess and then call RequestAccessAsync when your app launches after being updated. 詳しくは、「バックグラウンド タスクのガイドライン」をご覧ください。For more information, see Guidelines for background tasks.

メソッドのシグニチャと戻り値の型の定義Define the method signature and return type

このメソッドは、タスクのエントリ ポイント、タスク名、構築済みのバックグラウンド タスク トリガーのほか、(必要に応じて) バックグラウンド タスクの SystemCondition を引数として受け取ります。This method takes in the task entry point, task name, a pre-constructed background task trigger, and (optionally) a SystemCondition for the background task. このメソッドは、BackgroundTaskRegistration オブジェクトを返します。This method returns a BackgroundTaskRegistration object.

重要

taskEntryPoint -このする必要があります名前空間の名前として構築するバック グラウンド タスクをアウト プロセスで実行されるの '.'、およびバック グラウンド クラスを含むクラスの名前。taskEntryPoint - for background tasks that run in out of process, this must be constructed as the namespace name, '.', and the name of the class containing your background class. この文字列では、大文字と小文字を区別します。The string is case-sensitive. たとえば、名前空間 "MyBackgroundTasks" と、バックグラウンド クラス コードを含むクラス "BackgroundTask1" がある場合、taskEntryPoint 用の文字列は "MyBackgroundTasks.BackgroundTask1" となります。For example, if you had a namespace "MyBackgroundTasks" and a class "BackgroundTask1" that contained your background class code, the string for taskEntryPoint would be "MyBackgroundTasks.BackgroundTask1". バックグラウンド タスクをアプリと同じプロセスで実行する (インプロセスのバックグラウンド タスク) 場合、taskEntryPoint を設定する必要はありません。If your background task runs in the same process as your app (i.e. a in-process background task) taskEntryPoint should not be set.

public static BackgroundTaskRegistration RegisterBackgroundTask(
                                                string taskEntryPoint,
                                                string name,
                                                IBackgroundTrigger trigger,
                                                IBackgroundCondition condition)
{
    
    // We'll add code to this function in subsequent steps.

}
BackgroundTaskRegistration^ MainPage::RegisterBackgroundTask(
                                             Platform::String ^ taskEntryPoint,
                                             Platform::String ^ taskName,
                                             IBackgroundTrigger ^ trigger,
                                             IBackgroundCondition ^ condition)
{
    
    // We'll add code to this function in subsequent steps.

}

登録の重複確認Check for existing registrations

既に登録されたタスクかどうかを確認します。Check whether the task is already registered. 同じタスクが二重に登録されると、1 回のトリガーにつきタスクが複数回実行され、CPU が無駄に消費されるばかりか、予期しない動作を招くこともあるため、この確認は重要です。It's important to check this because if a task is registered multiple times, it will run more than once whenever it’s triggered; this can use excess CPU and may cause unexpected behavior.

同じタスクが登録されているかどうかは、BackgroundTaskRegistration.AllTasks プロパティを照会し、返された結果を反復処理することで確認できます。You can check for existing registrations by querying the BackgroundTaskRegistration.AllTasks property and iterating on the result. 各インスタンスの名前を調べ、登録しようとしているタスクの名前と一致した場合、ループを抜けて、フラグ変数を設定します。このフラグに応じたコード パスが次のステップで選択されます。Check the name of each instance – if it matches the name of the task you’re registering, then break out of the loop and set a flag variable so that your code can choose a different path in the next step.

  アプリに固有のバック グラウンド タスクの名前を使用します。Note  Use background task names that are unique to your app. 各バックグラウンド タスクには一意の名前が付いている必要があります。Ensure each background task has a unique name.

次のコードは、最後の手順で作成した SystemTrigger を使ってバックグラウンド タスクを登録します。The following code registers a background task using the SystemTrigger we created in the last step:

public static BackgroundTaskRegistration RegisterBackgroundTask(
                                                string taskEntryPoint,
                                                string name,
                                                IBackgroundTrigger trigger,
                                                IBackgroundCondition condition)
{
    //
    // Check for existing registrations of this background task.
    //

    foreach (var cur in BackgroundTaskRegistration.AllTasks)
    {

        if (cur.Value.Name == name)
        {
            //
            // The task is already registered.
            //

            return (BackgroundTaskRegistration)(cur.Value);
        }
    }
    
    // We'll register the task in the next step.
}
BackgroundTaskRegistration^ MainPage::RegisterBackgroundTask(
                                             Platform::String ^ taskEntryPoint,
                                             Platform::String ^ taskName,
                                             IBackgroundTrigger ^ trigger,
                                             IBackgroundCondition ^ condition)
{
    //
    // Check for existing registrations of this background task.
    //
    
    auto iter   = BackgroundTaskRegistration::AllTasks->First();
    auto hascur = iter->HasCurrent;
    
    while (hascur)
    {
        auto cur = iter->Current->Value;
        
        if(cur->Name == name)
        {
            //
            // The task is registered.
            //
            
            return (BackgroundTaskRegistration ^)(cur);
        }
        
        hascur = iter->MoveNext();
    }
    
    // We'll register the task in the next step.
}

バックグラウンド タスクを登録する (または既に登録されているタスクを返す)Register the background task (or return the existing registration)

同じバックグラウンド タスクが既に登録されているかどうかを確認します。Check to see if the task was found in the list of existing background task registrations. 登録されている場合は、そのタスクのインスタンスを返します。If so, return that instance of the task.

登録されていない場合は、新しい BackgroundTaskBuilder オブジェクトを使ってタスクを登録します。Then, register the task using a new BackgroundTaskBuilder object. このコードは、condition パラメーターが null かどうかを確認し、null でない場合は、その condition を登録オブジェクトに追加します。This code should check whether the condition parameter is null, and if not, add the condition to the registration object. 戻り値は、BackgroundTaskBuilder.Register メソッドから返された BackgroundTaskRegistration です。Return the BackgroundTaskRegistration returned by the BackgroundTaskBuilder.Register method.

  バック グラウンド タスクの登録パラメーターは、登録時に検証されます。Note  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. アプリと同じプロセスで実行されるバックグラウンド タスクを登録する場合、String.Empty または nulltaskEntryPoint パラメーターに送信します。Note If you are registering a background task that runs in the same process as your app, send String.Empty or null for the taskEntryPoint parameter.

次の例には、既にあるタスクを返すか、バックグラウンド タスクを登録するコードが追加されています。また、システムの条件 (省略可能) が指定された場合の処理も追加されています。The following example either returns the existing task, or adds code that registers the background task (including the optional system condition if present):

public static BackgroundTaskRegistration RegisterBackgroundTask(
                                                string taskEntryPoint,
                                                string name,
                                                IBackgroundTrigger trigger,
                                                IBackgroundCondition condition)
{
    //
    // Check for existing registrations of this background task.
    //

    foreach (var cur in BackgroundTaskRegistration.AllTasks)
    {

        if (cur.Value.Name == taskName)
        {
            //
            // The task is already registered.
            //

            return (BackgroundTaskRegistration)(cur.Value);
        }
    }

    //
    // Register the background task.
    //

    var builder = new BackgroundTaskBuilder();

    builder.Name = name;

    // in-process background tasks don't set TaskEntryPoint
    if ( taskEntryPoint != null && taskEntryPoint != String.Empty)
    {
        builder.TaskEntryPoint = taskEntryPoint;
    }
    builder.SetTrigger(trigger);

    if (condition != null)
    {
        builder.AddCondition(condition);
    }

    BackgroundTaskRegistration task = builder.Register();

    return task;
}
BackgroundTaskRegistration^ MainPage::RegisterBackgroundTask(
                                             Platform::String ^ taskEntryPoint,
                                             Platform::String ^ taskName,
                                             IBackgroundTrigger ^ trigger,
                                             IBackgroundCondition ^ condition)
{

    //
    // Check for existing registrations of this background task.
    //

    auto iter   = BackgroundTaskRegistration::AllTasks->First();
    auto hascur = iter->HasCurrent;

    while (hascur)
    {
        auto cur = iter->Current->Value;

        if(cur->Name == name)
        {
            //
            // The task is registered.
            //

            return (BackgroundTaskRegistration ^)(cur);
        }

        hascur = iter->MoveNext();
    }

    //
    // Register the background task.
    //

    auto builder = ref new BackgroundTaskBuilder();

    builder->Name = name;
    builder->TaskEntryPoint = taskEntryPoint;
    builder->SetTrigger(trigger);

    if (condition != nullptr) {
        
        builder->AddCondition(condition);
    }

    BackgroundTaskRegistration ^ task = builder->Register();

    return task;
}

バックグラウンド タスク登録ユーティリティ関数の完成Complete background task registration utility function

この例は、バックグラウンド タスク登録ユーティリティ関数全体を示しています。This example shows the completed background task registration function. ネットワーク関連のバックグラウンド タスクを除くほとんどのバックグラウンド タスクは、この関数を使って登録できます。This function can be used to register most background tasks, with the exception of networking background tasks.

//
// Register a background task with the specified taskEntryPoint, name, trigger,
// and condition (optional).
//
// taskEntryPoint: Task entry point for the background task.
// taskName: A name for the background task.
// trigger: The trigger for the background task.
// condition: Optional parameter. A conditional event that must be true for the task to fire.
//
public static BackgroundTaskRegistration RegisterBackgroundTask(string taskEntryPoint,
                                                                string taskName,
                                                                IBackgroundTrigger trigger,
                                                                IBackgroundCondition condition)
{
    //
    // Check for existing registrations of this background task.
    //

    foreach (var cur in BackgroundTaskRegistration.AllTasks)
    {

        if (cur.Value.Name == taskName)
        {
            //
            // The task is already registered.
            //

            return (BackgroundTaskRegistration)(cur.Value);
        }
    }

    //
    // Register the background task.
    //

    var builder = new BackgroundTaskBuilder();

    builder.Name = taskName;
    builder.TaskEntryPoint = taskEntryPoint;
    builder.SetTrigger(trigger);

    if (condition != null)
    {

        builder.AddCondition(condition);
    }

    BackgroundTaskRegistration task = builder.Register();

    return task;
}
//
// Register a background task with the specified taskEntryPoint, name, trigger,
// and condition (optional).
//
// taskEntryPoint: Task entry point for the background task.
// taskName: A name for the background task.
// trigger: The trigger for the background task.
// condition: Optional parameter. A conditional event that must be true for the task to fire.
//
BackgroundTaskRegistration^ MainPage::RegisterBackgroundTask(Platform::String ^ taskEntryPoint,
                                                             Platform::String ^ taskName,
                                                             IBackgroundTrigger ^ trigger,
                                                             IBackgroundCondition ^ condition)
{

    //
    // Check for existing registrations of this background task.
    //

    auto iter   = BackgroundTaskRegistration::AllTasks->First();
    auto hascur = iter->HasCurrent;

    while (hascur)
    {
        auto cur = iter->Current->Value;

        if(cur->Name == name)
        {
            //
            // The task is registered.
            //

            return (BackgroundTaskRegistration ^)(cur);
        }

        hascur = iter->MoveNext();
    }


    //
    // Register the background task.
    //

    auto builder = ref new BackgroundTaskBuilder();

    builder->Name = name;
    builder->TaskEntryPoint = taskEntryPoint;
    builder->SetTrigger(trigger);

    if (condition != nullptr) {

        builder->AddCondition(condition);
    }

    BackgroundTaskRegistration ^ task = builder->Register();

    return task;
}