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

  • 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 workers, and that your app registers each background task worker to respond to one or more triggers.

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 from the BackgroundTaskSample:


<Application Id="App" StartPage="default.html">
  <VisualElements DisplayName="BackgroundTask JS sample" Logo="images\squareTile-sdk.png" SmallLogo="images\smallTile-sdk.png" Description="BackgroundTask JS sample" ForegroundText="light" BackgroundColor="#00b2f0" ToastCapable="false">
    <LockScreen Notification="badgeAndTileText" BadgeLogo="images\badgelogo-sdk.png" />
    <DefaultTile ShortName="BGTask JS" ShowName="allLogos" WideLogo="images\tile-sdk.png" />
    <SplashScreen BackgroundColor="#00b2f0" Image="images\splash-sdk.png" />
  </VisualElements>

  <Extensions>

    <!-- In the next step, we'll 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).


<Application Id="App" StartPage="default.html">
  <VisualElements DisplayName="BackgroundTask JS sample" Logo="images\squareTile-sdk.png" SmallLogo="images\smallTile-sdk.png" Description="BackgroundTask JS sample" ForegroundText="light" BackgroundColor="#00b2f0" ToastCapable="false">
    <LockScreen Notification="badgeAndTileText" BadgeLogo="images\badgelogo-sdk.png" />
    <DefaultTile ShortName="BGTask JS" ShowName="allLogos" WideLogo="images\tile-sdk.png" />
    <SplashScreen BackgroundColor="#00b2f0" Image="images\splash-sdk.png" />
  </VisualElements>

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

</Application>

  1. Change the EntryPoint attribute to have the same string used to register your background task (path.filename).

    In this example, the entry point is Tasks.SampleBackgroundTask:

    
<Extension Category="windows.backgroundTasks" StartPage="js\backgroundtask.js">

  2. Change the 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 with 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 the SystemEventTrigger:

    
<Task Type="systemEvent" />

    Note  In JavaScript, it is not necessary (or even applicable) to use the Executable element. All JavaScript background workers run in the default system-provided host.

     

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 3 background tasks. Copy the Extensions section of this example, and modify it as needed, to declare background tasks in your application manifest.

<Application Id="App" StartPage="default.html">
  <VisualElements DisplayName="BackgroundTask JS sample" Logo="images\squareTile-sdk.png" SmallLogo="images\smallTile-sdk.png" Description="BackgroundTask JS sample" ForegroundText="light" BackgroundColor="#00b2f0" ToastCapable="false">
    <LockScreen Notification="badgeAndTileText" BadgeLogo="images\badgelogo-sdk.png" />
    <DefaultTile ShortName="BGTask JS" ShowName="allLogos" WideLogo="images\tile-sdk.png" />
    <SplashScreen BackgroundColor="#00b2f0" Image="images\splash-sdk.png" />
  </VisualElements>
  <Extensions>
    <Extension Category="windows.backgroundTasks" StartPage="js\backgroundtask.js">
      <BackgroundTasks>
        <Task Type="systemEvent" />
      </BackgroundTasks>
    </Extension>
    <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>

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