How to send and receive Tile notifications for Windows Phone 8

Article
05/20/2016

[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]

This topic introduces you to the steps needed to send Tile notifications to the Microsoft Push Notification Service so that a pinned Tile for your application on a Windows Phone will be updated. Push notifications for Windows Phone 8 has information on Tile notifications and how they are used.

You can download the complete Tile Notification Sample.

Important Note:
The section of this topic that sends a Tile notification from an ASP.NET webpage running on a web server requires either the full version of Visual Studio or the free Visual Studio Express for Web.

This topic contains the following sections.

Creating a Push Client to Receive Tile Notifications

In this section, we create an application that runs on a Windows Phone that creates a push notification channel and handles notification events.

Important Note:
For simplicity, we copy and paste the toast notification URI to our webpage that sends the notification. Normally, this URI is passed to a web service that you have created for your application.

To create a push client to receive Tile notifications

Create a new Windows Phone app.
Name the project TileNotificationClient.
Add the following using directive to the top of the MainPage.xaml.cs file.
```
using Microsoft.Phone.Notification;
```
Create two or three graphics for images to update the Tile with. For example, you can use Microsoft Paint to create three .jpg files that are 173 x 173 pixels and are a solid color of red, green, and blue. Name them Red.jpg, Green.jpg, and Blue.jpg.
Add the graphics files to the project by right-clicking the TileNotificationSample project name and selecting Add..., and then Existing Item. Select the three images you created and add them to the project.
Select Red.jpg in the Solution Explorer. In the Properties window, set its Build Action to Content to include the graphic as part of the .xap file. Repeat these steps for the other .jpg files.

Replace the MainPage constructor with the following code. This code looks to see whether a Tile notification channel has already been set up in a previous instance of the application. If the notification channel is found, it connects to the notification events. If the notification channel is not found, it is created and then connects to the notification events.

        public MainPage()
        {
            /// Holds the push channel that is created or found.
            HttpNotificationChannel pushChannel;

            // The name of our push channel.
            string channelName = "TileSampleChannel";

            InitializeComponent();

            // Try to find the push channel.
            pushChannel = HttpNotificationChannel.Find(channelName);

            // If the channel was not found, then create a new connection to the push service.
            if (pushChannel == null)
            {
                pushChannel = new HttpNotificationChannel(channelName);

                // Register for all the events before attempting to open the channel.
                pushChannel.ChannelUriUpdated += new EventHandler<NotificationChannelUriEventArgs>(PushChannel_ChannelUriUpdated);
                pushChannel.ErrorOccurred += new EventHandler<NotificationChannelErrorEventArgs>(PushChannel_ErrorOccurred);

                pushChannel.Open();

                // Bind this new channel for Tile events.
                pushChannel.BindToShellTile();


            }
            else
            {
                // The channel was already open, so just register for all the events.
                pushChannel.ChannelUriUpdated += new EventHandler<NotificationChannelUriEventArgs>(PushChannel_ChannelUriUpdated);
                pushChannel.ErrorOccurred += new EventHandler<NotificationChannelErrorEventArgs>(PushChannel_ErrorOccurred);

                // Display the URI for testing purposes. Normally, the URI would be passed back to your web service at this point.
                System.Diagnostics.Debug.WriteLine(pushChannel.ChannelUri.ToString());
                MessageBox.Show(String.Format("Channel Uri is {0}",
                    pushChannel.ChannelUri.ToString()));

            }
        }

Next, we add the code for the event handlers. The first event handler is for the ChannelUriUpdated event. For simplicity, the channel URI is displayed here, but normally this URI would be sent back to your web service.

        void PushChannel_ChannelUriUpdated(object sender, NotificationChannelUriEventArgs e)
        {

            Dispatcher.BeginInvoke(() =>
            {
                // Display the new URI for testing purposes. Normally, the URI would be passed back to your web service at this point.
                System.Diagnostics.Debug.WriteLine(e.ChannelUri.ToString());
                MessageBox.Show(String.Format("Channel Uri is {0}",
                    e.ChannelUri.ToString()));

            });
        }

The next event handler is for error handling. Your code should gracefully handle notification errors, because data connections can vary depending on the location and services of the phone.

        void PushChannel_ErrorOccurred(object sender, NotificationChannelErrorEventArgs e)
        {
            // Error handling logic for your particular application would be here.
            Dispatcher.BeginInvoke(() =>
                MessageBox.Show(String.Format("A push notification {0} error occurred.  {1} ({2}) {3}",
                    e.ErrorType, e.Message, e.ErrorCode, e.ErrorAdditionalData))
                    );
        }

The push client code is now complete. We will run this code after we have completed our webpage that sends the notification.

Sending a Tile notification

In this section, we create an ASP.NET webpage that sends a Tile notification by using the URI that is returned when the push channel is created on the device.

Important Note:
If you need to use remote Internet URIs for Tile images, you must take the following steps: Ensure the remote image file size is less than 150 KB. Ensure the image can be downloaded in 60 seconds or less. On your HttpNotificationChannel object, you must specify the remote base URIs in the BindToShellTile(Collection<(Of <(Uri>)>)) method.

If you need to use remote Internet URIs for Tile images, you must take the following steps:

Ensure the remote image file size is less than 150 KB.
Ensure the image can be downloaded in 60 seconds or less.
On your HttpNotificationChannel object, you must specify the remote base URIs in the BindToShellTile(Collection<(Of <(Uri>)>)) method.

To create an ASP.NET project, you need the full version of Visual Studio or the free Visual Studio Express for Web.

To create an ASP.NET page for sending Tile notifications

Open another instance of Visual Studio and create a new application. The template should be a ASP.NET Empty Web Application under the Web C# categories.
Name the project SendTile.
Add a new web form to the project by right-clicking the SendTile project name, selecting Add, then New Item…, and then Web Form.
Name the form SendTile and click the Add button.
Make the SendTile form the start page by right-clicking SendTile.aspx in the Solution Explorer and then selecting Set as Start Page.
The next step is to add the following controls to the SendTile.aspx web form.

Control type	Control ID	Text for control
TextBox	TextBoxUri	Enter Uri:
TextBox	TextBoxTitle	Enter Title:
TextBox	TextBoxBackgroundImage	Enter Image:
TextBox	TextBoxCount	Enter Count:
TextBox	TextBoxBackTitle	Enter Back Title:
TextBox	TextBoxBackBackgroundImage	Enter Back Background Image:
TextBox	TextBoxBackContent	Enter Back Content:
Button	ButtonSendTile	Send Tile Notification:
TextBox	TextBoxResponse	Response:

The **Send Tile** button will have a ButtonSendTile\_Click event handler. Replace the contents of SendTile.aspx with the following code to create these controls. <%@ Page Language="C#" AutoEventWireup="true" CodeBehind="SendTile.aspx.cs" Inherits="SendTile.SendTile" %>

Add the following using directives to the top of the SendTile.aspx.cs file.
```
using System.Net;
using System.IO;
using System.Text;
```

Add the code for the ButtonSendTile_Click event handler. This code gets the URI that was entered in the first TextBox, form the Tile notification message, and then post it to the Microsoft Push Notification Service.

             protected void ButtonSendTile_Click(object sender, EventArgs e)
        {


            try
            {
                // Get the URI that the Microsoft Push Notification Service returns to the Push Client when creating a notification channel.
                // Normally, a web service would listen for URIs coming from the web client and maintain a list of URIs to send
                // notifications out to.
                string subscriptionUri = TextBoxUri.Text.ToString();


                HttpWebRequest sendNotificationRequest = (HttpWebRequest)WebRequest.Create(subscriptionUri);

                // Create an HTTPWebRequest that posts the Tile notification to the Microsoft Push Notification Service.
                // HTTP POST is the only method allowed to send the notification.
                sendNotificationRequest.Method = "POST";

                // The optional custom header X-MessageID uniquely identifies a notification message. 
                // If it is present, the same value is returned in the notification response. It must be a string that contains a UUID.
                // sendNotificationRequest.Headers.Add("X-MessageID", "<UUID>");

                // Create the Tile message.
                  string tileMessage = "<?xml version=\"1.0\" encoding=\"utf-8\"?>" +
                  "<wp:Notification xmlns:wp=\"WPNotification\">" +
                      "<wp:Tile>" +
                        "<wp:BackgroundImage>" + TextBoxBackgroundImage.Text + "</wp:BackgroundImage>" +
                        "<wp:Count>" + TextBoxCount.Text + "</wp:Count>" +
                        "<wp:Title>" + TextBoxTitle.Text + "</wp:Title>" +
                        "<wp:BackBackgroundImage>" + TextBoxBackBackgroundImage.Text + "</wp:BackBackgroundImage>" +
                        "<wp:BackTitle>" + TextBoxBackTitle.Text + "</wp:BackTitle>" +
                        "<wp:BackContent>" + TextBoxBackContent.Text + "</wp:BackContent>" +
                     "</wp:Tile> " +
                  "</wp:Notification>";

                // Set the notification payload to send.
                byte[] notificationMessage = Encoding.Default.GetBytes(tileMessage);

                // Set the web request content length.
                sendNotificationRequest.ContentLength = notificationMessage.Length;
                sendNotificationRequest.ContentType = "text/xml";
                sendNotificationRequest.Headers.Add("X-WindowsPhone-Target", "token");
                sendNotificationRequest.Headers.Add("X-NotificationClass", "1");


                using (Stream requestStream = sendNotificationRequest.GetRequestStream())
                {
                    requestStream.Write(notificationMessage, 0, notificationMessage.Length);
                }

                // Send the notification and get the response.
                HttpWebResponse response = (HttpWebResponse)sendNotificationRequest.GetResponse();
                string notificationStatus = response.Headers["X-NotificationStatus"];
                string notificationChannelStatus = response.Headers["X-SubscriptionStatus"];
                string deviceConnectionStatus = response.Headers["X-DeviceConnectionStatus"];

                // Display the response from the Microsoft Push Notification Service.  
                // Normally, error handling code would be here. In the real world, because data connections are not always available,
                // notifications may need to be throttled back if the device cannot be reached.
                TextBoxResponse.Text = notificationStatus + " | " + deviceConnectionStatus + " | " + notificationChannelStatus;
            }
            catch (Exception ex)
            {
                TextBoxResponse.Text = "Exception caught sending update: " + ex.ToString();
            }

        }

Running the Tile notification sample

To run the sample, we first run the push client code to create the channel and get the URI. We then use this URI in the webpage to send the Tile.

To run the sample

Go back to the TileNotificationClient project and run it. Windows Phone Emulator initializes, and then the application starts. After a moment or two, the application should display a message with the URI. This URI also will be displayed in the Visual Studio debugger Output window.

Tip

In Microsoft Visual Studio Express 2012 for Windows Phone, the default setting is to not display the Output window during a debugging session. You can display the Output window by going to the Debug menu, selecting Windows, and then selecting Output. Scroll the window to find the URI.

The notification channel has now been created. Copy the URI from the Visual Studio debugger Output window to the clipboard.
In your Windows Phone application running on the emulator, pin the Tile for your application to Start by tapping and holding the TileNotificationClient name in the application list and then selecting pin to start. This is the Tile that will be updated.
Switch to the SendTile project and run it.
In the URI text box, paste the URI that you copied from the previous project.
Enter a title, count, and image for the Tile. Use the full name of the .jpg file, such as Red.jpg, for the image name.

Note that you can also send URIs to remote image files by using the BindToShellTile(Collection<(Of <(Uri>)>)) method.
Click the Send Tile button. The Tile that you pinned to Start should update. If you set any properties of the back of the Tile, the Tile will flip over after a couple of seconds to show the back of the Tile. If you leave a field blank, such as Title, then that field will not update.

You have now learned how to update a Tile by using an ASP.NET page to send a notification to a Windows Phone.