TileUpdater TileUpdater TileUpdater TileUpdater Class

Changes the content of the specific tile that the updater is bound to.

Syntax

Declaration

public sealed class TileUpdaterpublic sealed class TileUpdaterPublic NotInheritable Class TileUpdater

Remarks

To get an instance of this object, call the CreateTileUpdaterForApplication() or CreateTileUpdaterForSecondaryTile(System.String) method.

When it is created, TileUpdater is bound to a specific app or secondary tile, so the methods of this class affect only the single tile that the object instance is bound to.

Examples

The following example shows Update(Windows.UI.Notifications.TileNotification) used to send a notification to the app's tile.


function sendTileTextNotification() {
    var Notifications = Windows.UI.Notifications;

    // Get an XML DOM version of a specific template by using getTemplateContent.
    var tileXml = Notifications.TileUpdateManager.getTemplateContent(Notifications.TileTemplateType.tileWide310x150Text03);

    // You will need to look at the template documentation to know how many text fields a particular template has.
    // Get the text attribute for this template and fill it in.
    var tileAttributes = tileXml.getElementsByTagName("text");
    tileAttributes[0].appendChild(tileXml.createTextNode("Hello World!"));

    // Create the notification from the XML.
    var tileNotification = new Notifications.TileNotification(tileXml);

    // Send the notification to the calling app's tile.
    Notifications.TileUpdateManager.createTileUpdaterForApplication().update(tileNotification);
}

The following line of code uses EnableNotificationQueue(System.Boolean) to enable the notification queue for the calling app's tile.


Windows.UI.Notifications.TileUpdateManager.createTileUpdaterForApplication().enableNotificationQueue(true);

The following example shows the use of the RemoveFromSchedule(Windows.UI.Notifications.ScheduledTileNotification) method.


var notifier = Notifications.TileUpdateManager.createTileUpdaterForApplication();
var scheduled = notifier.getScheduledTileNotifications();

for (var i = 0, len = scheduled.length; i < len; i++) {

    // The itemId value is the unique ScheduledTileNotification.Id assigned to the 
    // notification when it was created.
    if (scheduled[i].id === itemId) {
        notifier.removeFromSchedule(scheduled[i]);
    }
}

Properties summary

Gets a value that specifies whether a tile can be updated through notifications.

Methods summary

Adds a ScheduledTileNotification to the schedule.

Removes all updates and causes the tile to display its default content as declared in the app's manifest.

Enables the tile to queue up to five notifications. This enables the notification queue on all tile sizes.

Enables the tile to queue up to five notifications on the medium tile.

Enables the tile to queue up to five notifications on the large tile.

Enables the tile to queue up to five notifications on the wide tile.

Retrieves a list of scheduled updates to the tile.

Removes an upcoming tile update from the schedule.

Begins a series of timed updates for the tile that the updater is bound to. Update content is retrieved from a specified Uniform Resource Identifier (URI). Updates begin at a specified time.

Begins a series of timed content changes for the tile that the updater is bound to, beginning immediately.

Begins a series of timed updates that cycle on the tile that the updater is bound to. Update content is retrieved from an array of specified Uniform Resource Identifier (URI) with updates beginning at a specified time and subsequent updates occurring at the periodic interval thereafter.

Note

To use this feature, you must first enable the tile's notification queue by calling EnableNotificationQueue(System.Boolean).

Begins a series of timed updates that cycle on the tile that the updater is bound to. Update content is retrieved from an array of specified Uniform Resource Identifier (URI), the first update happening immediately and subsequent updates occurring at the periodic interval thereafter.

Note

To use this feature, you must first enable the tile's notification queue by calling EnableNotificationQueue(System.Boolean).

Cancels the current series of timed updates for the tile that the updater is bound to.

Applies a change in content or appearance to the tile.

Properties

  • Setting
    Setting
    Setting
    Setting

    Gets a value that specifies whether a tile can be updated through notifications.

    public NotificationSetting Setting { get; }public NotificationSetting Setting { get; }Public ReadOnly Property Setting As NotificationSetting

    Property Value

    Remarks

Methods

  • AddToSchedule(Windows.UI.Notifications.ScheduledTileNotification)
    AddToSchedule(Windows.UI.Notifications.ScheduledTileNotification)
    AddToSchedule(Windows.UI.Notifications.ScheduledTileNotification)
    AddToSchedule(Windows.UI.Notifications.ScheduledTileNotification)

    Adds a ScheduledTileNotification to the schedule.

    public void AddToSchedule(Windows.UI.Notifications.ScheduledTileNotification)public void AddToSchedule(Windows.UI.Notifications.ScheduledTileNotification)Public Function AddToSchedule(Windows.UI.Notifications.ScheduledTileNotification) As void

    Parameters

    Remarks

    If your call to this method returns a failure code, examine these possible causes:

    • Possible cause: You've exceeded the maximum allowed number of scheduled notifications.

    Fix: AddToSchedule(Windows.UI.Notifications.ScheduledTileNotification) will fail if you attempt to schedule more than 4096 notifications. Reduce your number of scheduled notifications.

    • Possible cause: Your notification is scheduled for a time in the past relative to the current system clock time.

    Fix: Make sure that the scheduled notification time is in the future. Examine the system clock time.

  • Clear()
    Clear()
    Clear()
    Clear()

    Removes all updates and causes the tile to display its default content as declared in the app's manifest.

    public void Clear()public void Clear()Public Function Clear() As void

    Remarks

    Note

    This method does not stop periodic updates. If your tile is using periodic updates, you must also call StopPeriodicUpdate() to prevent further updates.

  • EnableNotificationQueue(System.Boolean)
    EnableNotificationQueue(System.Boolean)
    EnableNotificationQueue(System.Boolean)
    EnableNotificationQueue(System.Boolean)

    Enables the tile to queue up to five notifications. This enables the notification queue on all tile sizes.

    public void EnableNotificationQueue(System.Boolean)public void EnableNotificationQueue(System.Boolean)Public Function EnableNotificationQueue(System.Boolean) As void

    Parameters

    • enable
      System.Boolean
      System.Boolean
      System.Boolean
      System.Boolean

      True to enable queuing; otherwise false.

    Remarks

    When queuing is enabled, a maximum of five tile notifications can automatically cycle on the tile. Be careful about enabling cycling unless your app explicitly wants to use it, otherwise you can potentially have outdated notifications cycling through. Generally, the queue is FIFO (first in, first out), so that when it is full and a new notification arrives, the oldest notification is removed. However, notifications can be given a Tag, which allows a new notification with that same Tag to replace its older notification in the queue, regardless of its position.

    When your tile is based on a peek template, notification cycling is timed so that the full content is always shown before the tile cycles to the next notification.

    As of Windows 8.1, you can also enable the notification queue for only specific tile sizes. See the following topics:

    Examples

    The following line of code enables the notification queue for the calling app's tile.

    
    Windows.UI.Notifications.TileUpdateManager.createTileUpdaterForApplication().enableNotificationQueue(true);
    
  • EnableNotificationQueueForSquare150x150(System.Boolean)
    EnableNotificationQueueForSquare150x150(System.Boolean)
    EnableNotificationQueueForSquare150x150(System.Boolean)
    EnableNotificationQueueForSquare150x150(System.Boolean)

    Enables the tile to queue up to five notifications on the medium tile.

    public void EnableNotificationQueueForSquare150x150(System.Boolean)public void EnableNotificationQueueForSquare150x150(System.Boolean)Public Function EnableNotificationQueueForSquare150x150(System.Boolean) As void

    Parameters

    • enable
      System.Boolean
      System.Boolean
      System.Boolean
      System.Boolean

      True to enable queuing on this tile size; otherwise false.

  • EnableNotificationQueueForSquare310x310(System.Boolean)
    EnableNotificationQueueForSquare310x310(System.Boolean)
    EnableNotificationQueueForSquare310x310(System.Boolean)
    EnableNotificationQueueForSquare310x310(System.Boolean)

    Enables the tile to queue up to five notifications on the large tile.

    public void EnableNotificationQueueForSquare310x310(System.Boolean)public void EnableNotificationQueueForSquare310x310(System.Boolean)Public Function EnableNotificationQueueForSquare310x310(System.Boolean) As void

    Parameters

    • enable
      System.Boolean
      System.Boolean
      System.Boolean
      System.Boolean

      True to enable queuing on this tile size; otherwise false.

    Remarks

    We recommend that you disable the notification queu when using a large tile with one of the following templates, which already show three notifications simultaneously. This avoids a tile that's distractingly busy to the user.

  • EnableNotificationQueueForWide310x150(System.Boolean)
    EnableNotificationQueueForWide310x150(System.Boolean)
    EnableNotificationQueueForWide310x150(System.Boolean)
    EnableNotificationQueueForWide310x150(System.Boolean)

    Enables the tile to queue up to five notifications on the wide tile.

    public void EnableNotificationQueueForWide310x150(System.Boolean)public void EnableNotificationQueueForWide310x150(System.Boolean)Public Function EnableNotificationQueueForWide310x150(System.Boolean) As void

    Parameters

    • enable
      System.Boolean
      System.Boolean
      System.Boolean
      System.Boolean

      True to enable queuing on this tile size; otherwise false.

  • GetScheduledTileNotifications()
    GetScheduledTileNotifications()
    GetScheduledTileNotifications()
    GetScheduledTileNotifications()

    Retrieves a list of scheduled updates to the tile.

    public IVectorView<ScheduledTileNotification> GetScheduledTileNotifications()public IVectorView<ScheduledTileNotification> GetScheduledTileNotifications()Public Function GetScheduledTileNotifications() As IVectorView( Of ScheduledTileNotification )

    Returns

    • The collection of scheduled updates for this tile.

  • RemoveFromSchedule(Windows.UI.Notifications.ScheduledTileNotification)
    RemoveFromSchedule(Windows.UI.Notifications.ScheduledTileNotification)
    RemoveFromSchedule(Windows.UI.Notifications.ScheduledTileNotification)
    RemoveFromSchedule(Windows.UI.Notifications.ScheduledTileNotification)

    Removes an upcoming tile update from the schedule.

    public void RemoveFromSchedule(Windows.UI.Notifications.ScheduledTileNotification)public void RemoveFromSchedule(Windows.UI.Notifications.ScheduledTileNotification)Public Function RemoveFromSchedule(Windows.UI.Notifications.ScheduledTileNotification) As void

    Parameters

    Remarks

    Examples

    The following example shows the use of the RemoveFromSchedule(Windows.UI.Notifications.ScheduledTileNotification) method.

    
    var notifier = Notifications.TileUpdateManager.createTileUpdaterForApplication();
    var scheduled = notifier.getScheduledTileNotifications();
    
    for (var i = 0, len = scheduled.length; i < len; i++) {
    
        // The itemId value is the unique ScheduledTileNotification.Id assigned to the 
        // notification when it was created.
        if (scheduled[i].id === itemId) {
            notifier.removeFromSchedule(scheduled[i]);
        }
    }
    
  • StartPeriodicUpdate(Windows.Foundation.Uri,Windows.Foundation.DateTime,Windows.UI.Notifications.PeriodicUpdateRecurrence)
    StartPeriodicUpdate(Windows.Foundation.Uri,Windows.Foundation.DateTime,Windows.UI.Notifications.PeriodicUpdateRecurrence)
    StartPeriodicUpdate(Windows.Foundation.Uri,Windows.Foundation.DateTime,Windows.UI.Notifications.PeriodicUpdateRecurrence)
    StartPeriodicUpdate(Windows.Foundation.Uri,Windows.Foundation.DateTime,Windows.UI.Notifications.PeriodicUpdateRecurrence)

    Begins a series of timed updates for the tile that the updater is bound to. Update content is retrieved from a specified Uniform Resource Identifier (URI). Updates begin at a specified time.

    public void StartPeriodicUpdate(Windows.Foundation.Uri,Windows.Foundation.DateTime,Windows.UI.Notifications.PeriodicUpdateRecurrence)public void StartPeriodicUpdate(Windows.Foundation.Uri,Windows.Foundation.DateTime,Windows.UI.Notifications.PeriodicUpdateRecurrence)Public Function StartPeriodicUpdate(Windows.Foundation.Uri,Windows.Foundation.DateTime,Windows.UI.Notifications.PeriodicUpdateRecurrence) As void

    Parameters

  • StartPeriodicUpdate(Windows.Foundation.Uri,Windows.UI.Notifications.PeriodicUpdateRecurrence)
    StartPeriodicUpdate(Windows.Foundation.Uri,Windows.UI.Notifications.PeriodicUpdateRecurrence)
    StartPeriodicUpdate(Windows.Foundation.Uri,Windows.UI.Notifications.PeriodicUpdateRecurrence)
    StartPeriodicUpdate(Windows.Foundation.Uri,Windows.UI.Notifications.PeriodicUpdateRecurrence)

    Begins a series of timed content changes for the tile that the updater is bound to, beginning immediately.

    public void StartPeriodicUpdate(Windows.Foundation.Uri,Windows.UI.Notifications.PeriodicUpdateRecurrence)public void StartPeriodicUpdate(Windows.Foundation.Uri,Windows.UI.Notifications.PeriodicUpdateRecurrence)Public Function StartPeriodicUpdate(Windows.Foundation.Uri,Windows.UI.Notifications.PeriodicUpdateRecurrence) As void

    Parameters

  • StartPeriodicUpdateBatch(Windows.Foundation.Collections.IIterable{Windows.Foundation.Uri},Windows.Foundation.DateTime,Windows.UI.Notifications.PeriodicUpdateRecurrence)
    StartPeriodicUpdateBatch(Windows.Foundation.Collections.IIterable{Windows.Foundation.Uri},Windows.Foundation.DateTime,Windows.UI.Notifications.PeriodicUpdateRecurrence)
    StartPeriodicUpdateBatch(Windows.Foundation.Collections.IIterable{Windows.Foundation.Uri},Windows.Foundation.DateTime,Windows.UI.Notifications.PeriodicUpdateRecurrence)
    StartPeriodicUpdateBatch(Windows.Foundation.Collections.IIterable{Windows.Foundation.Uri},Windows.Foundation.DateTime,Windows.UI.Notifications.PeriodicUpdateRecurrence)

    Begins a series of timed updates that cycle on the tile that the updater is bound to. Update content is retrieved from an array of specified Uniform Resource Identifier (URI) with updates beginning at a specified time and subsequent updates occurring at the periodic interval thereafter.

    Note

    To use this feature, you must first enable the tile's notification queue by calling EnableNotificationQueue(System.Boolean).

    public void StartPeriodicUpdateBatch(Windows.Foundation.Collections.IIterable{Windows.Foundation.Uri},Windows.Foundation.DateTime,Windows.UI.Notifications.PeriodicUpdateRecurrence)public void StartPeriodicUpdateBatch(Windows.Foundation.Collections.IIterable{Windows.Foundation.Uri},Windows.Foundation.DateTime,Windows.UI.Notifications.PeriodicUpdateRecurrence)Public Function StartPeriodicUpdateBatch(Windows.Foundation.Collections.IIterable{Windows.Foundation.Uri},Windows.Foundation.DateTime,Windows.UI.Notifications.PeriodicUpdateRecurrence) As void

    Parameters

    • tileContents

      An array of up to five Uniform Resource Identifier (URI) from which the XML content of the cycling tile updates will be retrieved. If the array contains more than five Uniform Resource Identifier (URI), the method will fail.

    • startTime

      The time at which the initial Uniform Resource Identifier (URI) should first be polled for new content.

    • requestedInterval

      The frequency with which the Uniform Resource Identifier (URI) is polled for new tile content, following the initial update at startTime.

    Remarks

    Using the notification queue with periodic updates

    To use the notification queue, you must first enable it for your tile with this line of code:

    Windows.UI.Notifications.TileUpdateManager.createTileUpdaterForApplication().enableNotificationQueue(true);
    

    This API only needs to be called once in your app's lifetime, but there is no harm in calling it each time the app launches.

    In the case of periodic notifications, a unique URL is provided for each notification. Each URL is polled on a periodic basis by Windows for updated notification content. The content payload returned from each URL should contain versions of the notification XML for all supported tile sizes. Each polled URL also can optionally return its own unique expiration time and tag value.

    Tagging notifications for periodic updates

    With the notification queue enabled, your tile can cycle through a maximum of five queued notifications. Generally, the oldest notification is replaced in the queue when a new notification arrives. However, notifications can be given a tag so that a new notification with a specific tag will replace an older notification with the same tag, regardless of its place in the queue.

    Tags are optional strings of up to 16 characters that can be set on a notification as an identifier. If a new notification arrives with the same tag as a notification already in the queue, the new notification replaces the old one rather than falling under the default first-in, first-out queue behavior. This prevents the case where two versions of the same notification— one of them out-of-date— are present in the queue at the same time.

    In the case of periodic notifications, tags are provided in the X-WNS-Tag header of the notification's HTTP response message, which also includes the notification's content. This message is sent in response to the system's periodic call to the notification's Uniform Resource Identifier (URI). The header name and the tag value are case-insensitive.

    An example is shown here:

    X-WNS-Tag: stockMSFT
    

    Setting an expiration time for periodic updates

    Tiles expire by default after three days. If your notification content has a significantly different useful lifespan— shorter or longer— you should explicitly set an expiration time for each notification. This prevents stale or irrelevant content from remaining in the queue. This is especially important if the user's machine loses Internet connectivity for a long period of time.

    For example, during active trading, it would be advisable for a stock app to set the expiration on a stock price notification to twice that of your polling interval, such as a notification that expires one hour after it is sent if you poll for an update every half-hour. In the case of a news app, an expiration of one day for a tile that shows the top daily news would be appropriate.

    For periodic notifications, the expiration time is set in the X-WNS-Expires header of the notification's HTTP response message. The expiration time is expressed as an HTTP-date, which uses one of the formats shown in these examples:

    • Sun, 06 Nov 1994 08:49:37 GMT
    • Sunday, 06-Nov-94 08:49:37 GMT
    • Sun Nov 6 08:49:37 1994

    For more information on the HTTP-date format, see the World Wide Web Consortium (W3C) 3 Protocol Parameters document.

    For an example of a full implementation of periodic notifications used in conjunction with the notification queue, see Scenario 3 in the Push and periodic notifications sample.

  • StartPeriodicUpdateBatch(Windows.Foundation.Collections.IIterable{Windows.Foundation.Uri},Windows.UI.Notifications.PeriodicUpdateRecurrence)
    StartPeriodicUpdateBatch(Windows.Foundation.Collections.IIterable{Windows.Foundation.Uri},Windows.UI.Notifications.PeriodicUpdateRecurrence)
    StartPeriodicUpdateBatch(Windows.Foundation.Collections.IIterable{Windows.Foundation.Uri},Windows.UI.Notifications.PeriodicUpdateRecurrence)
    StartPeriodicUpdateBatch(Windows.Foundation.Collections.IIterable{Windows.Foundation.Uri},Windows.UI.Notifications.PeriodicUpdateRecurrence)

    Begins a series of timed updates that cycle on the tile that the updater is bound to. Update content is retrieved from an array of specified Uniform Resource Identifier (URI), the first update happening immediately and subsequent updates occurring at the periodic interval thereafter.

    Note

    To use this feature, you must first enable the tile's notification queue by calling EnableNotificationQueue(System.Boolean).

    public void StartPeriodicUpdateBatch(Windows.Foundation.Collections.IIterable{Windows.Foundation.Uri},Windows.UI.Notifications.PeriodicUpdateRecurrence)public void StartPeriodicUpdateBatch(Windows.Foundation.Collections.IIterable{Windows.Foundation.Uri},Windows.UI.Notifications.PeriodicUpdateRecurrence)Public Function StartPeriodicUpdateBatch(Windows.Foundation.Collections.IIterable{Windows.Foundation.Uri},Windows.UI.Notifications.PeriodicUpdateRecurrence) As void

    Parameters

    • tileContents

      An array of up to five Uniform Resource Identifier (URI) from which the XML content of the cycling tile updates will be retrieved. If the array contains more than five Uniform Resource Identifier (URI), the method will fail.

    • requestedInterval

      The frequency with which the Uniform Resource Identifier (URI) is polled for new tile content, following the initial update at startTime.

    Remarks

    Using the notification queue with periodic updates

    To use the notification queue, you must first enable it for your tile with this line of code:

    Windows.UI.Notifications.TileUpdateManager.createTileUpdaterForApplication().enableNotificationQueue(true);
    

    This API only needs to be called once in your app's lifetime, but there is no harm in calling it each time the app launches.

    In the case of periodic notifications, a unique URL is provided for each notification. Each URL is polled on a periodic basis by Windows for updated notification content. The content payload returned from each URL should contain versions of the notification XML for all supported tile sizes. Each polled URL also can optionally return its own unique expiration time and tag value.

    Tagging notifications for periodic updates

    With the notification queue enabled, your tile can cycle through a maximum of five queued notifications. Generally, the oldest notification is replaced in the queue when a new notification arrives. However, notifications can be given a tag so that a new notification with a specific tag will replace an older notification with the same tag, regardless of its place in the queue.

    Tags are optional strings of up to 16 characters that can be set on a notification as an identifier. If a new notification arrives with the same tag as a notification already in the queue, the new notification replaces the old one rather than falling under the default first-in, first-out queue behavior. This prevents the case where two versions of the same notification— one of them out-of-date— are present in the queue at the same time.

    In the case of periodic notifications, tags are provided in the X-WNS-Tag header of the notification's HTTP response message, which also includes the notification's content. This message is sent in response to the system's periodic call to the notification's Uniform Resource Identifier (URI). The header name and the tag value are case-insensitive.

    An example is shown here:

    X-WNS-Tag: stockMSFT
    

    Setting an expiration time for periodic updates

    Periodic notifications expire by default after three days. If your notification content has a significantly different useful lifespan— shorter or longer— you should explicitly set an expiration time for each notification. This prevents stale or irrelevant content from remaining in the queue. This is especially important if the user's machine loses Internet connectivity for a long period of time.

    For example, during active trading, it would be advisable for a stock app to set the expiration on a stock price notification to twice that of your polling interval, such as a notification that expires one hour after it is sent if you poll for an update every half-hour. In the case of a news app, an expiration of one day for a tile that shows the top daily news would be appropriate.

    For periodic notifications, the expiration time is set in the X-WNS-Expires header of the notification's HTTP response message. The expiration time is expressed as an HTTP-date, which uses one of the formats shown in these examples:

    • Sun, 06 Nov 1994 08:49:37 GMT
    • Sunday, 06-Nov-94 08:49:37 GMT
    • Sun Nov 6 08:49:37 1994

    For more information on the HTTP-date format, see the World Wide Web Consortium (W3C) 3 Protocol Parameters document.

    For an example of a full implementation of periodic notifications used in conjunction with the notification queue, see Scenario 3 in the Push and periodic notifications sample.

  • StopPeriodicUpdate()
    StopPeriodicUpdate()
    StopPeriodicUpdate()
    StopPeriodicUpdate()

    Cancels the current series of timed updates for the tile that the updater is bound to.

    public void StopPeriodicUpdate()public void StopPeriodicUpdate()Public Function StopPeriodicUpdate() As void
  • Update(Windows.UI.Notifications.TileNotification)
    Update(Windows.UI.Notifications.TileNotification)
    Update(Windows.UI.Notifications.TileNotification)
    Update(Windows.UI.Notifications.TileNotification)

    Applies a change in content or appearance to the tile.

    public void Update(Windows.UI.Notifications.TileNotification)public void Update(Windows.UI.Notifications.TileNotification)Public Function Update(Windows.UI.Notifications.TileNotification) As void

    Parameters

    Remarks

    Examples

    The following example shows Update(Windows.UI.Notifications.TileNotification) used to send a notification to the app's tile.

    
    function sendTileTextNotification() {
        var Notifications = Windows.UI.Notifications;
    
        // Get an XML DOM version of a specific template by using getTemplateContent.
        var tileXml = Notifications.TileUpdateManager.getTemplateContent(Notifications.TileTemplateType.tileWide310x150Text03);
    
        // You will need to look at the template documentation to know how many text fields a particular template has.
        // Get the text attribute for this template and fill it in.
        var tileAttributes = tileXml.getElementsByTagName("text");
        tileAttributes[0].appendChild(tileXml.createTextNode("Hello World!"));
    
        // Create the notification from the XML.
        var tileNotification = new Notifications.TileNotification(tileXml);
    
        // Send the notification to the calling app's tile.
        Notifications.TileUpdateManager.createTileUpdaterForApplication().update(tileNotification);
    }
    

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.MuseAttribute

Details

Assembly

Windows.UI.Notifications.dll