バックグラウンド タスクのデバッグDebug a background task

重要な APIImportant APIs

バックグラウンド タスクをデバッグする方法について説明します。バックグラウンド タスクのアクティブ化のほか、Windows イベント ログでのデバッグ トレースなどについて取り上げます。Learn how to debug a background task, including background task activation and debug tracing in the Windows event log.

アウトプロセス バックグラウンド タスクのデバッグとインプロセス バックグラウンド タスクのデバッグDebugging out-of-process vs. in-process background tasks

このトピックでは主に、ホスト アプリとは別のプロセスで実行されているバックグラウンド タスクについて扱います。This topic primarily addresses background tasks that run in a separate process than the host app. インプロセス バックグラウンド タスクをデバッグする場合、別個のバックグラウンド タスク プロジェクト タスクはいらず、OnBackgroundActivated() (インプロセス バックグラウンド コードが実行される場所) にブレークポイントを設定できます。実行するバックグラウンド コードをトリガーする手順については、以下の「バックグラウンド タスク コードをデバッグするためバックグラウンド タスクを手動でトリガー」をご覧ください。If you are debugging an in-process background task, then you won't have a separate background task project and can set a breakpoint on OnBackgroundActivated() (where your in-process background code runs) and see step 2 in Trigger background tasks manually to debug background task code, below, for instructions about how to trigger your background code to execute.

バックグラウンド タスク プロジェクトが正しく設定されていることを確認Make sure the background task project is set up correctly

このトピックは、デバッグ対象のバックグラウンド タスクを備えたアプリが既に手元にあることを前提としています。This topic assumes that you already have an existing app with a background task to debug. 以下の内容は、アウトプロセスで実行されるバックグラウンド タスクに固有の内容であり、インプロセス バックグラウンド タスクには適用されません。The following is specific to background tasks that run out-of-process and does not apply to in-process background tasks.

  • C# と C++ の場合、メイン プロジェクトがバックグラウンド タスク プロジェクトを参照していることを確認します。In C# and C++, make sure the main project references the background task project. この参照が行われない場合、アプリ パッケージにバックグラウンド タスクが含まれていない可能性があります。If this reference is not in place, the background task won't be included in the app package.
  • C# と C++ の場合、バックグラウンド タスク プロジェクトの [出力の種類] が "Windows ランタイム コンポーネント" になっていることを確認します。In C# and C++, make sure the Output type of the background task project is "Windows Runtime Component".
  • バックグラウンド クラスは、パッケージ マニフェストのエントリ ポイント属性で宣言されている必要があります。The background class must be declared in the entry point attribute in the package manifest.

バックグラウンド タスク コードをデバッグするためバックグラウンド タスクを手動でトリガーTrigger background tasks manually to debug background task code

バックグラウンド タスクは、Microsoft Visual Studio を使って手動でトリガーできます。Background tasks can be triggered manually through Microsoft Visual Studio. その後で、コードをステップ実行してデバッグできます。Then you can step through the code and debug it.

  1. C# では、バックグラウンド クラスの Run メソッドにブレークポイントを置き (インプロセス バックグラウンド タスクの場合は、App.OnBackgroundActivated() にブレークポイントを置きます)、System.Diagnostics を使ってデバッグ出力を記述します。In C#, put a breakpoint in the Run method of the background class (for in-process background tasks put the breakpoint in App.OnBackgroundActivated()), and/or write debugging output by using System.Diagnostics.

    C++ では、バックグラウンド クラスの Run 関数にブレークポイントを置き (インプロセス バックグラウンド タスクの場合は、App.OnBackgroundActivated() にブレークポイントを置きます)、OutputDebugString を使ってデバッグ出力を記述します。In C++, put a breakpoint in the Run function of the background class (for in-process background tasks put the breakpoint in App.OnBackgroundActivated()), and/or write debugging output by using OutputDebugString.

  2. デバッガーでアプリケーションを実行し、[ライフサイクル イベント] ツール バーを使ってバックグラウンド タスクをトリガーします。Run your application in the debugger and then trigger the background task using the Lifecycle Events toolbar. このドロップダウンには、Visual Studio でアクティブ化できるバックグラウンド タスクの名前が表示されます。This drop down shows the names of the background tasks that can be activated by Visual Studio.

    注意

    Visual Studio では、[ライフサイクルイベント] ツールバーのオプションは既定では表示されません。The Lifecycle Events toolbar options are not shown by default in Visual Studio. これらのオプションを表示するには、Visual Studio で現在のツールバーを右クリックし、[ デバッグの場所 ] オプションが有効になっていることを確認します。To show these options, right-click on the current toolbar in Visual Studio and ensure the option Debug Location is enabled.

    この機能を使うには、バックグラウンド タスクが既に登録されていて、トリガーを待機する状態になっていることが必要です。For this to work, the background task must already be registered and it must still be waiting for the trigger. たとえば、1 回限りの TimeTrigger に対してバックグラウンド タスクを登録した場合、そのトリガーが起動された後に Visual Studio からそのタスクを起動しても何も起こりません。For example, if a background task was registered with a one-shot TimeTrigger and that trigger has already fired, launching the task through Visual Studio will have no effect.

    注意

    次のトリガーを使ったバックグラウンド タスクを、アプリケーション トリガーMediaProcessing トリガーControlChannelTriggerPushNotificationTriggerSmsReceived トリガー型の SystemTrigger を使ったバックグラウンド タスク、という方法でアクティブ化することはできません。Background tasks using the following triggers cannot be activated in this manner: Application trigger, MediaProcessing trigger, ControlChannelTrigger, PushNotificationTrigger, and background tasks using a SystemTrigger with the SmsReceived trigger type.
    Application triggerMediaProcessingTrigger は、trigger.RequestAsync() を使ってコードで手動通知できます。Application trigger and MediaProcessingTrigger can be signaled manually in code with trigger.RequestAsync().

    バックグラウンド タスクのデバッグ

  3. バックグラウンド タスクがアクティブになると、デバッガーがアタッチされて、デバッグ出力が VS に表示されます。When the background task activates, the debugger will attach to it and display debug output in VS.

バックグラウンド タスクのアクティブ化のデバッグDebug background task activation

注意

このセクションは、アウトプロセスで実行されるバックグラウンド タスクに固有の内容であり、インプロセス バックグラウンド タスクには適用されません。This section is specific to background tasks the run out-of-process and does not apply to in-process background tasks.

バックグラウンド タスクのアクティブ化は、次の 3 つの点に依存します。Background task activation depends on three things:

  • バック グラウンド タスク クラスの名前と名前空間The name and namespace of the background task class
  • パッケージ マニフェストで指定されたエントリ ポイント属性The entry point attribute specified in the package manifest
  • バックグラウンド タスクの登録時にアプリによって指定されたエントリ ポイントThe entry point specified by your app when registering the background task
  1. Visual Studio を使い、バックグラウンド タスクのエントリ ポイントを確認します。Use Visual Studio to note the entry point of the background task:

    • C# と C++ の場合、バックグラウンド タスク プロジェクトで指定されたバックグラウンド タスク クラスの名前と名前空間を確認します。In C# and C++, note the name and namespace of the background task class specified in the background task project.
  2. マニフェスト デザイナーを使い、バックグラウンド タスクがパッケージ マニフェストで正しく宣言されているかどうかを確認します。Use the manifest designer to check that the background task is correctly declared in the package manifest:

    • C# と C++ の場合、エントリ ポイント属性が、クラス名の前のバックグラウンド タスク名前空間と一致している必要があります。In C# and C++, the entry point attribute must match the background task namespace followed by the class name. たとえば、RuntimeComponent1.MyBackgroundTask のようになります。For example: RuntimeComponent1.MyBackgroundTask.
    • タスクと共に使われるトリガー タイプがすべて指定されている必要があります。All the trigger type(s) used with the task must also be specified.
    • ControlChannelTrigger または PushNotificationTrigger を使う場合以外、実行可能ファイルを指定しないでください。The executable MUST NOT be specified unless you are using the ControlChannelTrigger or PushNotificationTrigger.
  3. Windows のみ。Windows only. バックグラウンド タスクをアクティブ化するために Windows で使われるエントリ ポイントを確認するには、デバッグ トレースを有効にして Windows イベント ログを使います。To see the entry point used by Windows to activate the background task, enable debug tracing and use the Windows event log.

    この手順を実行し、その結果イベント ログにバックグラウンド タスクの間違ったエントリ ポイントまたはトリガーが表示される場合は、アプリにバックグラウンド タスクが正しく登録されていません。If you follow this procedure and the event log shows the wrong entry point or trigger for the background task, your app is not registering the background task correctly. このタスクのヘルプが必要な場合は、「バックグラウンド タスクの登録」をご覧ください。For help with this task see Register a background task.

    1. スタート画面に移動して eventvwr.exe を検索し、イベント ビューアーを開きます。Open event viewer by going to the Start screen and searching for eventvwr.exe.
    2. イベントビューアーで、[アプリケーションとサービスログ] [ - > Microsoft - > Windows - > backgroundtaskinfrastructure ] にアクセスします。Go to Application and Services Logs -> Microsoft -> Windows -> BackgroundTaskInfrastructure in the event viewer.
    3. [操作] ウィンドウで、[表示] [ - > 分析とデバッグログの表示] を選択して、診断ログを有効にします。In the actions pane, select View -> Show Analytic and Debug Logs to enable the diagnostic logging.
    4. 診断ログを選び、[ログの有効化] をクリックします。Select the Diagnostic log and click Enable Log.
    5. 次に、アプリを使ってバックグラウンド タスクの登録とアクティブ化をもう一度試します。Now try using your app to register and activate the background task again.
    6. 診断ログで、詳しいエラー情報を確認します。View the diagnostic logs for detailed error information. このログには、バックグラウンド タスクに登録されたエントリ ポイントが含まれます。This will include the entry point registered for the background task.

イベント ビューアーでバックグラウンド タスクのデバッグ情報を表示

バックグラウンド タスクと Visual Studio パッケージの展開Background tasks and Visual Studio package deployment

バックグラウンドタスクを使用するアプリが Visual Studio を使用して展開され、マニフェストデザイナーで指定されたバージョン (メジャーまたはマイナー) が更新された場合、その後 Visual Studio でアプリを再配置すると、アプリのバックグラウンドタスクが停止する可能性があります。If an app that uses background tasks is deployed using Visual Studio, and the version (major and/or minor) specified in Manifest Designer is then updated, subsequently re-deploying the app with Visual Studio may cause the app's background tasks to stall. これは、次のようにして対処できます。This can be remedied as follows:

  • 更新したアプリを (Visual Studio ではなく) Windows PowerShell を使って展開します。パッケージと一緒に生成されるスクリプトを実行してください。Use Windows PowerShell to deploy the updated app (instead of Visual Studio) by running the script generated alongside the package.
  • 既に Visual Studio を使用してアプリをデプロイしていて、バックグラウンドタスクが停滞している場合は、再起動またはログオフ/ログインして、アプリのバックグラウンドタスクを再度実行します。If you already deployed the app using Visual Studio and its background tasks are now stalled, reboot or log off/log in to get the app's background tasks working again.
  • C# プロジェクトでは、"パッケージを常に再インストール" というデバッグ オプションを選ぶことで、この問題を回避することができます。You can select the "Always re-install my package" debugging option to avoid this in C# projects.
  • アプリが最終的な配置の準備が整うまで待ってから、パッケージのバージョンを増やします (デバッグ中に変更しないでください)。Wait until the app is ready for final deployment to increment the package version (don't change it while debugging).

注釈Remarks

  • バックグラウンド タスクは、同じバックグラウンド タスクが登録されていないことをアプリ側で必ずチェックしたうえで登録してください。Make sure your app checks for existing background task registrations before registering the background task again. 同じバックグラウンド タスクを重複して登録すると、1 回のトリガーにつきバックグラウンド タスクが複数回実行され、予期しない結果を招きます。Multiple registrations of the same background task can cause unexpected results by running the background task more than once each time it is triggered.
  • バックグラウンド タスクがロック画面へのアクセスを必要とする場合は、バックグラウンド タスクをデバッグする前にロック画面にアプリを配置してください。If the background task requires lock screen access make sure to put the app on the lock screen before trying to debug the background task. ロック画面対応アプリのマニフェスト オプションを指定する方法については、「アプリケーション マニフェストでのバックグラウンド タスクの宣言」をご覧ください。For info on specifying manifest options for lock screen-capable apps, see Declare background tasks in the application manifest.
  • バックグラウンド タスクの登録パラメーターは登録時に検証されます。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.

VS を使用してバックグラウンドタスクをデバッグする方法の詳細については、「 UWP アプリで中断イベント、再開イベント、およびバックグラウンドイベントをトリガーする方法」を参照してください。For more info on using VS to debug a background task see How to trigger suspend, resume, and background events in UWP apps.