How to debug a background task (Windows Runtime apps)

  • Article

[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]

Learn how to debug a background task, including background task activation and debug tracing in the Windows event log.

What you need to know

Technologies

Prerequisites

  • This topic assumes that you have an existing app with a background task you need to debug.

Instructions

Make sure the background task project is set up correctly

  • 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.
  • In C# and C++, make sure the Output type of the background task project is "WinMD File".
  • In JavaScript, the background task worker must be in its own JavaScript file.
  • The background task must be declared in the package manifest. JavaScript tasks are declared using the start page attribute, while other tasks are declared using the entry point attribute.

Trigger background tasks manually to debug background task code

Background tasks can be triggered manually through Microsoft Visual Studio. Then you can step through the code and debug it.

  1. In C#, put a breakpoint in the Run method, and/or write debugging output by using System.Diagnostics.

    In C++, put a breakpoint in the Run function, and/or write debugging output by using OutputDebugString.

    In JavaScript, put a breakpoint in the background task JavaScript file, and/or write debugging output by using the debug object.

  2. Trigger the background task using the suspend drop down menu available in the Debug Location toolbar. This drop down shows the names of the background tasks that can be activated by Visual Studio.

    For this to work, the background task must already be registered and it must still be waiting for the trigger. 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.

    Note  Background tasks using the ControlChannelTrigger or PushNotificationTrigger, and background tasks using a SystemTrigger with the SmsReceived trigger type, cannot be activated in this manner.

     

  3. When the background task activates, the debugger will attach to it and display debug output in VS.

Debug background task activation

Background task activation depends on three things matching up correctly. This procedure shows how to check and make sure that these all match up.

  • The name and namespace of the background task class (for Javascript, the path and filename of the task)
  • The entry point attribute specified in the package manifest (for Javascript, the start page attribute)
  • The entry point specified by your app when registering the background task

  1. Use Visual Studio to note the entry point of the background task:

    • In C# and C++, note the name and namespace of the background task class specified in the background task project.
    • In JavaScript, note the path to the background task file and the filename.

  2. Use the manifest designer to check that the background task is correctly declared in the package manifest:

    • In C# and C++, the entry point attribute must match the background task namespace followed by the class name. For example: Tasks.MyBackgroundTask.
    • In JavaScript, the start page attribute must be the path to the JavaScript file for the background task worker. For example: js\MyBackgroundTask.js.
    • All the trigger type(s) used with the task must also be specified.
    • The executable MUST NOT be specified unless you are using the ControlChannelTrigger or PushNotificationTrigger.

  3. Windows only. 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 How to register a background task.

    1. Open event viewer by going to the Start screen and searching for eventvwr.exe.
    2. 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.

Background tasks and Visual Studio package deployment

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:

  • Use Windows PowerShell to deploy the updated app (instead of Visual Studio) by running the script generated alongside the package.
  • 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.
  • 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

Additional tips for debugging background tasks:

  • JavaScript background tasks need to call close() when they are complete. If the background task doesn't call close(), the task process keeps running. This can waste battery life and cause unexpected behavior.
  • Make sure your app checks for existing background task registrations before registering the background task again. Multiple registrations of the same background task can cause unexpected results by running the background task more than once each time it is triggered. For help with this task see How to get a list of pending background tasks.
  • On Windows, 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 How to show notifications on the lock screen and How to declare background tasks in the application manifest.
  • Starting in Windows 8.1, 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. For example, your app can use a conditional statement to check for registration errors, and then retry failed registration with different parameter values.

For more info on using VS to debug a background task see How to trigger suspend, resume, and background events in Windows Store apps.

Quickstart: Create and register a background task

How to register a background task

How to declare background tasks in the application manifest

Guidelines and checklists for background tasks

Manifest Designer

How to trigger suspend, resume, and background events in Windows Store apps

Analyzing the code quality of Windows Windows Store apps with Visual Studio code analysis