Envoyer une notification toast locale à partir d’une application C#

  • Article

Une notification toast est un message que votre application peut construire et remettre à votre utilisateur alors qu’il ne se trouve pas actuellement dans votre application.

Capture d’écran d’une notification toast

Ce guide de démarrage rapide vous guide tout au long des étapes de création, de remise et d’affichage d’une notification toast Windows 10 ou Windows 11 à l’aide d’un contenu enrichi et d’actions interactives. Ce guide de démarrage rapide utilise des notifications locales, qui sont la notification la plus simple à implémenter. Tous les types d’applications (WPF, UWP, WinForms, console) peuvent envoyer des notifications !

Important

Si vous écrivez une application C++, consultez la documentation C++ UWP ou C++ WRL .

Étape 1 : Installer le package NuGet

Dans votre solution Visual Studio, cliquez avec le bouton droit sur votre projet, cliquez sur « Gérer les packages NuGet... », puis recherchez et installez le Microsoft.Toolkit.Uwp.Notificationspackage NuGet version 7.0 ou ultérieure.

Important

Les applications de bureau .NET Framework qui utilisent toujours packages.config doivent migrer vers PackageReference, sinon les kits SDK Windows ne seront pas référencés correctement. Dans votre projet, cliquez avec le bouton droit sur « Références », puis cliquez sur « Migrer packages.config vers PackageReference ».

Les applications WPF .NET Core 3.0 doivent être mises à jour vers .NET Core 3.1, sinon les API seront absentes.

Les applications .NET doivent utiliser l’un des modules tfms Windows, sinon les API d’envoi et de gestion toast telles que Show() seront manquantes. Définissez votre TFM sur net6.0-windows10.0.17763.0 ou version ultérieure.

Notre exemple de code utilisera ce package. Ce package vous permet de créer des notifications toast sans utiliser XML, et permet également aux applications de bureau d’envoyer des toasts.

Étape 2 : Envoyer un toast

Dans Windows 10 et Windows 11, le contenu de votre notification toast est décrit à l’aide d’un langage adaptatif qui offre une grande flexibilité quant à l’apparence de votre notification. Pour plus d’informations, consultez la documentation sur le contenu toast.

Nous allons commencer par une simple notification par texte. Construisez le contenu de la notification (à l’aide de la bibliothèque notifications) et affichez la notification ! Notez que l’espace de noms est Microsoft.Toolkit.Uwp.Notifications.

Notification texte simple 
// Requires Microsoft.Toolkit.Uwp.Notifications NuGet package version 7.0 or greater
new ToastContentBuilder()
    .AddArgument("action", "viewConversation")
    .AddArgument("conversationId", 9813)
    .AddText("Andrew sent you a picture")
    .AddText("Check this out, The Enchantments in Washington!")
    .Show(); // Not seeing the Show() method? Make sure you have version 7.0, and if you're using .NET 6 (or later), then your TFM must be net6.0-windows10.0.17763.0 or greater

Essayez d’exécuter ce code et vous devriez voir la notification s’afficher !

Étape 3 : Gestion de l’activation

Après avoir affiché une notification, vous devrez probablement gérer l’utilisateur qui clique sur la notification (qu’il s’agisse d’afficher du contenu spécifique après que l’utilisateur a cliqué dessus, d’ouvrir votre application en général ou d’effectuer une action quand l’utilisateur clique sur la notification).

Les étapes de gestion de l’activation diffèrent pour UWP et pour les applications de bureau empaquetées et non empaquetées.

Lorsque l’utilisateur clique sur votre notification (ou sur un bouton sur la notification avec activation au premier plan), l’application App.xaml.csOnActivated de votre application est appelée et les arguments que vous avez ajoutés sont retournés.

App.xaml.cs

protected override void OnActivated(IActivatedEventArgs e)
{
    // Handle notification activation
    if (e is ToastNotificationActivatedEventArgs toastActivationArgs)
    {
        // Obtain the arguments from the notification
        ToastArguments args = ToastArguments.Parse(toastActivationArgs.Argument);

        // Obtain any user input (text boxes, menu selections) from the notification
        ValueSet userInput = toastActivationArgs.UserInput;
 
        // TODO: Show the corresponding content
    }
}

Important

Vous devez initialiser votre frame et activer votre fenêtre comme votre code OnLaunched . OnLaunched n’est PAS appelé si l’utilisateur clique sur votre toast, même si votre application a été fermée et est lancée pour la première fois. Nous vous recommandons souvent de combiner OnLaunched et OnActivated dans votre propre OnLaunchedOrActivated méthode, car la même initialisation doit se produire dans les deux.

Étape 4 : Gestion de la désinstallation

Vous n’avez rien à faire ! Lorsque les applications UWP sont désinstallées, toutes les notifications et toutes les autres ressources associées sont automatiquement nettoyées.

Ajout d’images

Vous pouvez ajouter du contenu enrichi aux notifications. Nous allons ajouter une image inline et une image de profil (remplacement du logo de l’application).

Notes

Les images peuvent être utilisées à partir du package de l’application, du stockage local de l’application ou du web. À compter de fall Creators Update, les images web peuvent atteindre 3 Mo sur les connexions normales et 1 Mo sur les connexions limitées. Sur les appareils qui n’exécutent pas encore fall Creators Update, les images web ne doivent pas dépasser 200 Ko.

Important

Les images Http sont prises en charge uniquement dans les applications empaquetées qui ont la fonctionnalité Internet dans leur manifeste. Les applications non empaquetées ne prennent pas en charge les images HTTP ; vous devez télécharger l’image dans vos données d’application locales et les référencer localement.

Toast avec des images 
// Construct the content and show the toast!
new ToastContentBuilder()
    ...

    // Inline image
    .AddInlineImage(new Uri("https://picsum.photos/360/202?image=883"))

    // Profile (app logo override) image
    .AddAppLogoOverride(new Uri("ms-appdata:///local/Andrew.jpg"), ToastGenericAppLogoCrop.Circle)
    
    .Show();

Ajout de boutons et d’entrées

Vous pouvez ajouter des boutons et des entrées pour rendre vos notifications interactives. Les boutons peuvent lancer votre application au premier plan, un protocole ou votre tâche en arrière-plan. Nous allons ajouter une zone de texte de réponse, un bouton « J’aime » et un bouton « Afficher » qui ouvre l’image.

Capture d’écran d’une notification toast avec des entrées et des boutons 
int conversationId = 384928;

// Construct the content
new ToastContentBuilder()
    .AddArgument("conversationId", conversationId)
    ...

    // Text box for replying
    .AddInputTextBox("tbReply", placeHolderContent: "Type a response")

    // Buttons
    .AddButton(new ToastButton()
        .SetContent("Reply")
        .AddArgument("action", "reply")
        .SetBackgroundActivation())

    .AddButton(new ToastButton()
        .SetContent("Like")
        .AddArgument("action", "like")
        .SetBackgroundActivation())

    .AddButton(new ToastButton()
        .SetContent("View")
        .AddArgument("action", "viewImage")
        .AddArgument("imageUrl", image.ToString()))
    
    .Show();

L’activation des boutons de premier plan est gérée de la même façon que le corps toast main (votre App.xaml.cs OnActivated est appelé).

Notez que les arguments ajoutés au toast de niveau supérieur (comme l’ID de conversation) sont également retournés lorsque vous cliquez sur les boutons, tant que les boutons utilisent l’API AddArgument comme indiqué ci-dessus (si vous affectez des arguments personnalisés sur un bouton, les arguments de niveau supérieur ne seront pas inclus).

Gestion de l’activation en arrière-plan

Lorsque vous spécifiez l’activation en arrière-plan sur votre toast (ou sur un bouton à l’intérieur du toast), votre tâche en arrière-plan est exécutée au lieu d’activer votre application au premier plan.

Pour plus d’informations sur les tâches en arrière-plan, consultez Prise en charge de votre application avec des tâches en arrière-plan.

Si vous ciblez la build 14393 ou ultérieure, vous pouvez utiliser des tâches en arrière-plan in-process, ce qui simplifie considérablement les choses. Notez que les tâches en arrière-plan in-process ne peuvent pas s’exécuter sur les versions antérieures de Windows. Nous allons utiliser une tâche en arrière-plan in-process dans cet exemple de code.

const string taskName = "ToastBackgroundTask";

// If background task is already registered, do nothing
if (BackgroundTaskRegistration.AllTasks.Any(i => i.Value.Name.Equals(taskName)))
    return;

// Otherwise request access
BackgroundAccessStatus status = await BackgroundExecutionManager.RequestAccessAsync();

// Create the background task
BackgroundTaskBuilder builder = new BackgroundTaskBuilder()
{
    Name = taskName
};

// Assign the toast action trigger
builder.SetTrigger(new ToastNotificationActionTrigger());

// And register the task
BackgroundTaskRegistration registration = builder.Register();

Ensuite, dans votre app.xaml.cs, remplacez la méthode OnBackgroundActivated. Vous pouvez ensuite récupérer les arguments prédéfinis et l’entrée utilisateur, comme l’activation au premier plan.

App.xaml.cs

protected override async void OnBackgroundActivated(BackgroundActivatedEventArgs args)
{
    var deferral = args.TaskInstance.GetDeferral();
 
    switch (args.TaskInstance.Task.Name)
    {
        case "ToastBackgroundTask":
            var details = args.TaskInstance.TriggerDetails as ToastNotificationActionTriggerDetail;
            if (details != null)
            {
                ToastArguments arguments = ToastArguments.Parse(details.Argument);
                var userInput = details.UserInput;

                // Perform tasks
            }
            break;
    }
 
    deferral.Complete();
}

Définir une heure d’expiration

Dans Windows 10, toutes les notifications toast sont envoyées dans le Centre de notifications une fois qu’elles ont été ignorées ou ignorées par l’utilisateur, afin que les utilisateurs puissent consulter votre notification une fois la fenêtre contextuelle supprimée.

Toutefois, si le message de votre notification n’est pertinent que pour une période donnée, vous devez définir une heure d’expiration sur la notification toast afin que les utilisateurs ne voient pas les informations obsolètes de votre application. Par exemple, si une promotion n’est valide que pendant 12 heures, définissez le délai d’expiration sur 12 heures. Dans le code ci-dessous, nous définissons la durée d’expiration sur 2 jours.

Notes

La durée d’expiration par défaut et maximale des notifications toast locales est de 3 jours.

// Create toast content and show the toast!
new ToastContentBuilder()
    .AddText("Expires in 2 days...")
    .Show(toast =>
    {
        toast.ExpirationTime = DateTime.Now.AddDays(2);
    });

Fournissez une clé primaire pour votre toast

Si vous souhaitez supprimer ou remplacer par programmation la notification que vous envoyez, vous devez utiliser la propriété Tag (et éventuellement la propriété Group) pour fournir une clé primaire pour votre notification. Ensuite, vous pouvez utiliser cette clé primaire à l’avenir pour supprimer ou remplacer la notification.

Pour plus d’informations sur le remplacement/la suppression des notifications toast déjà remises, consultez Démarrage rapide : Gestion des notifications toast dans le centre de notifications (XAML) .

L’étiquette et le groupe combinés agissent comme une clé primaire composite. Group est l’identificateur le plus générique, où vous pouvez affecter des groupes tels que « wallPosts », « messages », « friendRequests », etc. La balise doit ensuite identifier de manière unique la notification elle-même à partir du groupe. En utilisant un groupe générique, vous pouvez ensuite supprimer toutes les notifications de ce groupe à l’aide de l’API RemoveGroup.

// Create toast content and show the toast!
new ToastContentBuilder()
    .AddText("New post on your wall!")
    .Show(toast =>
    {
        toast.Tag = "18365";
        toast.Group = "wallPosts";
    });

Effacer vos notifications

Les applications sont responsables de la suppression et de l’effacement de leurs propres notifications. Lorsque votre application est lancée, nous n’effacez PAS automatiquement vos notifications.

Windows supprime automatiquement une notification uniquement si l’utilisateur clique explicitement sur la notification.

Voici un exemple de ce qu’une application de messagerie doit faire...

  1. L’utilisateur reçoit plusieurs toasts sur les nouveaux messages dans une conversation
  2. L’utilisateur appuie sur l’un de ces toasts pour ouvrir la conversation
  3. L’application ouvre la conversation, puis efface tous les toasts pour cette conversation (à l’aide de RemoveGroup sur le groupe fourni par l’application pour cette conversation)
  4. Le Centre de notifications de l’utilisateur reflète désormais correctement l’état de notification, car il n’y a plus de notifications obsolètes pour cette conversation dans le Centre de notifications.

Pour en savoir plus sur l’effacement de toutes les notifications ou la suppression de notifications spécifiques, consultez Démarrage rapide : Gestion des notifications toast dans le centre de notifications (XAML) .

ToastNotificationManagerCompat.History.Clear();

Ressources