Envoyer une notification par vignette locale

Les vignettes d’application principales dans Windows 10 sont définies dans votre manifeste d’application, tandis que les vignettes secondaires sont créées par programme et définies par votre code d’application. Cet article explique comment envoyer une notification de vignette locale à une vignette principale et une vignette secondaire à l’aide de modèles de vignette adaptatifs. (Une notification locale est une notification envoyée à partir du code d’application par opposition à une notification push ou extraite à partir d’un serveur web.)

Installez le package NuGet

Nous vous recommandons d’installer le package NuGet de la bibliothèque notifications, ce qui simplifie les choses en générant des charges utiles de vignette avec des objets au lieu de xml brut.

Les exemples de code inline de cet article concernent C# à l’aide de 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 en vignette (vous devez installer le package NuGet de la bibliothèque notifications pour accéder à ces API).

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

Créer le contenu de notification

Dans Windows 10, les charges utiles de vignette sont définies à l’aide de modèles de vignette adaptatifs, ce qui vous permet 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 du contenu de vignette adaptatif 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 notification ressemble à ce qui suit lorsqu’il s’affiche sur 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 accepte un objet XmlDocument Windows Runtime, que vous pouvez obtenir à partir 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 de vignette et de badge locales n’expirent pas, tandis que les notifications Push, périodiques et planifiées expirent après trois jours. Étant donné que le contenu de vignette ne doit pas persister plus longtemps que nécessaire, il est recommandé de définir une heure d’expiration qui est logique pour votre application, en particulier sur les notifications de vignette et de badge locales.

Cet exemple de code crée une notification qui expire et sera supprimée de la vignette après dix minutes.

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

Envoyer la notification

Bien que l’envoi local d’une notification de vignette soit simple, l’envoi de la notification à une vignette primaire ou secondaire est un peu différent.

Vignette principale

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 ». Qu’elle soit visible ou non, la vignette principale de votre application existe toujours. Vous pouvez donc envoyer des notifications même lorsqu’elle n’est pas épinglée. Si l’utilisateur épingle ultérieurement votre vignette principale, les notifications que vous avez envoyées s’affichent.

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, vérifiez d’abord que la vignette secondaire existe. Si vous essayez de créer un générateur de mises à jour de vignettes pour une vignette secondaire qui n’existe pas (par exemple, si l’utilisateur n’a pas é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 un correctif 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 les notifications sur la vignette (facultatif)

Dans la plupart des cas, vous devez effacer une notification une fois que l’utilisateur a interagissant avec ce contenu. Par exemple, lorsque l’utilisateur lance votre application, vous souhaiterez peut-être effacer toutes les notifications de la vignette. Si vos notifications sont limitées dans le temps, nous vous recommandons de définir une heure d’expiration sur la notification au lieu d’effacer explicitement la notification.

Cet exemple de code efface la notification de vignette pour la vignette principale. Vous pouvez faire de même pour les vignettes secondaires en créant un générateur de mises à jour de vignettes pour la vignette secondaire.

TileUpdateManager.CreateTileUpdaterForApplication().Clear();

Pour une vignette avec la file d’attente de notification activée et les notifications dans la file d’attente, l’appel de la méthode Clear vide la file d’attente. Toutefois, vous ne pouvez pas effacer une notification via le serveur de votre application ; seul le code d’application local peut effacer les notifications.

Les notifications périodiques ou push peuvent uniquement ajouter de nouvelles notifications ou remplacer des notifications existantes. Un appel local à la méthode Clear efface la vignette si les notifications elles-mêmes ont été envoyées via 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 notification

Maintenant que vous avez effectué votre première mise à jour de vignette, vous pouvez développer les fonctionnalités de la vignette en activant une file d’attente de notification.

Autres méthodes de remise de notification

Cet article vous montre comment envoyer la mise à jour de vignette en tant que notification. Pour explorer d’autres méthodes de remise de notification, notamment planifiées, périodiques et push, consultez Remise de notifications.

Méthode de remise XmlEncode

Si vous n’utilisez pas la bibliothèque Notifications, cette méthode de remise de notification est une autre 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 bibliothèque de notifications

Si vous préférez utiliser du code XML brut au lieu du package NuGet de la bibliothèque notifications, utilisez ces exemples de code alternatifs pour les trois premiers exemples fournis dans cet article. Le reste des exemples de code peut être utilisé avec la bibliothèque Notifications ou avec 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 de 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 notification (XAML)
• Remise de notifications