Envoyer une notification par vignette localeSend a local tile notification

Les vignettes d’application principales de Windows 10 sont définies dans le manifeste de votre application, tandis que les vignettes secondaires sont créées et définies par programme par le code de votre application.Primary app tiles in Windows 10 are defined in your app manifest, while secondary tiles are programmatically created and defined by your app code. Cet article décrit comment envoyer une notification par vignette locale à une vignette principale et une vignette secondaire à l’aide de modèles de vignette adaptative.This article describes how to send a local tile notification to a primary tile and a secondary tile using adaptive tile templates. (Une notification locale est une notification envoyée à partir du code d’application, par opposition à une notification qui fait l’objet d’une transmission de type push ou pull à partir d’un serveur web).(A local notification is one that's sent from app code as opposed to one that's pushed or pulled from a web server.)

Vignette par défaut et vignette avec notification

 

Installez le package NuGetInstall the NuGet package

Nous vous recommandons d’installer le package NuGet de la bibliothèque Notifications qui simplifie les choses en générant les charges utiles de vignettes à l’aide d’objets au lieu de code XML brut.We recommend installing the Notifications library NuGet package, which simplifies things by generating tile payloads with objects instead of raw XML.

Les exemples de code inclus dans cet article utilisent C# et la bibliothèque Notifications.The inline code examples in this article are for C# using the Notifications library. (Si vous préférez créer votre propre code XML, vous trouverez des exemples de code sans la bibliothèque Notifications vers la fin de l’article.)(If you'd prefer to create your own XML, you can find code examples without the Notifications library toward the end of the article.)

Ajout de déclarations d'espaces de nomsAdd namespace declarations

Pour accéder aux API de vignettes, incluez l’espace de noms Windows. UI. notifications .To access the tile APIs, include the Windows.UI.Notifications namespace. Nous vous recommandons également d’inclure l’espace de noms Microsoft. Toolkit. UWP. notifications afin de pouvoir tirer parti de nos API d’assistance de vignettes (vous devez installer le package NuGet de la bibliothèque de notifications pour accéder à ces API).We also recommend including the Microsoft.Toolkit.Uwp.Notifications namespace so that you can take advantage of our tile helper APIs (you must install the Notifications library NuGet package to access these APIs).

using Windows.UI.Notifications;
using Microsoft.Toolkit.Uwp.Notifications; // Notifications library

Créer le contenu d’une notificationCreate the notification content

Dans Windows 10, les charges utiles de vignette sont définies à l’aide de modèles de vignette adaptative qui vous permettent de créer des dispositions visuelles personnalisées pour vos notifications.In Windows 10, tile payloads are defined using adaptive tile templates, which allow you to create custom visual layouts for your notifications. (Pour savoir ce qui est possible avec les vignettes adaptatives, consultez créer des vignettes adaptatives.)(To learn what's possible with adaptive tiles, see Create adaptive tiles.)

Cet exemple de code crée le contenu de vignette adaptative pour les vignettes moyennes et larges.This code example creates adaptive tile content for medium and wide tiles.

// In a real app, these would be initialized with actual data
string from = "Jennifer Parker";
string subject = "Photos from our trip";
string body = "Check out these awesome photos I took while in New Zealand!";
 
 
// Construct the tile content
TileContent content = new TileContent()
{
    Visual = new TileVisual()
    {
        TileMedium = new TileBinding()
        {
            Content = new TileBindingContentAdaptive()
            {
                Children =
                {
                    new AdaptiveText()
                    {
                        Text = from
                    },

                    new AdaptiveText()
                    {
                        Text = subject,
                        HintStyle = AdaptiveTextStyle.CaptionSubtle
                    },

                    new AdaptiveText()
                    {
                        Text = body,
                        HintStyle = AdaptiveTextStyle.CaptionSubtle
                    }
                }
            }
        },

        TileWide = new TileBinding()
        {
            Content = new TileBindingContentAdaptive()
            {
                Children =
                {
                    new AdaptiveText()
                    {
                        Text = from,
                        HintStyle = AdaptiveTextStyle.Subtitle
                    },

                    new AdaptiveText()
                    {
                        Text = subject,
                        HintStyle = AdaptiveTextStyle.CaptionSubtle
                    },

                    new AdaptiveText()
                    {
                        Text = body,
                        HintStyle = AdaptiveTextStyle.CaptionSubtle
                    }
                }
            }
        }
    }
};

Le contenu de la notification se présente comme suit pour une vignette moyenne :The notification content looks like the following when displayed on a medium tile:

Contenu de la notification sur une vignette moyenne

Créer la notificationCreate the notification

Une fois que vous avez votre contenu de notification, vous devez créer un nouveau TileNotification.Once you have your notification content, you'll need to create a new TileNotification. Le constructeur TileNotification prend un objet Windows Runtime XmlDocument que vous pouvez obtenir de la méthode TileContent.GetXml si vous utilisez la bibliothèque Notifications.The TileNotification constructor takes a Windows Runtime XmlDocument object, which you can obtain from the TileContent.GetXml method if you're using the Notifications library.

Cet exemple de code crée une notification pour une nouvelle vignette.This code example creates a notification for a new tile.

// Create the tile notification
var notification = new TileNotification(content.GetXml());

Définir un délai d’expiration pour la notification (facultatif)Set an expiration time for the notification (optional)

Par défaut, les notifications locales par vignette et de badge n’expirent pas, alors que les notifications Push, périodiques et planifiées expirent après trois jours.By default, local tile and badge notifications don't expire, while push, periodic, and scheduled notifications expire after three days. Étant donné que le contenu de la vignette ne doit pas être conservé plus longtemps que nécessaire, il est recommandé de définir un délai d’expiration approprié pour votre application, en particulier sur les notifications locales par vignette et de badge.Because tile content shouldn't persist longer than necessary, it's a best practice to set an expiration time that makes sense for your app, especially on local tile and badge notifications.

Cet exemple de code crée une notification qui arrive à expiration et est supprimée de la vignette au bout de 10 minutes.This code example creates a notification that expires and will be removed from the tile after ten minutes.

tileNotification.ExpirationTime = DateTimeOffset.UtcNow.AddMinutes(10);

Envoyer la notificationSend the notification

Bien que l’envoi local d’une notification par vignette soit simple, l’envoi de la notification à une vignette principale ou secondaire est légèrement différent.Although locally sending a tile notification is simple, sending the notification to a primary or secondary tile is a bit different.

Vignette principalePrimary tile

Pour envoyer une notification à une vignette principale, utilisez TileUpdateManager pour créer un programme de mise à jour de vignette pour la vignette principale et envoyez la notification en appelant « Update ».To send a notification to a primary tile, use the TileUpdateManager to create a tile updater for the primary tile, and send the notification by calling "Update". Qu’elle soit visible ou non, la vignette principale de votre application existe toujours ; vous pouvez donc lui envoyer des notifications même si elle n’est pas épinglée.Regardless of whether it's visible, your app's primary tile always exists, so you can send notifications to it even when it's not pinned. Si l’utilisateur épingle votre vignette principale ultérieurement, les notifications que vous avez envoyées seront alors affichées.If the user pins your primary tile later, the notifications that you sent will appear then.

Cet exemple de code envoie une notification à une vignette principale.This code example sends a notification to a primary tile.

// Send the notification to the primary tile
TileUpdateManager.CreateTileUpdaterForApplication().Update(notification);

Vignette secondaireSecondary tile

Pour envoyer une notification à une vignette secondaire, assurez-vous d’abord que la vignette secondaire existe.To send a notification to a secondary tile, first make sure that the secondary tile exists. Si vous essayez de créer une mise à jour pour une vignette secondaire qui n’existe pas (par exemple, si l’utilisateur a désépinglé la vignette secondaire), une exception est levée.If you try to create a tile updater for a secondary tile that doesn't exist (for example, if the user unpinned the secondary tile), an exception will be thrown. Vous pouvez utiliser SecondaryTile. Exists(tileId) pour déterminer si votre vignette secondaire est épinglée, puis créer un programme de mise à jour de vignette pour la vignette secondaire et envoyer la notification.You can use SecondaryTile.Exists(tileId) to discover if your secondary tile is pinned, and then create a tile updater for the secondary tile and send the notification.

Cet exemple de code envoie une notification à une vignette secondaire.This code example sends a notification to a secondary tile.

// If the secondary tile is pinned
if (SecondaryTile.Exists("MySecondaryTile"))
{
    // Get its updater
    var updater = TileUpdateManager.CreateTileUpdaterForSecondaryTile("MySecondaryTile");
 
    // And send the notification
    updater.Update(notification);
}

Vignette par défaut et vignette avec notification

Effacer des notifications sur la vignette (facultatif)Clear notifications on the tile (optional)

Dans la plupart des cas, vous devez effacer une notification une fois que l’utilisateur a interagi avec ce contenu.In most cases, you should clear a notification once the user has interacted with that content. Par exemple, lorsque l’utilisateur lance votre application, il peut être judicieux d’effacer toutes les notifications de la vignette.For example, when the user launches your app, you might want to clear all the notifications from the tile. Si vos modifications sont temporaires, nous vous recommandons de définir un délai d’expiration sur la notification au lieu de supprimer celle-ci explicitement.If your notifications are time-bound, we recommend that you set an expiration time on the notification instead of explicitly clearing the notification.

Cet exemple de code supprime la notification de la vignette principale.This code example clears the tile notification for the primary tile. Vous pouvez effectuer la même opération pour les vignettes secondaires en créant un outil de mise à jour pour la vignette secondaire.You can do the same for secondary tiles by creating a tile updater for the secondary tile.

TileUpdateManager.CreateTileUpdaterForApplication().Clear();

Si la file d’attente est activée pour une vignette et qu’il y a des notifications en attente, l’appel de la méthode Clear a pour effet de vider la file d’attente.For a tile with the notification queue enabled and notifications in the queue, calling the Clear method empties the queue. Vous ne pouvez pas, cependant, effacer une notification via un serveur de votre application ; seul le code d’application local peut effacer des notifications.You can't, however, clear a notification via your app's server; only the local app code can clear notifications.

Les notifications périodiques ou Push peuvent uniquement ajouter de nouvelles notifications ou remplacer les notifications existantes.Periodic or push notifications can only add new notifications or replace existing notifications. Un appel local à la méthode Clear effacera la vignette, que les notifications aient été fournies ou non par le biais push, périodique ou local.A local call to the Clear method will clear the tile whether or not the notifications themselves came via push, periodic, or local. Les notifications planifiées qui n’ont pas encore été affichées ne sont pas effacées par cette méthode.Scheduled notifications that haven't yet appeared are not cleared by this method.

Vignette avec notification et vignette après effacement

Étapes suivantesNext steps

Utilisation de la file d’attente de notificationsUsing the notification queue

Maintenant que vous avez réalisé votre première mise à jour de vignette, vous pouvez développer les fonctionnalités de la vignette en activant une file d’attente de notifications.Now that you have done your first tile update, you can expand the functionality of the tile by enabling a notification queue.

Autres modes de remise des notificationsOther notification delivery methods

Cet article vous montre comment envoyer la mise à jour de vignette sous forme de notification.This article shows you how to send the tile update as a notification. Pour découvrir d’autres modes de remise de notification, y compris les notifications planifiées, périodiques et Push, voir Remise de notifications.To explore other methods of notification delivery, including scheduled, periodic, and push, see Delivering notifications.

Méthode de remise XmlEncodeXmlEncode delivery method

Si vous n’utilisez pas la bibliothèque Notifications, ce mode de remise de notification représente une autre solution.If you're not using the Notifications library, this notification delivery method is another alternative.

public string XmlEncode(string text)
{
    StringBuilder builder = new StringBuilder();
    using (var writer = XmlWriter.Create(builder))
    {
        writer.WriteString(text);
    }

    return builder.ToString();
}

Exemples de code sans la bibliothèque NotificationsCode examples without Notifications library

Si vous préférez utiliser du code XML brut à la place du package NuGet de la bibliothèque Notifications, utilisez ces autres exemples de code pour les trois premiers exemples fournis dans cet article.If you prefer to work with raw XML instead of the Notifications library NuGet package, use these alternate code examples to first three examples provided in this article. Les exemples de code restants peuvent être utilisés avec la bibliothèque Notifications ou du code XML brut.The rest of the code examples can be used either with the Notifications library or with raw XML.

Ajout de déclarations d'espaces de nomsAdd namespace declarations

using Windows.UI.Notifications;
using Windows.Data.Xml.Dom;

Créer le contenu d’une notificationCreate the notification content

// In a real app, these would be initialized with actual data
string from = "Jennifer Parker";
string subject = "Photos from our trip";
string body = "Check out these awesome photos I took while in New Zealand!";
 
 
// TODO - all values need to be XML escaped
 
 
// Construct the tile content as a string
string content = $@"
<tile>
    <visual>
 
        <binding template='TileMedium'>
            <text>{from}</text>
            <text hint-style='captionSubtle'>{subject}</text>
            <text hint-style='captionSubtle'>{body}</text>
        </binding>
 
        <binding template='TileWide'>
            <text hint-style='subtitle'>{from}</text>
            <text hint-style='captionSubtle'>{subject}</text>
            <text hint-style='captionSubtle'>{body}</text>
        </binding>
 
    </visual>
</tile>";

Créer la notificationCreate the notification

// Load the string into an XmlDocument
XmlDocument doc = new XmlDocument();
doc.LoadXml(content);
 
// Then create the tile notification
var notification = new TileNotification(doc);