How to declare background tasks in the application manifest (Windows Store apps using C#/VB/C++ and XAML)
Enable the use of background tasks by declaring them as extensions in the Windows Store 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.
- Microsoft Visual Studio Manifest Designer
- 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.
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>
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>
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:
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.
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>
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
Build date: 3/5/2013