App notification progress bar and data binding

Using a progress bar inside your app notification allows you to convey the status of long-running operations to the user, like downloads, video rendering, exercise goals, and more.

A progress bar inside an app notification can either be "indeterminate" (no specific value, animated dots indicate an operation is occurring) or "determinate" (a specific percent of the bar is filled, like 60%).

The image below shows a determinate progress bar with all of its corresponding properties labeled.

For more information about app notifications, see App notifications overview.

Use AppNotificationBuilder.AddProgressBar to add a progress bar to your notification. The following example generates the notification shown above.

var builder = new AppNotificationBuilder()
    .AddText("Downloading your weekly playlist...")
    .AddProgressBar(new AppNotificationProgressBar()
        .SetTitle("Weekly playlist")
        .SetValue(0.6)
        .SetValueStringOverride("15/26 songs")
        .SetStatus("Downloading..."));

To dynamically update the values of the progress bar, use data binding as described in the next section.

Update a progress bar with data binding

To display a live progress bar, use data binding to update the notification values without re-sending the entire notification.

1. Construct notification content with data-bound fields by calling the Bind methods on AppNotificationProgressBar.
2. Assign a Tag (and optionally a Group) to identify the notification.
3. Set the initial AppNotificationProgressData values.
4. Show the notification by calling AppNotificationManager.Default.Show.

using Microsoft.Windows.AppNotifications;
using Microsoft.Windows.AppNotifications.Builder;

string tag = "weekly-playlist";
string group = "downloads";

var builder = new AppNotificationBuilder()
    .AddText("Downloading your weekly playlist...")
    .AddProgressBar(new AppNotificationProgressBar()
        .BindTitle()
        .BindValue()
        .BindValueStringOverride()
        .BindStatus());

var notification = builder.BuildNotification();
notification.Tag = tag;
notification.Group = group;

notification.Progress = new AppNotificationProgressData(1)
{
    Title = "Weekly playlist",
    Value = 0.6,
    ValueStringOverride = "15/26 songs",
    Status = "Downloading..."
};

AppNotificationManager.Default.Show(notification);

Then, update the progress values by calling AppNotificationManager.Default.UpdateAsync with a new AppNotificationProgressData instance. Increment the sequence number so the platform knows this is a newer update.

using Microsoft.Windows.AppNotifications;

string tag = "weekly-playlist";
string group = "downloads";

var data = new AppNotificationProgressData(2)
{
    Value = 0.7,
    ValueStringOverride = "18/26 songs"
};

await AppNotificationManager.Default.UpdateAsync(data, tag, group);

Using UpdateAsync rather than replacing the entire notification ensures that the notification stays in the same position in Notification Center and doesn't move up or down. The method returns a NotificationUpdateResult that indicates whether the update succeeded or whether the notification couldn't be found (the user may have dismissed it).

Elements that support data binding

The following elements in app notifications support data binding:

• All properties on AppNotificationProgressBar
• The Text property on the top-level text elements

Update or replace a notification

You can replace a notification by sending a new notification with the same Tag and Group. The following table describes the difference between replacing and updating a notification.

In general, updating is useful for information that changes frequently and doesn't require the user's immediate attention, such as progress changing from 50% to 65%.

After your sequence of updates has completed (for example, a file has finished downloading), consider replacing the notification for the final step because:

• The final notification likely has different layout, such as removal of the progress bar or addition of new buttons.
• The user may have dismissed the progress notification but still wants to see a popup when the operation completes.

See also

• App notifications overview