ToastNotification Class

Definition

Defines the content, associated metadata and events, and expiration time of a toast notification.

public ref class ToastNotification sealed
/// [Windows.Foundation.Metadata.Activatable(Windows.UI.Notifications.IToastNotificationFactory, 65536, Windows.Foundation.UniversalApiContract)]
/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.DualApiPartition(version=100794368)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.MTA)]
class ToastNotification sealed
/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.DualApiPartition(version=100794368)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.MTA)]
/// [Windows.Foundation.Metadata.Activatable(Windows.UI.Notifications.IToastNotificationFactory, 65536, "Windows.Foundation.UniversalApiContract")]
class ToastNotification sealed
/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.DualApiPartition(version=100794368)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.MTA)]
/// [Windows.Foundation.Metadata.Activatable(Windows.UI.Notifications.IToastNotificationFactory, 65536, "Windows.Foundation.UniversalApiContract")]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
class ToastNotification sealed
[Windows.Foundation.Metadata.Activatable(typeof(Windows.UI.Notifications.IToastNotificationFactory), 65536, typeof(Windows.Foundation.UniversalApiContract))]
[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.DualApiPartition(version=100794368)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.MTA)]
public sealed class ToastNotification
[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.DualApiPartition(version=100794368)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.MTA)]
[Windows.Foundation.Metadata.Activatable(typeof(Windows.UI.Notifications.IToastNotificationFactory), 65536, "Windows.Foundation.UniversalApiContract")]
public sealed class ToastNotification
[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.DualApiPartition(version=100794368)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.MTA)]
[Windows.Foundation.Metadata.Activatable(typeof(Windows.UI.Notifications.IToastNotificationFactory), 65536, "Windows.Foundation.UniversalApiContract")]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
public sealed class ToastNotification
function ToastNotification(content)
Public NotInheritable Class ToastNotification
Inheritance
ToastNotification
Attributes

Windows 10 requirements

Device family
Windows 10 (introduced in 10.0.10240.0 - for Xbox, see UWP features that aren't yet supported on Xbox)
API contract
Windows.Foundation.UniversalApiContract (introduced in v1.0)

Examples

The following example shows how to create and send a toast notification that includes text and images, including use of the ToastNotification constructor.

var notifications = Windows.UI.Notifications;

// Get the toast notification manager for the current app.
var notificationManager = notifications.ToastNotificationManager;

// The getTemplateContent method returns a Windows.Data.Xml.Dom.XmlDocument object
// that contains the toast notification XML content.
var template = notifications.toastTemplateType.toastImageAndText01;
var toastXml = notificationManager.getTemplateContent(notifications.ToastTemplateType[template]);

// You can use the methods from the XML document to specify the required elements for the toast.
var images = toastXml.getElementsByTagName("image");
images[0].setAttribute("src", "images/toastImageAndText.png");

var textNodes = toastXml.getElementsByTagName("text");
textNodes.forEach(function (value, index) {
    var textNumber = index + 1;
    var text = "";
    for (var j = 0; j < 10; j++) {
        text += "Text input " + /*@static_cast(String)*/textNumber + " ";
    }
    value.appendChild(toastXml.createTextNode(text));
});

// Create a toast notification from the XML, then create a ToastNotifier object
// to send the toast.
var toast = new notifications.ToastNotification(toastXml);

notificationManager.createToastNotifier().show(toast);

The following example shows how to listen for and handle the Dismissed event.

var notifications = Windows.UI.Notifications;

yourToastNotification.addEventListener("dismissed", function (e) {
    switch (e.reason) {
        case notifications.ToastDismissalReason.applicationHidden:
            // The application hid the toast using ToastNotifier.hide.
            break;
        case notifications.ToastDismissalReason.userCanceled:
            // The user dismissed the toast.
            break;
        case notifications.ToastDismissalReason.timedOut:
            // The toast has expired.
            break;
    }
}

Using Event Handlers

The following example shows how to add an event handler for toast activation on running desktop apps. ToastNotifications need to be persisted in a list to maintain a reference to the toast for later callbacks. A similar pattern can be followed for dismissed and expired toast events.

Important

Ensure event handlers are unsubscribed to when no longer needed to avoid memory leaks.

class AppNotification
{
    protected List<ToastNotification> toastNotificationList = new List<ToastNotification>();

    public void SendToastNotification()
    {
        // Constructs the content
        ToastContent content = new ToastContentBuilder()
            .AddText("Firing Toast")
            .GetToastContent();

        // Creates the notification
        ToastNotification notification = new ToastNotification(content.GetXml());

        //Add an in memory event handler
        notification.Activated += ToastNotificationCallback_Activated;

        //Adds toast notification to list to persist toast
        toastNotificationList.Add(notification);

        //Sends the notification
        ToastNotificationManager.CreateToastNotifier().Show(notification);
    }

    private void ToastNotificationCallback_Activated(ToastNotification sender, object args)
    {
        //Handle Activation Here
    }

    ~AppNotification()
    {
        foreach(ToastNotification tn in toastNotificationList)
        {
            //Unsubscribe
            tn.Activated -= ToastNotificationCallback_Activated;
        }
        toastNotificationList.Clear();
    }
}

Remarks

  • Handling activation guidance
    • UWP Applications should use the OnActivated for handling toast activations.
    • Staring WinRT Build 19041, MSIX and Sparsed Sign Packaged applications are able to use ToastNotificationActionTrigger for handling activations for more details.
    • Desktop apps can use COM activation by following Desktop - Send Local Toast.
    • If none of the activation options fit your application, follow the example in this document for properly using event handlers.

Version history

Windows version SDK version Value added
1607 14393 NotificationMirroring
1607 14393 RemoteId
1703 15063 Data
1703 15063 Priority
1903 18362 ExpiresOnReboot

Constructors

ToastNotification(XmlDocument)

Creates and initializes a new instance of the ToastNotification.

Properties

Content

Gets the XML that defines the current toast notification.

Data

Gets or sets additional information about the status of the toast notification.

ExpirationTime

Gets or sets the time after which a toast notification should not be displayed.

ExpiresOnReboot

Indicates whether the toast notification will remain in the Notification Center after a reboot.

Group

Gets or sets the group identifier for the notification.

NotificationMirroring

Gets or sets a value that specifies whether notification mirroring is allowed.

Priority

Gets or sets the priority of the toast notification.

RemoteId

Gets or sets a remote id for the notification that enables the system to correlate this notification with another one generated on another device.

SuppressPopup

Gets or sets whether a toast's pop-up UI is displayed on the user's screen.

Do not set this property to true in a toast sent to a Windows 8.x device. Doing so will cause a compiler error or a dropped notification.

Tag

Gets or sets the unique identifier of this notification within the notification Group.

Events

Activated

Occurs when user activates a toast notification through a click or touch. Apps that are running subscribe to this event.

Dismissed

Occurs when a toast notification leaves the screen, either by expiring or being explicitly dismissed by the user. Apps that are running subscribe to this event.

Failed

Occurs when an error is caused when Windows attempts to raise a toast notification. Apps that are running subscribe to this event.

Applies to

See also