Edit

Schedule a toast notification

  • Article

Scheduled toast notifications allow you to schedule a notification to appear at a later time, regardless of whether your app is running at that time. This is useful for scenarios like displaying reminders or other follow-up tasks for the user, where the time and content of the notification is known ahead-of-time.

Note that scheduled toast notifications have a delivery window of 5 minutes. If the computer is turned off during the scheduled delivery time, and remains off for longer than 5 minutes, the notification will be "dropped" as no longer relevant to the user. If you need guaranteed delivery of notifications regardless of how long the computer was off, we recommend using a background task with a time trigger, as illustrated in this code sample.

Important

Desktop applications (both packaged and unpackaged) have slightly different steps for sending notifications and handling activation. Follow along with the instructions below, however replace ToastNotificationManager with the DesktopNotificationManagerCompat class from the desktop apps documentation.

Important APIs: ScheduledToastNotification Class

Prerequisites

To fully understand this topic, the following will be helpful...

Step 1: Install NuGet package

Install the Microsoft.Toolkit.Uwp.Notifications NuGet package. Our code sample will use this package. At the end of the article we'll provide the "plain" code snippets that don't use any NuGet packages. This package allows you to create toast notifications without using XML.

Step 2: Add namespace declarations

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

Step 3: Schedule the notification

We'll use a simple text-based notification reminding a student about the homework they have due today. Construct the notification and schedule it!

// Construct the content and schedule the toast!
new ToastContentBuilder()
    .AddArgument("action", "viewItemsDueToday")
    .AddText("ASTR 170B1")
    .AddText("You have 3 items due today!");
    .Schedule(DateTime.Now.AddSeconds(5));

Provide a primary key for your toast

If you want to programmatically cancel, remove, or replace the scheduled notification, you need to use the Tag property (and optionally the Group property) to provide a primary key for your notification. Then, you can use this primary key in the future to cancel, remove, or replace the notification.

To see more details on replacing/removing already delivered toast notifications, please see Quickstart: Managing toast notifications in action center (XAML).

Tag and Group combined act as a composite primary key. Group is the more generic identifier, where you can assign groups like "wallPosts", "messages", "friendRequests", etc. And then Tag should uniquely identify the notification itself from within the group. By using a generic group, you can then remove all notifications from that group by using the RemoveGroup API.

// Construct the content and schedule the toast!
new ToastContentBuilder()
    .AddArgument("action", "viewItemsDueToday")
    .AddText("ASTR 170B1")
    .AddText("You have 3 items due today!");
    .Schedule(DateTime.Now.AddSeconds(5), toast =>
    {
        toast.Tag = "18365";
        toast.Group = "ASTR 170B1";
    });

Cancel scheduled notifications

To cancel a scheduled notification, you first have to retrieve the list of all scheduled notifications.

Then, find your scheduled toast matching the tag (and optionally group) you specified earlier, and call RemoveFromSchedule().

// Create the toast notifier
ToastNotifierCompat notifier = ToastNotificationManagerCompat.CreateToastNotifier();

// Get the list of scheduled toasts that haven't appeared yet
IReadOnlyList<ScheduledToastNotification> scheduledToasts = notifier.GetScheduledToastNotifications();

// Find our scheduled toast we want to cancel
var toRemove = scheduledToasts.FirstOrDefault(i => i.Tag == "18365" && i.Group == "ASTR 170B1");
if (toRemove != null)
{
    // And remove it from the schedule
    notifier.RemoveFromSchedule(toRemove);
}

Important

An unpackaged (lacks package identity at runtime) Win32 app must use the ToastNotificationManagerCompat class as seen above. If you use ToastNotificationManager itself, then you'll receive an element-not-found exception. All types of apps can use the Compat class, and it will work correctly.

Activation handling

See the send a local toast docs to learn more about handling activation. Activation of a scheduled toast notification is handled the same as activation of a local toast notification.

Adding actions, inputs, and more

See the send a local toast docs to learn more about advanced topics like actions and inputs. Actions and inputs work the same in local toasts as they do in scheduled toasts.

Resources