How to write a background task for raw push notifications (XAML)
This topic shows how to write a background task to receive background network notifications that use raw push notifications in a Windows Store app.
What you need to know
Technologies
-
Windows.Networking.PushNotifications
Enables background network communications using raw push notifications.
Prerequisites
-
The following information applies to any connected or network-aware Windows Store app that depends on network connections using raw push notifications to always be connected. This topic applies to apps written in C++/XAML and apps using the .NET Framework 4.5 in C#, VB.NET, or managed C++ on Windows 8 and Windows Server 2012.
Background network connectivity using raw push notifications is supported by a JavaScript app. For more information on background tasks that apply to JavaScript apps, see Supporting your app with background tasks. For information on background network connectivity supported by a JavaScript app, see Staying connected in the background (HTML).
Instructions
Step 1: Writing your background task
An important next step in making the app always reachable is to provide the app code that runs when a raw push notification occurs. For example, in the case of an email app that uses incoming raw push notifications to signal that new mail has arrived on the server, the app needs to run code to process the data in the raw push notification. This data might contain a list of new emails received to raise a notification to the user. An app might also schedule to connect to the email server and download the new emails from the server the next time the app is not longer suspended. This processing is done in the background task.
Every background task is implemented in its Run method, which is part of the IBackgroundTask interface. The Run method is part of the class that was created when an app registered for a raw push notification. This was specified as part of the BackgroundTaskBuilder.TaskEntryPoint in the app manifest.
The following sample show a Run method implemented as part of the class that uses raw push notifications.
using namespace BackgroundTasks; using namespace Windows::ApplicationModel::Background; using namespace Windows::Networking::PushNotifications; using namespace Windows::Storage; void SampleBackgroundTask::Run(IBackgroundTaskInstance^ taskInstance) { // Get the background task details auto settings = ApplicationData::Current->LocalSettings; auto taskName = taskInstance->Task->Name; // Store the content received from the notification so it can be retrieved from the UI auto notificationDetails = dynamic_cast<IRawNotification^>(taskInstance->TriggerDetails); settings->Values->Insert(taskName, notificationDetails->Content); }
The lifetime of the background task is controlled by the Run method. If an app exits the Run method, the app is suspended.
When an app background task is triggered, the operating system ensures that appropriate synchronization delivers the raw push notification data to the app or returns an error (connection aborted, for example). Similarly, at the end of the background task an app must ensure that any pending data is sent before the app is suspended.
When the background task triggers you will want to identify the corresponding raw push notification channel from the trigger details and interpret the content data received.
Although the background task is primarily targeted towards an app in the suspended state, an app configured with background tasks will also have these background tasks trigger when the app is in the foreground.
Step 2: Previous steps
For more information on how to create a lock screen app to receive background network notifications that use raw push notifications, see Quickstart: Create a lock screen app that uses background raw push notifications.
For more information on the process of registering a push notification channel and send it to your server, register a background task to activate from a raw push notification, and send a raw push notification to the channel and activate the background task, see How to use WNS to deliver raw push notifications to a lock screen app.
Step 3: Further steps
For more information on guidelines and checklists for using raw push notifications, see Guidelines and checklist for raw notifications.
Related topics
- Other resources
- Adding support for networking
- Background Networking
- How to use WNS to deliver raw push notifications to a lock screen app
- Lock screen overview
- Push notification overview
- How to create a lock screen app that uses background raw push notifications
- Staying connected in the background
- Supporting your app with background tasks
- Troubleshooting and debugging network connections
- Reference
- HttpClient
- HttpClientHandler
- IXMLHTTPRequest2
- System.Net.Http
- Windows.ApplicationModel.Background
- Windows.Networking.BackgroundTransfer
- Windows.Networking.PushNotifications
- Windows.Networking.Sockets
- Windows.Web.Http
- Samples
- Background task sample
- Lock screen apps sample
- Push and periodic notifications client-side sample
- Raw notifications sample