This sample shows how to use raw notification, which are push notifications with no associated UI that performs a background task for the app. For example, a magazine app can download the latest issue in the background so that it is ready when the user subsequently switches to the app.
Note This sample was created using one of the universal app templates available in Visual Studio. It shows how its solution is structured so it can run on both Windows 8.1 and Windows Phone 8.1. For more info about how to build apps that target Windows and Windows Phone with Visual Studio, see Build apps that target Windows and Windows Phone 8.1 by using Visual Studio.
The sample demonstrates the following actions:
- Requesting access from the user to be allowed to run in the background (Windows only)
- Opening a channel URI through which the raw notifications will be sent
- Registering a background task for the raw notification
- Receiving a raw notification when your app is running and visible (Windows only)
- Unregistering a background task
To obtain an evaluation copy of Windows 8.1, go to Windows 8.1.
To obtain an evaluation copy of Microsoft Visual Studio 2013, go to Visual Studio 2013.
Related topics
Operating system requirements
| Client | |
|---|---|
| Server | |
| Phone |
Build the sample
- Start Microsoft Visual Studio 2013 Update 2 and select File > Open > Project/Solution.
- Go to the directory to which you unzipped the sample. Then go to the subdirectory named for the sample and double-click the Visual Studio 2013 Update 2 Solution (.sln) file.
- Follow the steps for the version of the sample you want:
-
To build the Windows version of the sample:
- Select RawNotifications.Windows in Solution Explorer.
- Press Ctrl+Shift+B, or use Build > Build Solution, or use Build > Build RawNotifications.Windows.
-
To build the Windows Phone version of the sample:
- Select RawNotifications.WindowsPhone in Solution Explorer.
- Press Ctrl+Shift+B or use Build > Build Solution or use Build > Build RawNotifications.WindowsPhone.
-
Run the sample
The next steps depend on whether you just want to deploy the sample or you want to both deploy and run it.
Deploying the sample
-
To deploy the built Windows version of the sample:
- Select RawNotifications.Windows in Solution Explorer.
- Use Build > Deploy Solution or Build > Deploy RawNotifications.Windows.
-
To deploy the built Windows Phone version of the sample:
- Select RawNotifications.WindowsPhone in Solution Explorer.
- Use Build > Deploy Solution or Build > Deploy RawNotifications.WindowsPhone.
Deploying and running the sample
-
To deploy and run the Windows version of the sample:
- Right-click RawNotifications.Windows in Solution Explorer and select Set as StartUp Project.
- To debug the sample and then run it, press F5 or use Debug > Start Debugging. To run the sample without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.
-
To deploy and run the Windows Phone version of the sample:
- Right-click RawNotifications.WindowsPhone in Solution Explorer and select Set as StartUp Project.
- To debug the sample and then run it, press F5 or use Debug > Start Debugging. To run the sample without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.
- Give it a few seconds to launch in the emulator, after which you can find the sample in the Apps list.
How to use the sample
For an app to be capable of performing background tasks, it must declare those background tasks in its app manifest file (package.appxmanifest). For a raw notification, you must declare the "Push notification" background task as this sample has done. In Visual Studio 2013 Update 2, this value is set in the Declarations page of the manifest editor, which sets the BackgroundTasks element in the package.appxmanifest file.
For raw notifications to work, your app tile must be able to receive notifications. Tile notifications can be disabled by a user for a single app or for all apps, or by a system administrator by using group policy.
An app is allowed to ask a user to grant background task access only one time. When you first run this sample and select Open a channel and register background task, a dialog box appears. Regardless of the answer you choose, because of the "ask only one time" rule, you will not see this dialog again unless you uninstall and reinstall the sample. When you choose Allow from the dialog box, the sample app is added to the lock screen because the two capabilities are set as a pair. However, because a raw notification does not include UI, you will not see a badge or tile text associated with a raw notification on the lock screen.
The channel URI that is returned is sent to your web server as it would be with any push notification, and any subsequent actions taken by the server to send a raw notification using that channel URI, are also no different than other push notifications. For more information, see the Push and periodic notifications sample.