Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

ShellToast on Windows Phone - when HTTP push is just too much

DZone's Guide to

ShellToast on Windows Phone - when HTTP push is just too much

· Mobile Zone
Free Resource

Discover how to focus on operators for Reactive Programming and how they are essential to react to data in your application.  Brought to you in partnership with Wakanda

For those who want to have in-app alerts it is a major problem to have to invoke the HTTP push channel when all that is needed is simply alert the user about an oncoming event or action inside the application itself and not outside of it.

Don't get too excited about this - there are some restrictions and limitations, but at least you can do this in offline mode now and not require the user to have an active Internet connection.

It all starts with the ShellToast and ShellTile classes. These are the two building blocks for internal notifications and their structure is very similar to the one of regular push notifications. The only difference is the fact that their content is no longer pushed through the HTTP pipe but rather created in the code-behind.

ShellToast

This is probably the most useful notification type that you can use in an application, because of its simplicity and the possibility to appear even if other applications are running. Creating one is as simple as this code snippet:

Microsoft.Phone.Shell.ShellToast toast = new Microsoft.Phone.Shell.ShellToast();
toast.Content = "This is a local toast";
toast.Title = "MYAPP";
toast.NavigationUri = new System.Uri("/SecondPage.xaml", System.UriKind.Relative);
toast.Show();

A new instance should be created for every toast that you want to show. The content of the message is set by the Content property - that is the message itself. Try keeping it generally short because the entire message is not going to be shown if it's too long. Same applies to the title, which should be four times shorter than the message (if talking about max values).

SIDENOTE: Max length for the title is 64 characters. For the content: 256 characters.

These values are clearly visible if you decide to dig through the source code of the ShellToast class itself:

Now it's time to show the notification. But there is one thing - you cannot show it directly while the application is running, but rather from inside a background agent. And there you have several choices - you can read more about those here.

For my example, I simply created the most basic testing infrastructure. It is described really well in this MSDN article. All I did was adding a new ScheduledTaskAgent-based project that carries a single class. I added the snippet above to the OnInvoke method.

NOTE: One application can have only one ScheduledTaskAgent-based class that will be handling background operations.

Here I could check for the type of task that is being processed (only one instance of each type can be used) by checking the ScheduledTask parameter passed to OnInvoke by the OS, but since I am in a test project, I can skip that and simply invoke the toast:

public class TaskScheduler : ScheduledTaskAgent
{
    protected override void OnInvoke(ScheduledTask task)
    {
        Microsoft.Phone.Shell.ShellToast toast = new Microsoft.Phone.Shell.ShellToast();
        toast.Content = "This is a local toast";
        toast.Title = "MYAPP";
        toast.NavigationUri = new System.Uri("/SecondPage.xaml", System.UriKind.Relative);
        toast.Show();

        NotifyComplete();
    }

    protected override void OnCancel()
    {
        base.OnCancel();
    }
}

Here I am also passing a URI to another page inside the application itself. I can easily skip this and if the user decides to tap on the notification, it will simply get him to the application startup page.

So far the task hasn't been added to the scheduler yet, so there is no way the notification will be shown. I can use a PeriodicTask that will work just fine for this situation:

PeriodicTask task = new PeriodicTask("TASK_ID_02");
task.Description = "A simple task";

ScheduledActionService.Add(task);

Once added to the pool, a PeriodicTask will be triggered every half an hour. This is introduced to specifically prevent abuse from the developer's side, but that's another topic. Now, once I run the application, I will see that the notification will show up if I set a breakpoint on the ShellToast instantiation line and close the app (by pressing the Home button).

Congratulations! Now you know how to create toast notifications from your app even when no network is accessible.

In the next article, I will cover ShellTile - the old-style tile notification, also controlled from the application and not a web service.

Learn how divergent branches can appear in your repository and how to better understand why they are called “branches".  Brought to you in partnership with Wakanda

Topics:

Opinions expressed by DZone contributors are their own.

The best of DZone straight to your inbox.

SEE AN EXAMPLE
Please provide a valid email address.

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.
Subscribe

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}