Quickstart: Sending a toast notification from the desktop

Article
04/30/2018

This quickstart shows how to raise a toast notification from a desktop app.

Prerequisites

Libraries
- C++: Runtime.object.lib
- C#: Windows.Winmd
A shortcut to your app, with a System.AppUserModel.ID, must be installed to the Start screen. Note, however, that it does not need to be pinned to the Start screen. For more information, see How to enable desktop toast notifications through an AppUserModelID.
A version of Microsoft Visual Studio that supports at least Windows 8

Instructions

1. Create your toast content

Note When you specify a toast template that includes an image, be aware that desktop apps can use only local images; web images are not supported. Also, the path to the local image file must be provided as an absolute (not relative) path.


// Get a toast XML template
XmlDocument toastXml = ToastNotificationManager.GetTemplateContent(ToastTemplateType.ToastImageAndText04);

// Fill in the text elements
XmlNodeList stringElements = toastXml.GetElementsByTagName("text");
for (int i = 0; i < stringElements.Length; i++)
{
    stringElements[i].AppendChild(toastXml.CreateTextNode("Line " + i));
}

// Specify the absolute path to an image
String imagePath = "file:///" + Path.GetFullPath("toastImageAndText.png");
XmlNodeList imageElements = toastXml.GetElementsByTagName("image");

ToastNotification toast = new ToastNotification(toastXml);

2. Create and attach the event handlers

Register handlers for the toast events: Activated, Dismissed, and Failed. A desktop app must at least subscribe to the Activated event so that it can handle the expected activation of the app from the toast when the user selects it.


toast.Activated += ToastActivated;
toast.Dismissed += ToastDismissed;
toast.Failed += ToastFailed;

3. Send the toast

Important You must include the AppUserModelID of your app's shortcut on the Start screen each time that you call CreateToastNotifier. If you fail to do this, your toast will not be displayed.

ToastNotificationManager.CreateToastNotifier(appID).Show(toast);

4. Handle the callbacks

Bring your app's window to the foreground if it receives an "activated" callback from the toast notification. When a user selects a toast, the expectation is that the app will be launched to a view related to the content of that toast..