Share via

How to declare background tasks in the application manifest (XAML)

  • 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]

Enable the use of background tasks by declaring them as extensions in the app manifest. Each background task must be declared as an extension in the application manifest. Without this, your app will not be able to register the background tasks (an exception will be thrown). Additionally, background tasks must be declared in the application manifest to pass certification.

What you need to know

Technologies

  • Microsoft Visual Studio Manifest Designer

Prerequisites

  • This topic assumes you have a created one or more background task classes, and that your app registers each background task to run in response to at least one trigger.

Instructions

Step 1: Add Extensions Manually

Open the application manifest and go to the Application element. Create an Extensions element (if one doesn't already exist).

The following snippet is taken from the BackgroundTaskSample:

    <Application Id="BackgroundTaskSample.App" Executable="BackgroundTaskSample.exe" EntryPoint="BackgroundTaskSample.App">
      <VisualElements DisplayName="BackgroundTaskSample" Logo="Images\squareTile-sdk.png" SmallLogo="Images\smallTile-sdk.png" Description="BackgroundTaskSample" ForegroundText="dark" BackgroundColor="#222222">
        <LockScreen Notification="badgeAndTileText" BadgeLogo="images\badgelogo.png" />
        <DefaultTile ShowName="allLogos" WideLogo="images\tile-sdk.png" />
        <SplashScreen Image="Images\splash-sdk.png" BackgroundColor="#FFFFFF" />
      </VisualElements>

      <Extensions>

          <!-- TODO: Add elements here -->

      </Extensions>

    </Application>

Step 2: Add Background Task Extension

Declare your first background task.

Copy this code into the Extensions element (you will add attributes in the following steps).

      <Extensions>

        <Extension Category="windows.backgroundTasks" EntryPoint="">
          <BackgroundTasks>
            <Task Type="" />
          </BackgroundTasks>
        </Extension>

      </Extensions>

  1. Change the EntryPoint attribute to have the same string used by your code as the entry point when registering your background task (namespace.classname).

    In this example, the entry point is ExampleBackgroundTaskNameSpace.ExampleBackgroundTaskClassName:

          <Extensions>

        <Extension Category="windows.backgroundTasks" EntryPoint="Tasks.ExampleBackgroundTaskClassName">
          <BackgroundTasks>
            <Task Type="" />
          </BackgroundTasks>
        </Extension>

      </Extensions>

  2. Change the list of Task Type attribute to indicate the type of task registration used with this background task. If the background task is registered with multiple trigger types, add additional Task elements and Type attributes for each one.

    Note  Make sure to list each of the trigger types you're using, or the background task will not register with the undeclared trigger types (the Register method will fail and throw an exception).

     

    This snippet example indicates the use of system event triggers and push notifications:

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

    Note  Normally, an app will run in a special process called "BackgroundTaskHost.exe". It is possible to add an Executable element to the Extension element, allowing the background task to run in the context of the app. Only use the Executable element with background tasks that require it, such as the ControlChannelTrigger.

     

Step 3: Add Additional Background Task Extensions

Repeat step 2 for each additional background task class registered by your app.

The following example is the complete Application element from the background task sample. This shows the use of 2 background task classes with a total of 3 trigger types. Copy the Extensions section of this example, and modify it as needed, to declare background tasks in your application manifest.

<Application Id="BackgroundTask.App" Executable="$targetnametoken$.exe" EntryPoint="BackgroundTask.App">
  <VisualElements DisplayName="BackgroundTask CS sample" Logo="Assets\squareTile-sdk.png" SmallLogo="Assets\smallTile-sdk.png" Description="BackgroundTask CS sample" ForegroundText="light" BackgroundColor="#00b2f0">
    <LockScreen Notification="badgeAndTileText" BadgeLogo="Assets\badgelogo.png" />
    <DefaultTile ShowName="allLogos" ShortName="BGTask CS" WideLogo="Assets\tile-sdk.png" />
    <SplashScreen Image="Assets\splash-sdk.png" BackgroundColor="#00b2f0" />
  </VisualElements>
  <Extensions>
    <Extension Category="windows.backgroundTasks" EntryPoint="Tasks.SampleBackgroundTask">
      <BackgroundTasks>
        <Task Type="systemEvent" />
        <Task Type="timer" />
      </BackgroundTasks>
    </Extension>
    <Extension Category="windows.backgroundTasks" EntryPoint="Tasks.ServicingComplete">
      <BackgroundTasks>
        <Task Type="systemEvent" />
      </BackgroundTasks>
    </Extension>
  </Extensions>
</Application>

Remarks

Note  If you are writing a lock screen-capable app, you also need to include LockScreen elements in the VisualElements section as described in How to show notifications on the lock screen.

 

App capability declarations

How to create a package manifest manually

How to register a background task

How to debug a background task

Guidelines and checklists for background tasks