Envoyer une notification par vignette locale

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. 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. (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).

Notes

Découvrez comment créer des vignettes adaptatives et un schéma de contenu de vignette.

 

Installez le package NuGet

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.

Les exemples de code inclus dans cet article utilisent C# et la bibliothèque Notifications. (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.)

Ajout de déclarations d'espaces de noms

Pour accéder aux API de vignette, incluez l’espace de noms Windows.UI.Notifications . Nous vous recommandons également d’inclure l’espace de noms Microsoft.Toolkit.Uwp.Notifications afin que vous puissiez 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).

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

Créer le contenu d’une notification

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. (Pour savoir ce qui est possible avec les vignettes adaptatives, consultez Créer des vignettes adaptatives.)

Cet exemple de code crée le contenu de vignette adaptative pour les vignettes moyennes et larges.

// 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 :

Créer la notification

Une fois que vous avez votre contenu de notification, vous devez créer une nouvelle vignette 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.

Cet exemple de code crée une notification pour une nouvelle vignette.

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

Définir un délai d’expiration pour la notification (facultatif)

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. É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.

Cet exemple de code crée une notification qui arrive à expiration et est supprimée de la vignette au bout de 10 minutes.

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

Envoyer la 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.

Vignette principale

Pour envoyer une notification à une vignette principale, utilisez TileUpdateManager pour créer un updater de vignette pour la vignette principale, puis envoyez la notification en appelant « 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. Si l’utilisateur épingle votre vignette principale ultérieurement, les notifications que vous avez envoyées seront alors affichées.

Cet exemple de code envoie une notification à une vignette principale.

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

Vignette secondaire

Pour envoyer une notification à une vignette secondaire, assurez-vous d’abord que la vignette secondaire existe. 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. Vous pouvez utiliser SecondaryTile.Exists(tileId) pour découvrir si votre vignette secondaire est épinglée, puis créer une mise à jour de vignette pour la vignette secondaire et envoyer la notification.

Cet exemple de code envoie une notification à une vignette secondaire.

// 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);
}

Effacer des notifications sur la vignette (facultatif)

Dans la plupart des cas, vous devez effacer une notification une fois que l’utilisateur a interagi avec ce contenu. Par exemple, lorsque l’utilisateur lance votre application, il peut être judicieux d’effacer toutes les notifications de la vignette. 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.

Cet exemple de code supprime la notification de la vignette principale. Vous pouvez effectuer la même opération pour les vignettes secondaires en créant un outil de mise à jour pour la vignette secondaire.

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. Vous ne pouvez pas, cependant, effacer une notification via un serveur de votre application ; seul le code d’application local peut effacer des notifications.

Les notifications périodiques ou Push peuvent uniquement ajouter de nouvelles notifications ou remplacer les notifications existantes. 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. Les notifications planifiées qui n’ont pas encore été affichées ne sont pas effacées par cette méthode.

Étapes suivantes

Utilisation de la file d’attente de notifications

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.

Autres modes de remise des notifications

Cet article vous montre comment envoyer la mise à jour de vignette sous forme de 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.

Méthode de remise XmlEncode

Si vous n’utilisez pas la bibliothèque Notifications, ce mode de remise de notification représente une autre solution.

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 Notifications

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. Les exemples de code restants peuvent être utilisés avec la bibliothèque Notifications ou du code XML brut.

Ajout de déclarations d'espaces de noms

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

Créer le contenu d’une notification

// 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 notification

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

Rubriques connexes

• Créer des vignettes adaptatives
• Schéma de contenu de vignette
• Bibliothèque de notifications
• Exemple de code complet sur GitHub
• Espace de noms Windows.UI.Notifications
• Comment utiliser la file d’attente de notifications (XAML)
• Remise de notifications