This article is Day #3 in a series called the 31 Days of Mango.
Today, we are going to discuss how we can set alarms and reminders on a user’s phone. These reminders can be completely managed by our application, which means we can create, edit, and delete them as the need arises.
How Reminders Work
Reminders on Windows Phone are a way to alert your user that something needs to be done. The obvious applications of a reminder are an alarm clock, a calendar, or a to-do list. However, reminders can be used for a variety of applications, and are even a handy tool for reminding your user to jump back into your app. Here’s a look at an example of a reminder you could launch on your user’s phone:
How To Create a Reminder
Creating a reminder is relatively simple. You create a new Reminder object, tack on the properties that are important to you, and then add it to the ScheduledActionService that is running on your user’s phone. Below is the source code for a fully-functioning reminder (the one in the screenshot above). After the code, I’ll walk through each piece in detail. Please note that I have added an additional using statement to the top of my page: Microsoft.Phone.Scheduler.
using Microsoft.Phone.Controls;
using Microsoft.Phone.Scheduler;
namespace Day3_Reminders
{
public partial class MainPage : PhoneApplicationPage
{
// Constructor
public MainPage()
{
InitializeComponent();
Reminder r = new Reminder("testreminder");
r.Title = "A Special Reminder";
r.Content = "Jeff Blankenburg’s Reminder";
r.NavigationUri = new Uri("/ReminderPage.xaml", UriKind.Relative);
r.BeginTime = DateTime.Now.AddSeconds(15);
r.ExpirationTime = DateTime.Now.AddDays(7);
r.RecurrenceType = RecurrenceInterval.Daily;
ScheduledActionService.Add(r);
}
}
}
Naming Your Reminder
The first line of Reminder code requires you to name your Reminder. In the example above, we named ours “testreminder.” Each Reminder (and Alarm, which we cover later) must have a name, and we will use this name to manage our events in the future. Each Reminder/Alarm must have a unique name, so keep this in mind as you’re building your app. If the name doesn’t matter to you, or you don’t plan on managing these events, you can use a simple timestamp as your name, which should guarantee a unique name each time.
App Name, Title and Content
These two text values represent the messages you will see in the box that appears on the user’s screen. In the image below, I have labeled each of the text values, so you know exactly how your text will appear.
As you can see, we don’t really get any control over how the text is displayed, but we do get plenty of space to write it. If the user taps on any portion of these text values, we have the option to take them back into our application using the NavigationUri property.
NavigationUri
The NavigationUri is a relative path to a page of your application. In our code sample above, we are sending the user to ReminderPage.xaml. This concept is referred to as “deep linking,” and you will see it used in many of the new APIs that are available to us in Windows Phone 7.5. The ability to launch your application to a specific page will prove incredibly valuable to both you and your users, and is using this ability is highly recommended.
BeginTime, ExpirationTime, and RecurrenceType
BeginTime is obviously a very important value, because it determines when our Reminder will launch on the user’s device. It takes a DateTime value, as does ExpirationTime. The ExpirationTime value is not required, but becomes more relevant and useful when we add the concept of a recurrence to our reminders. Perhaps you build an application that reminds your user to check their blood sugar levels at 1pm each day, but you only want to do it for one week. You can set the ExpirationTme to be one week from the initial Reminder, and set the RecurrenceType = RecurrenceInterval.Daily. This will send the same Reminder to the user at the same time each day. For multiple Reminders per day, you can create several different Reminders at a time. This will ultimately lead you to the next challenge: managing all of the different reminders on the device.
Managing Your Existing Reminders
Creating one reminder is a simple task. Managing many reminders and alarms can get tricky fast, however. If you’ve used the example code above in your own project, you’ve likely encountered an InvalidOperationException that tells you a Reminder with that name already exists. This is why, when creating a Reminder on your user’s phone, it is important to check and make sure that you haven’t already created it for them. To do this, we can search for an existing Reminder name, and delete it if it exists. The following code is exactly the same as my earlier example, except that I check to see if a Reminder with that name already exists, and delete it.
using Microsoft.Phone.Controls;
using Microsoft.Phone.Scheduler;
namespace Day3_Reminders
{
public partial class MainPage : PhoneApplicationPage
{
// Constructor
public MainPage()
{
InitializeComponent();
if (ScheduledActionService.Find("testreminder") != null)
ScheduledActionService.Remove("testreminder");
Reminder r = new Reminder("testreminder");
r.Title = "A Special Reminder";
r.Content = "Jeff Blankenburg’s Reminder";
r.NavigationUri = new Uri("/ReminderPage.xaml", UriKind.Relative);
r.BeginTime = DateTime.Now.AddSeconds(15);
r.ExpirationTime = DateTime.Now.AddDays(7);
r.RecurrenceType = RecurrenceInterval.Daily;
ScheduledActionService.Add(r);
}
}
}
This ability to find specific Reminders and Alarms becomes very handy when you need to edit or change an existing reminder that you have created. To edit a Reminder, you just need to use the Find() method to create a new reference to it, and the Replace() method to save it, like the example below:
{
Reminder r = ScheduledActionService.Find("testreminder") as Reminder;
r.Title = "This has been edited.";
r.Content = "This is updated content.";
r.BeginTime = DateTime.Now.AddSeconds(15);
ScheduledActionService.Replace(r);
}
How To Create an Alarm
Alarms are nearly identical to Reminders, with a couple of exceptions. First, Alarms can’t specify a Title property, and they also can’t use the NavigationUri property. What they can do, however, is play a custom sound, something Reminders can’t do. In every other way, Alarms and Reminders are identical. We manage them the same way (using the ScheduledActionService), which allows us to add, edit, and delete them as needed. Here’s some sample code for creating an Alarm, using the lessons we’ve already learned about Reminders:
ScheduledActionService.Remove("testalarm");
Alarm a = new Alarm("testalarm");
a.Content = "Jeff Blankenburg’s Alarm";
a.Sound = new Uri("button-8.mp3", UriKind.Relative);
a.BeginTime = DateTime.Now.AddSeconds(15);
a.ExpirationTime = DateTime.Now.AddDays(7);
a.RecurrenceType = RecurrenceInterval.Daily;
ScheduledActionService.Add(a);
As you can see, even the syntax is identical to a Reminder. For the Sound property, I am referencing an MP3 file that I included in my project. Day #20 of my 31 Days of Silverlight series covers exactly how to include an audio file in your project, and even how to call it from click events. Make sure to give that read if you need more information on this.
Summary
To wrap up, Reminders and Alarms are a great way to notify your user that the time has come to do something. While very similar, it’s important to remember that Reminders allow you to provide a link back into your application, even to a specific page, if you need. This is an important and effective way to get your user back into your app, and it makes it much easier for your user to find what they need.
To see a complete working application that uses all of the code and concepts from this article, click the “Download the Code” image below.
Tomorrow, I am going to walk through a newly available sensor in Windows Phones: the Compass. I’ll even show how magnets can affect it dramatically. See you then!
JEFF BLANKENBURG 
Leave a Reply