How to use the notification queue with local notifications (XAML)
Note Not using C#/VB/C++? See How to use the notification queue with local notifications (HTML).
This topic shows how to enable the notification queue on your tile. It also shows how to tag your notification before sending it, to avoid duplicate or out-of-date content in the queue. With the notification queue enabled, Windows will cycle through up to five notifications.
To see JavaScript versions of the examples given in this Quickstart, see How to use the notification queue with local notifications (JavaScript).
Note In this Quickstart you'll manipulate the notification content directly through the XML Document Object Model (DOM). An optional approach is available through the NotificationsExtensions library, which presents the XML content as object properties, including Intellisense. For more information, see Quickstart: Using the NotificationsExtensions library in your code. To see the code in this Quickstart expressed using NotificationsExtenstions, see the App tiles and badges sample.
What you need to know
Technologies
- Windows Runtime
Prerequisites
To understand this topic, you will need:
- A working knowledge of tile and notification terms and concepts. For more information, see Tiles, Badges, and Notifications.
- A familiarity with the tile XML schema. For more information, see Tile schema.
- The ability to create a basic Windows Store app with C# or C++ Microsoft Visual Basic using Windows Runtime APIs. For more information, see Create your first Windows Store app using C# or Visual Basic.
- An existing default tile for your app, defined in your app's manifest. For more information, see Quickstart: Creating a default tile using the Microsoft Visual Studio manifest editor.
- A familiarity with XML and its manipulation through Document Object Model (DOM) APIs.
Instructions
Step 1: Add namespace declarations
Windows.UI.Notifications includes the toast APIs.
using Windows.UI.Notifications;
using Windows.Data.Xml.Dom;
Step 2: Set the option to enable notification cycling
This code enables the notification queue for your app. This call only needs to be made once while the app is running, though there is no harm in calling it again. We recommend that you place this call in your app's initialization code. This ensures that the call is made before you update the tile locally, request a push notification channel, or start periodic updates for the tile.
TileUpdateManager.CreateTileUpdaterForApplication().EnableNotificationQueue(true);
Step 3: Create a tile notification
This is the first step in all tile notifications and is no different here than in any other situation; it is included here only for completeness. For more information, see Quickstart: Sending a tile update.
Note When GetTemplateContent is called on a Windows 8 system, it returns a version 1 template. When this method is called on a Windows 8.1 system, it returns a version 2 template or a version 3 template in case of phone-only templates. However, if an app specifies Windows 8 compatibility in its manifest, this method returns a version 1 template regardless of the Windows version. In this topic, we'll use a version 2 template.
TileUpdateManager.GetTemplateContent(TileTemplateType.TileWide310x150ImageAndText01);
XmlDocument tileXml = TileUpdateManager.GetTemplateContent(tileTemplate);
// TO DO: Fill in the template with your tile content. Define a tile and add it to tileXML.
TileNotification tileNotification = new TileNotification(tileXml);
Step 4: Give your notification a tag
A tag is a string of no more than 16 alphanumeric characters, plus a terminating null character, that uniquely identifies its notification within your app.
When queuing is enabled, a maximum of five tile notifications can automatically cycle on the tile. By default, the replacement policy for notifications in the queue is first in, first out (FIFO); when the queue is full and a new notification arrives, the oldest notification is removed. Note that the notification display order does not follow a strict linear pattern. Users can see the notifications in a different order than they arrived in.
To override the FIFO queue behavior, a notification can be given a tag. If a new notification arrives with the same tag as an existing notification, the new notification replaces the old, regardless of the older notification's place in the queue. For instance, if your tile shows stock prices, you want to show the most up-to-date info. The use of tags to replace notifications in the queue is optional.
For more information on using tags with the notification queue, see Using the notification queue. The example below shows how to set the tag for local notifications. For information on setting tags for periodic updates, see Tileupdater.StartPeriodicUpdateBatch. For information on setting tags for push notifications, see Push notification service request and response headers.
tileNotification.Tag = "stockMSFT";
Step 5: Send the notification to the tile
TileUpdateManager.CreateTileUpdaterForApplication().Update(tileNotification);
Related topics
Quickstart: Sending a tile update