アウトプロセスバックグラウンドタスクの作成と登録

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

重要な API

バックグラウンドタスククラスを作り、アプリがフォアグラウンドにない場合にも実行されるように登録します。このトピックでは、アプリのプロセスとは別のプロセスで実行されるバックグラウンドタスクを作成して登録する方法について説明します。フォアグラウンドアプリケーションで直接バックグラウンド作業を実行する方法については、「インプロセスバックグラウンドタスクの作成と登録」をご覧ください。

注意

バックグラウンドタスクを使ってバックグラウンドでメディアを再生する場合、Windows 10 バージョン 1607 で簡単に行うことができる機能強化について、「バックグラウンドでのメディアの再生」をご覧ください。

注意

.NET 6 以降を使用する C# デスクトップアプリケーションでアウトプロセスバックグラウンドタスクを実装する場合は、C#/WinRT オーサリングサポートを使用してWindows ランタイムコンポーネントを作成します。これは、Windows アプリ SDK、WinUI 3、WPF、または WinForms を使用するアプリに適用されます。例については、バックグラウンドタスクのサンプルを参照してください。

バックグラウンドタスククラスを作る

IBackgroundTask インターフェイスを実装するクラスを作ると、コードをバックグラウンドで実行できます。このコードは、SystemTrigger や MaintenanceTrigger などを使って特定のイベントをトリガーすると実行されます。

次の手順では、IBackgroundTask インターフェイスを実装する新しいクラスを記述する方法について説明します。

バックグラウンドタスク用に新しいプロジェクトを作ってソリューションに追加します。このためには、ソリューションエクスプローラーのソリューションノードを右クリックし、[追加]>[新しいプロジェクト] を順に選びます。プロジェクトの種類として [Windows ランタイムコンポーネント] を選び、プロジェクトに名前を付け、[OK] をクリックします。
ユニバーサル Windows プラットフォーム (UWP) アプリプロジェクトからバックグラウンドタスクプロジェクトを参照します。 C# または C++ のアプリの場合、アプリプロジェクトで [参照] を右クリックして [新しい参照の追加] をクリックします。 [ソリューション] で、[プロジェクト] を選び、バックグラウンドタスクプロジェクトの名前を選んで [OK] をクリックします。
バックグラウンドタスクプロジェクトに、IBackgroundTask インターフェイスを実装する新しいクラスを追加します。 IBackgroundTask.Run メソッドは、指定のイベントがトリガーされたときに呼び出される必須のエントリポイントです。このメソッドは、各バックグラウンドタスクに必要です。

注意

バックグラウンドタスククラス自体と、バックグラウンドタスクプロジェクト内のその他すべてのクラスは、sealed (または final の) public クラスである必要があります。

次のサンプルコードは、バックグラウンドタスククラスの基本的な開始点を示しています。

// ExampleBackgroundTask.cs
using Windows.ApplicationModel.Background;

namespace Tasks
{
    public sealed class ExampleBackgroundTask : IBackgroundTask
    {
        public void Run(IBackgroundTaskInstance taskInstance)
        {
            
        }        
    }
}

// First, add ExampleBackgroundTask.idl, and then build.
// ExampleBackgroundTask.idl
namespace Tasks
{
    [default_interface]
    runtimeclass ExampleBackgroundTask : Windows.ApplicationModel.Background.IBackgroundTask
    {
        ExampleBackgroundTask();
    }
}

// ExampleBackgroundTask.h
#pragma once

#include "ExampleBackgroundTask.g.h"

namespace winrt::Tasks::implementation
{
    struct ExampleBackgroundTask : ExampleBackgroundTaskT<ExampleBackgroundTask>
    {
        ExampleBackgroundTask() = default;

        void Run(Windows::ApplicationModel::Background::IBackgroundTaskInstance const& taskInstance);
    };
}

namespace winrt::Tasks::factory_implementation
{
    struct ExampleBackgroundTask : ExampleBackgroundTaskT<ExampleBackgroundTask, implementation::ExampleBackgroundTask>
    {
    };
}

// ExampleBackgroundTask.cpp
#include "pch.h"
#include "ExampleBackgroundTask.h"

namespace winrt::Tasks::implementation
{
    void ExampleBackgroundTask::Run(Windows::ApplicationModel::Background::IBackgroundTaskInstance const& taskInstance)
    {
        throw hresult_not_implemented();
    }
}

// ExampleBackgroundTask.h
#pragma once

using namespace Windows::ApplicationModel::Background;

namespace Tasks
{
    public ref class ExampleBackgroundTask sealed : public IBackgroundTask
    {

    public:
        ExampleBackgroundTask();

        virtual void Run(IBackgroundTaskInstance^ taskInstance);
        void OnCompleted(
            BackgroundTaskRegistration^ task,
            BackgroundTaskCompletedEventArgs^ args
        );
    };
}

// ExampleBackgroundTask.cpp
#include "ExampleBackgroundTask.h"

using namespace Tasks;

void ExampleBackgroundTask::Run(IBackgroundTaskInstance^ taskInstance)
{
}

バックグラウンドタスクで非同期コードを実行する場合は、バックグラウンドタスクで遅延を使う必要があります。遅延を使わない場合、非同期処理の実行が完了する前に Run メソッドから制御が戻されると、バックグラウンドタスクプロセスが予期せずに終了することがあります。

非同期メソッドを呼び出す前に、Run メソッド内で遅延を要求します。クラスのデータメンバーに遅延を保存して、非同期メソッドからアクセスできるようにします。非同期コードが完了した後、遅延を完了するように宣言します。

次のサンプルコードでは、遅延を取得して保存し、非同期コードが完了した時点で解放します。

BackgroundTaskDeferral _deferral; // Note: defined at class scope so that we can mark it complete inside the OnCancel() callback if we choose to support cancellation
public async void Run(IBackgroundTaskInstance taskInstance)
{
    _deferral = taskInstance.GetDeferral();
    //
    // TODO: Insert code to start one or more asynchronous methods using the
    //       await keyword, for example:
    //
    // await ExampleMethodAsync();
    //

    _deferral.Complete();
}

// ExampleBackgroundTask.h
...
private:
    Windows::ApplicationModel::Background::BackgroundTaskDeferral m_deferral{ nullptr };

// ExampleBackgroundTask.cpp
...
Windows::Foundation::IAsyncAction ExampleBackgroundTask::Run(
    Windows::ApplicationModel::Background::IBackgroundTaskInstance const& taskInstance)
{
    m_deferral = taskInstance.GetDeferral(); // Note: defined at class scope so that we can mark it complete inside the OnCancel() callback if we choose to support cancellation.
    // TODO: Modify the following line of code to call a real async function.
    co_await ExampleCoroutineAsync(); // Run returns at this point, and resumes when ExampleCoroutineAsync completes.
    m_deferral.Complete();
}

void ExampleBackgroundTask::Run(IBackgroundTaskInstance^ taskInstance)
{
    m_deferral = taskInstance->GetDeferral(); // Note: defined at class scope so that we can mark it complete inside the OnCancel() callback if we choose to support cancellation.

    //
    // TODO: Modify the following line of code to call a real async function.
    //       Note that the task<void> return type applies only to async
    //       actions. If you need to call an async operation instead, replace
    //       task<void> with the correct return type.
    //
    task<void> myTask(ExampleFunctionAsync());

    myTask.then([=]() {
        m_deferral->Complete();
    });
}

注意

C# では、async/await キーワードを使ってバックグラウンドタスクの非同期メソッドを呼び出すことができます。 C++/CX では、タスクチェーンを使うことで同様の結果が得られます。

非同期パターンについて詳しくは、「非同期プログラミング」をご覧ください。遅延を使ってバックグラウンドタスクの早期停止を防ぐ方法に関するその他の例については、バックグラウンドタスクのサンプルに関するページをご覧ください。

次の手順はいずれかのアプリクラス (MainPage.xaml.cs など) で実行します。

注意

バックグラウンドタスクを登録するための専用の関数を作成することもできます (「バックグラウンドタスクの登録」を参照)。その場合、次の 3 つの手順は不要です。単にトリガーを作成し、タスクの名前とタスクのエントリポイント、(必要に応じて) 条件と併せて登録関数に渡すだけで済みます。

実行するバックグラウンドタスクを登録する

同じバックグラウンドタスクが登録されていないかどうかを、BackgroundTaskRegistration.AllTasks プロパティを反復処理して確認します。この確認は重要です。既にあるバックグラウンドタスクの二重登録をアプリで確認しなかった場合、同じタスクが何度も登録され、パフォーマンスが低下したり、タスクの CPU 時間を使い切って処理を完了できなくなるなどの問題が生じます。

次の例では、AllTasks プロパティを反復処理し、タスクが既に登録されていた場合はフラグ変数を true に設定します。

var taskRegistered = false;
var exampleTaskName = "ExampleBackgroundTask";

foreach (var task in BackgroundTaskRegistration.AllTasks)
{
    if (task.Value.Name == exampleTaskName)
    {
        taskRegistered = true;
        break;
    }
}

std::wstring exampleTaskName{ L"ExampleBackgroundTask" };

auto allTasks{ Windows::ApplicationModel::Background::BackgroundTaskRegistration::AllTasks() };

bool taskRegistered{ false };
for (auto const& task : allTasks)
{
    if (task.Value().Name() == exampleTaskName)
    {
        taskRegistered = true;
        break;
    }
}

// The code in the next step goes here.

boolean taskRegistered = false;
Platform::String^ exampleTaskName = "ExampleBackgroundTask";

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

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

    if(cur->Name == exampleTaskName)
    {
        taskRegistered = true;
        break;
    }

    hascur = iter->MoveNext();
}

バックグラウンドタスクがまだ登録されていない場合は、BackgroundTaskBuilder を使ってバックグラウンドタスクのインスタンスを作成します。タスクのエントリポイントには、名前空間を含めてバックグラウンドタスククラスの名前を指定します。

バックグラウンドタスクトリガーは、バックグラウンドタスクが実行されるタイミングを制御します。指定できるトリガーの一覧については、「SystemTrigger」をご覧ください。

たとえば、こちらのコードでは、新しいバックグラウンドタスクを作成し、TimeZoneChanged トリガーが発生したときに実行されるように設定しています。

var builder = new BackgroundTaskBuilder();

builder.Name = exampleTaskName;
builder.TaskEntryPoint = "Tasks.ExampleBackgroundTask";
builder.SetTrigger(new SystemTrigger(SystemTriggerType.TimeZoneChange, false));

if (!taskRegistered)
{
    Windows::ApplicationModel::Background::BackgroundTaskBuilder builder;
    builder.Name(exampleTaskName);
    builder.TaskEntryPoint(L"Tasks.ExampleBackgroundTask");
    builder.SetTrigger(Windows::ApplicationModel::Background::SystemTrigger{
        Windows::ApplicationModel::Background::SystemTriggerType::TimeZoneChange, false });
    // The code in the next step goes here.
}

auto builder = ref new BackgroundTaskBuilder();

builder->Name = exampleTaskName;
builder->TaskEntryPoint = "Tasks.ExampleBackgroundTask";
builder->SetTrigger(ref new SystemTrigger(SystemTriggerType::TimeZoneChange, false));

トリガーイベントの発生後、どのようなときにタスクを実行するかという条件を追加することもできます (省略可能)。たとえば、ユーザーが存在するときにだけタスクを実行する場合、UserPresent という条件を使います。指定できる条件の一覧については、「SystemConditionType」をご覧ください。

次のサンプルコードでは、"ユーザーの存在" を条件として割り当てています。

builder.AddCondition(new SystemCondition(SystemConditionType.UserPresent));

builder.AddCondition(Windows::ApplicationModel::Background::SystemCondition{ Windows::ApplicationModel::Background::SystemConditionType::UserPresent });
// The code in the next step goes here.

builder->AddCondition(ref new SystemCondition(SystemConditionType::UserPresent));

BackgroundTaskBuilder オブジェクトで Register メソッドを呼び出してバックグラウンドタスクを登録します。 BackgroundTaskRegistration の結果は、次の手順に備えて保存します。

バックグラウンドタスクを登録し、その結果を保存するコードを次に示します。

BackgroundTaskRegistration task = builder.Register();

Windows::ApplicationModel::Background::BackgroundTaskRegistration task{ builder.Register() };

BackgroundTaskRegistration^ task = builder->Register();

注意

ユニバーサル Windows アプリは、どの種類のバックグラウンドトリガーを登録する場合でも、先に RequestAccessAsync を呼び出す必要があります。

更新プログラムのリリース後にユニバーサル Windows アプリが引き続き適切に実行されるようにするには、ServicingComplete (SystemTriggerType に関するページをご覧ください) トリガーを使って、アプリのデータベースの移行やバックグラウンドタスクの登録などの更新後の構成の変更を実行します。現時点で、アプリの以前のバージョンに関連付けられたバックグラウンドタスクの登録を解除してから (RemoveAccess に関するページをご覧ください)、アプリの新しいバージョンのバックグラウンドタスクを登録する (RequestAccessAsync に関するページをご覧ください) ことをお勧めします。

詳しくは、「バックグラウンドタスクのガイドライン」をご覧ください。

イベントハンドラーでバックグラウンドタスクの完了を処理する

アプリからバックグラウンドタスクの結果を取得できるように、BackgroundTaskCompletedEventHandler にメソッドを登録します。アプリが起動、または再開されると、アプリが最後にフォアグラウンドに置かれた後にバックグラウンドタスクが終了していた場合、指定のメソッドが呼び出されます (アプリがフォアグラウンドにある間にバックグラウンドタスクが終了した場合は、OnCompleted メソッドが直ちに呼び出されます)。

バックグラウンドタスクの完了を処理する OnCompleted メソッドを記述します。たとえば、バックグラウンドタスクの結果により UI を更新できます。ここに示すメソッドのフットプリントは、この例では args パラメーターは使われていませんが、OnCompleted イベントハンドラーメソッドで必須になります。

次のサンプルコードは、バックグラウンドタスクの完了を認識し、メッセージ文字列を使う UI 更新メソッドの例を呼び出します。

private void OnCompleted(IBackgroundTaskRegistration task, BackgroundTaskCompletedEventArgs args)
{
    var settings = Windows.Storage.ApplicationData.Current.LocalSettings;
    var key = task.TaskId.ToString();
    var message = settings.Values[key].ToString();
    UpdateUI(message);
}

void UpdateUI(winrt::hstring const& message)
{
    MyTextBlock().Dispatcher().RunAsync(Windows::UI::Core::CoreDispatcherPriority::Normal, [=]()
    {
        MyTextBlock().Text(message);
    });
}

void OnCompleted(
    Windows::ApplicationModel::Background::BackgroundTaskRegistration const& sender,
    Windows::ApplicationModel::Background::BackgroundTaskCompletedEventArgs const& /* args */)
{
	// You'll previously have inserted this key into local settings.
    auto settings{ Windows::Storage::ApplicationData::Current().LocalSettings().Values() };
    auto key{ winrt::to_hstring(sender.TaskId()) };
    auto message{ winrt::unbox_value<winrt::hstring>(settings.Lookup(key)) };

    UpdateUI(message);
}

void MainPage::OnCompleted(BackgroundTaskRegistration^ task, BackgroundTaskCompletedEventArgs^ args)
{
    auto settings = ApplicationData::Current->LocalSettings->Values;
    auto key = task->TaskId.ToString();
    auto message = dynamic_cast<String^>(settings->Lookup(key));
    UpdateUI(message);
}

注意

UI の更新は、UI スレッドを拘束することがないように、非同期で実行する必要があります。例については、バックグラウンドタスクのサンプルの UpdateUI メソッドを参照してください。

バックグラウンドタスクを登録した位置に戻ります。そのコード行の後に、新しい BackgroundTaskCompletedEventHandler オブジェクトを追加します。 BackgroundTaskCompletedEventHandler コンストラクターのパラメーターとして OnCompleted メソッドを指定します。

次のサンプルコードにより、BackgroundTaskRegistration に BackgroundTaskCompletedEventHandler が追加されます。

task.Completed += new BackgroundTaskCompletedEventHandler(OnCompleted);

task.Completed({ this, &MainPage::OnCompleted });

task->Completed += ref new BackgroundTaskCompletedEventHandler(this, &MainPage::OnCompleted);

アプリがバックグラウンドタスクを使うことをアプリマニフェストで宣言する

アプリでバックグラウンドタスクを実行する前に、各バックグラウンドタスクをアプリマニフェストで宣言する必要があります。マニフェストにないトリガーを使用してバックグラウンドタスクを登録しようとすると、バックグラウンドタスクの登録は、"ランタイムクラスが登録されていません" というエラーで失敗します。

Package.appxmanifest という名前のファイルを開いて、パッケージマニフェストデザイナーを開きます。
[宣言] タブを開きます。
[使用可能な宣言] ボックスの一覧の [バックグラウンドタスク] を選び、[追加] をクリックします。
[システムイベント] チェックボックスをオンにします。
[エントリポイント] ボックスに、バックグラウンドクラスの名前空間と名前を入力します。この例の場合、Tasks.ExampleBackgroundTask です。
マニフェストデザイナーを閉じます。

バックグラウンドタスクを登録するために、次の Extensions 要素が Package.appxmanifest ファイルに追加されます。

<Extensions>
  <Extension Category="windows.backgroundTasks" EntryPoint="Tasks.ExampleBackgroundTask">
    <BackgroundTasks>
      <Task Type="systemEvent" />
    </BackgroundTasks>
  </Extension>
</Extensions>

まとめと次のステップ

ここでは、バックグラウンドタスククラスの記述方法、アプリ内からバックグラウンドタスクを登録する方法、バックグラウンドタスクが完了したことをアプリで認識する方法の基本について学習しました。また、アプリで適切にバックグラウンドタスクを登録できるように、アプリマニフェストを更新する方法についても学習しました。

注意

バックグラウンドタスクのサンプルをダウンロードして、バックグラウンドタスクを使う完全で堅牢な UWP アプリのコンテキストで類似のコード例を確認してください。

API リファレンス、バックグラウンドタスクの概念的ガイダンス、バックグラウンドタスクを使ったアプリの作成に関する詳しい説明については、次の関連するトピックをご覧ください。

バックグラウンドタスクに関する手順を詳しく説明するトピック

バックグラウンドタスクのガイダンス

バックグラウンドタスクの API リファレンス

Windows.ApplicationModel.Background

アウトプロセスバックグラウンドタスクの作成と登録

バックグラウンドタスククラスを作る

実行するバックグラウンドタスクを登録する

イベントハンドラーでバックグラウンドタスクの完了を処理する

アプリがバックグラウンドタスクを使うことをアプリマニフェストで宣言する

まとめと次のステップ

フィードバック

フィードバック

その他のリソース

アウトプロセス バックグラウンド タスクの作成と登録

バックグラウンド タスク クラスを作る

実行するバックグラウンド タスクを登録する

イベント ハンドラーでバックグラウンド タスクの完了を処理する

アプリがバックグラウンド タスクを使うことをアプリ マニフェストで宣言する

まとめと次のステップ

関連トピック

フィードバック

フィードバック

その他のリソース

アウトプロセスバックグラウンドタスクの作成と登録

バックグラウンドタスククラスを作る

実行するバックグラウンドタスクを登録する

イベントハンドラーでバックグラウンドタスクの完了を処理する

アプリがバックグラウンドタスクを使うことをアプリマニフェストで宣言する