取り消されたバックグラウンドタスクの処理

[アーティクル]
07/13/2023

重要な API

取り消し要求を認識し、作業を停止して、固定ストレージを使っているアプリに取り消しを報告するバックグラウンドタスクの作成方法について説明します。

このトピックでは、バックグラウンドタスクのエントリポイントとして使う Run メソッドも含めて、既にバックグラウンドタスククラスが作られていることを前提とします。バックグラウンドタスクの作成方法の概要については、「アウトプロセスバックグラウンドタスクの作成と登録」または「インプロセスバックグラウンドタスクの作成と登録」をご覧ください。条件とトリガーについて詳しくは、「バックグラウンドタスクによるアプリのサポート」をご覧ください。

このトピックは、インプロセスバックグラウンドタスクにも適用されます。しかし、Run メソッドを使う代わりに、OnBackgroundActivated に置き換えます。インプロセスバックグラウンドタスクでは、バックグラウンドタスクがフォアグラウンドアプリと同じプロセスで実行されているため、取り消しを通知するために固定ストレージを使用する必要はありません。アプリの状態を使用して、取り消しを伝えることができます。

OnCanceled メソッドにより、取り消し要求を認識します。

取り消しイベントを処理するメソッドを作ります。

注意

デスクトップ以外のすべてのデバイスファミリでは、デバイスのメモリが少なくなった場合、バックグラウンドタスクが終了することがあります。メモリ不足の例外が検出されないか、アプリによって処理されない場合、バックグラウンドタスクは、警告や OnCanceled イベントの発生なしに終了します。こうすることで、フォアグラウンドのアプリのユーザーエクスペリエンスが保証されます。バックグラウンドタスクは、このシナリオを処理できるように設計する必要があります。

次のように OnCanceled という名前のメソッドを作成します。このメソッドは、バックグラウンドタスクに対して取り消し要求が出されると、Windows ランタイムによって呼び出されるエントリポイントです。

private void OnCanceled(
    IBackgroundTaskInstance sender,
    BackgroundTaskCancellationReason reason)
{
    // TODO: Add code to notify the background task that it is cancelled.
}

void ExampleBackgroundTask::OnCanceled(
    Windows::ApplicationModel::Background::IBackgroundTaskInstance const& taskInstance,
    Windows::ApplicationModel::Background::BackgroundTaskCancellationReason reason)
{
    // TODO: Add code to notify the background task that it is cancelled.
}

void ExampleBackgroundTask::OnCanceled(
    IBackgroundTaskInstance^ taskInstance,
    BackgroundTaskCancellationReason reason)
{
    // TODO: Add code to notify the background task that it is cancelled.
}

バックグラウンドタスククラスに _CancelRequested というフラグ変数を追加します。この変数は、いつ取り消し要求が出されたかを示すために使います。

volatile bool _CancelRequested = false;

private:
    volatile bool m_cancelRequested;

private:
    volatile bool CancelRequested;

手順 1 で作った OnCanceled メソッドで、フラグ変数 _CancelRequested を true に設定します。

完全なバックグラウンドタスクのサンプルOnCanceled メソッドによって、_CancelRequested が true に設定され、役立つデバッグ出力を書き出します。

private void OnCanceled(IBackgroundTaskInstance sender, BackgroundTaskCancellationReason reason)
{
    // Indicate that the background task is canceled.
    _cancelRequested = true;

    Debug.WriteLine("Background " + sender.Task.Name + " Cancel Requested...");
}

void ExampleBackgroundTask::OnCanceled(
    Windows::ApplicationModel::Background::IBackgroundTaskInstance const& taskInstance,
    Windows::ApplicationModel::Background::BackgroundTaskCancellationReason reason)
{
    // Indicate that the background task is canceled.
    m_cancelRequested = true;
}

void ExampleBackgroundTask::OnCanceled(IBackgroundTaskInstance^ taskInstance, BackgroundTaskCancellationReason reason)
{
    // Indicate that the background task is canceled.
    CancelRequested = true;
}

バックグラウンドタスクの Run メソッドでは、処理を開始する前に OnCanceled イベントハンドラーメソッドを登録します。インプロセスバックグラウンドタスクでは、アプリケーションの初期化の一部としてこの登録を実行できます。たとえば、次のコード行を使います。

taskInstance.Canceled += new BackgroundTaskCanceledEventHandler(OnCanceled);

taskInstance.Canceled({ this, &ExampleBackgroundTask::OnCanceled });

taskInstance->Canceled += ref new BackgroundTaskCanceledEventHandler(this, &ExampleBackgroundTask::OnCanceled);

バックグラウンドタスクを終了することによって、取り消しを処理します。

キャンセル要求を受信すると、バックグラウンドの作業を実行しているメソッドは、_cancelRequested が true に設定されたタイミングを認識し、作業を停止して終了する必要があります。インプロセスバックグラウンドタスクの場合、これは OnBackgroundActivated メソッドから戻ることです。アウトプロセスバックグラウンドタスクの場合、これは Run メソッドから戻ることです。

バックグラウンドタスククラスの処理中にフラグ変数を確認するようにコードを変更します。 _cancelRequested が true に設定された時点で、処理を中断します。

バックグラウンドタスクのサンプルによって、バックグラウンドタスクが取り消されたときに、期間タイマーのコールバックが停止するかどうかの確認が行われます。

if ((_cancelRequested == false) && (_progress < 100))
{
    _progress += 10;
    _taskInstance.Progress = _progress;
}
else
{
    _periodicTimer.Cancel();
    // TODO: Record whether the task completed or was cancelled.
}

if (!m_cancelRequested && m_progress < 100)
{
    m_progress += 10;
    m_taskInstance.Progress(m_progress);
}
else
{
    m_periodicTimer.Cancel();
    // TODO: Record whether the task completed or was cancelled.
}

if ((CancelRequested == false) && (Progress < 100))
{
    Progress += 10;
    TaskInstance->Progress = Progress;
}
else
{
    PeriodicTimer->Cancel();
    // TODO: Record whether the task completed or was cancelled.
}

注意

上記のコードサンプルを使用すると、IBackgroundTaskInstance.Progress プロパティを使って、バックグラウンドタスクの進行状況が記録されます。進行状況は、BackgroundTaskProgressEventArgs クラスを使ってアプリに報告されます。

作業が停止したときに、タスクが完了したのか、取り消されたのかを記録するように、Run メソッドを変更します。この手順は、バックグラウンドタスクが取り消されたときにプロセス間で通信する手段が必要となるため、別のプロセスで実行されるアウトプロセスバックグラウンドタスクに適用されます。インプロセスバックグラウンドタスクでは、タスクが取り消されたことを示すために、状態をアプリケーションと共有するだけで十分です。

バックグラウンドタスクのサンプルによって、LocalSettings の状態が記録されます。

if ((_cancelRequested == false) && (_progress < 100))
{
    _progress += 10;
    _taskInstance.Progress = _progress;
}
else
{
    _periodicTimer.Cancel();

    var settings = ApplicationData.Current.LocalSettings;
    var key = _taskInstance.Task.TaskId.ToString();

    // Write to LocalSettings to indicate that this background task ran.
    if (_cancelRequested)
    {
        settings.Values[key] = "Canceled";
    }
    else
    {
        settings.Values[key] = "Completed";
    }
        
    Debug.WriteLine("Background " + _taskInstance.Task.Name + (_cancelRequested ? " Canceled" : " Completed"));
        
    // Indicate that the background task has completed.
    _deferral.Complete();
}

if (!m_cancelRequested && m_progress < 100)
{
    m_progress += 10;
    m_taskInstance.Progress(m_progress);
}
else
{
    m_periodicTimer.Cancel();

    // Write to LocalSettings to indicate that this background task ran.
    auto settings{ Windows::Storage::ApplicationData::Current().LocalSettings() };
    auto key{ m_taskInstance.Task().Name() };
    settings.Values().Insert(key, (m_progress < 100) ? winrt::box_value(L"Canceled") : winrt::box_value(L"Completed"));

    // Indicate that the background task has completed.
    m_deferral.Complete();
}

if ((CancelRequested == false) && (Progress < 100))
{
    Progress += 10;
    TaskInstance->Progress = Progress;
}
else
{
    PeriodicTimer->Cancel();
        
    // Write to LocalSettings to indicate that this background task ran.
    auto settings = ApplicationData::Current->LocalSettings;
    auto key = TaskInstance->Task->Name;
    settings->Values->Insert(key, (Progress < 100) ? "Canceled" : "Completed");
        
    // Indicate that the background task has completed.
    Deferral->Complete();
}

注釈

バックグラウンドタスクのサンプルをダウンロードして、メソッドのコンテキストに従ってコード例を確認できます。

このサンプルコードでは、説明の便宜上、バックグラウンドタスクのサンプルの Run メソッド (およびコールバックタイマー) の一部しか示していません。

メソッド例を実行します。

バックグラウンドタスクのサンプルのコンテキストがわかるように、以下に完全な Run メソッドとタイマーのコールバックコードを示します。

// The Run method is the entry point of a background task.
public void Run(IBackgroundTaskInstance taskInstance)
{
    Debug.WriteLine("Background " + taskInstance.Task.Name + " Starting...");

    // Query BackgroundWorkCost
    // Guidance: If BackgroundWorkCost is high, then perform only the minimum amount
    // of work in the background task and return immediately.
    var cost = BackgroundWorkCost.CurrentBackgroundWorkCost;
    var settings = ApplicationData.Current.LocalSettings;
    settings.Values["BackgroundWorkCost"] = cost.ToString();

    // Associate a cancellation handler with the background task.
    taskInstance.Canceled += new BackgroundTaskCanceledEventHandler(OnCanceled);

    // Get the deferral object from the task instance, and take a reference to the taskInstance;
    _deferral = taskInstance.GetDeferral();
    _taskInstance = taskInstance;

    _periodicTimer = ThreadPoolTimer.CreatePeriodicTimer(new TimerElapsedHandler(PeriodicTimerCallback), TimeSpan.FromSeconds(1));
}

// Simulate the background task activity.
private void PeriodicTimerCallback(ThreadPoolTimer timer)
{
    if ((_cancelRequested == false) && (_progress < 100))
    {
        _progress += 10;
        _taskInstance.Progress = _progress;
    }
    else
    {
        _periodicTimer.Cancel();

        var settings = ApplicationData.Current.LocalSettings;
        var key = _taskInstance.Task.Name;

        // Write to LocalSettings to indicate that this background task ran.
        settings.Values[key] = (_progress < 100) ? "Canceled with reason: " + _cancelReason.ToString() : "Completed";
        Debug.WriteLine("Background " + _taskInstance.Task.Name + settings.Values[key]);

        // Indicate that the background task has completed.
        _deferral.Complete();
    }
}

void ExampleBackgroundTask::Run(Windows::ApplicationModel::Background::IBackgroundTaskInstance const& taskInstance)
{
    // Query BackgroundWorkCost
    // Guidance: If BackgroundWorkCost is high, then perform only the minimum amount
    // of work in the background task and return immediately.
    auto cost{ Windows::ApplicationModel::Background::BackgroundWorkCost::CurrentBackgroundWorkCost() };
    auto settings{ Windows::Storage::ApplicationData::Current().LocalSettings() };
    std::wstring costAsString{ L"Low" };
    if (cost == Windows::ApplicationModel::Background::BackgroundWorkCostValue::Medium) costAsString = L"Medium";
    else if (cost == Windows::ApplicationModel::Background::BackgroundWorkCostValue::High) costAsString = L"High";
    settings.Values().Insert(L"BackgroundWorkCost", winrt::box_value(costAsString));

    // Associate a cancellation handler with the background task.
    taskInstance.Canceled({ this, &ExampleBackgroundTask::OnCanceled });

    // Get the deferral object from the task instance, and take a reference to the taskInstance.
    m_deferral = taskInstance.GetDeferral();
    m_taskInstance = taskInstance;

    Windows::Foundation::TimeSpan period{ std::chrono::seconds{1} };
    m_periodicTimer = Windows::System::Threading::ThreadPoolTimer::CreatePeriodicTimer([this](Windows::System::Threading::ThreadPoolTimer timer)
    {
        if (!m_cancelRequested && m_progress < 100)
        {
            m_progress += 10;
            m_taskInstance.Progress(m_progress);
        }
        else
        {
            m_periodicTimer.Cancel();

            // Write to LocalSettings to indicate that this background task ran.
            auto settings{ Windows::Storage::ApplicationData::Current().LocalSettings() };
            auto key{ m_taskInstance.Task().Name() };
            settings.Values().Insert(key, (m_progress < 100) ? winrt::box_value(L"Canceled") : winrt::box_value(L"Completed"));

            // Indicate that the background task has completed.
            m_deferral.Complete();
        }
    }, period);
}

void ExampleBackgroundTask::Run(IBackgroundTaskInstance^ taskInstance)
{
    // Query BackgroundWorkCost
    // Guidance: If BackgroundWorkCost is high, then perform only the minimum amount
    // of work in the background task and return immediately.
    auto cost = BackgroundWorkCost::CurrentBackgroundWorkCost;
    auto settings = ApplicationData::Current->LocalSettings;
    settings->Values->Insert("BackgroundWorkCost", cost.ToString());

    // Associate a cancellation handler with the background task.
    taskInstance->Canceled += ref new BackgroundTaskCanceledEventHandler(this, &ExampleBackgroundTask::OnCanceled);

    // Get the deferral object from the task instance, and take a reference to the taskInstance.
    TaskDeferral = taskInstance->GetDeferral();
    TaskInstance = taskInstance;

    auto timerDelegate = [this](ThreadPoolTimer^ timer)
    {
        if ((CancelRequested == false) &&
            (Progress < 100))
        {
            Progress += 10;
            TaskInstance->Progress = Progress;
        }
        else
        {
            PeriodicTimer->Cancel();

            // Write to LocalSettings to indicate that this background task ran.
            auto settings = ApplicationData::Current->LocalSettings;
            auto key = TaskInstance->Task->Name;
            settings->Values->Insert(key, (Progress < 100) ? "Canceled with reason: " + CancelReason.ToString() : "Completed");

            // Indicate that the background task has completed.
            TaskDeferral->Complete();
        }
    };

    TimeSpan period;
    period.Duration = 1000 * 10000; // 1 second
    PeriodicTimer = ThreadPoolTimer::CreatePeriodicTimer(ref new TimerElapsedHandler(timerDelegate), period);
}

取り消されたバックグラウンドタスクの処理

OnCanceled メソッドにより、取り消し要求を認識します。

バックグラウンドタスクを終了することによって、取り消しを処理します。

注釈

メソッド例を実行します。

フィードバック

フィードバック

その他のリソース

取り消されたバックグラウンド タスクの処理

OnCanceled メソッドにより、取り消し要求を認識します。

バックグラウンド タスクを終了することによって、取り消しを処理します。

注釈

メソッド例を実行します。

関連トピック

フィードバック

フィードバック

その他のリソース

取り消されたバックグラウンドタスクの処理

バックグラウンドタスクを終了することによって、取り消しを処理します。