ToastNotification Class

Definition

Namespace:: Windows.UI.Notifications

Edit

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: Object
ToastNotification

Attributes: ActivatableAttribute ContractVersionAttribute DualApiPartitionAttribute ThreadingAttribute MarshalingBehaviorAttribute

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