Category: Application Development

AdControl, Animations and the Back Key

Sometimes things don’t make sense, but bugs in software hardly do. In a new Windows Phone application I am implementing a fully functional trial mode that displays advertisements using Microsoft’s AdControl. I made sure to use the latest version of the AdControl (which is version 6.1.320.0). On one of the pages inside the application has both a list and detail view. If an item is selected from a list, the list disappears in the center of the page and detail information zooms in, making use of a few animations. Since the detail view seems to be a new page (even though it isn’t), I am overriding default hardware Back button behavior. If details are displayed when the hardware Back button is pressed, the list view becomes visible again. If the list view was already visible, I simply navigate back to the previous page. All in all, this functionality is straight forward and it is not uncommon to reuse pages for different views.

However, when I was testing the application, I ran into some unexpected behavior. With the AdControl visible, the animation that was supposed to run on pressing the hardware Back button did not run smoothly and sometimes it didn’t run at all. However, with the AdControl not visible, the animation was always running nice and smoothly.

This code is executed on pressing the hardware Back button:

Switching from detail to list

protected override void OnBackKeyPress(CancelEventArgs e)
{
    if (lastActiveListBox != null)
    {
        e.Cancel = true;
        lastActiveListBox = null;
        VisualStateManager.GoToState(this, "TreeListState", true);
    }
    base.OnBackKeyPress(e);
}

The following video shows the application in action, once with an AdControl on the page and once without the AdControl:

The AdControl influences animations

Of course this behavior is unacceptable for my application, so the next step is trying to work around the issue. After investigating a bit further, it seems that the combination of showing an AdControl and triggering an animation on the hardware Back button causes the problem. For instance, executing exactly the same code, but this time when tapping on the title bar (after adding a tap event handler), always results in smooth animations, independent of displaying an AdControl.

protected override void OnBackKeyPress(CancelEventArgs e)
{
    if (lastActiveListBox != null)
    {
        e.Cancel = true;
        lastActiveListBox = null;
        VisualStateManager.GoToState(this, "TreeListState", true);
    }
    base.OnBackKeyPress(e);
}
 
private void ApplicationTitle_Tap(object sender, System.Windows.Input.GestureEventArgs e)
{
    if (lastActiveListBox != null)
    {
        lastActiveListBox = null;
        VisualStateManager.GoToState(this, "TreeListState", true);
    }
}

Triggering the animation on the hardware Back button still shows the same behavior though:

The AdControl in combination with the Back Key influences animations

I am not sure what causes the problem. However, the fact that the animation runs smoothly when triggered in another way got me thinking about a more or less acceptable work around with not too much additional code involved. Since starting the animation on another event got rid of my problem, I came to the following solution. When the hardware Back button is pressed in my detailed view, I start a Timer that expires immediately. In the Tick event of the timer I am simply stopping the timer and I am starting the animation. This resulted in the following code:

Start animation on timer tick

private DispatcherTimer timer;
 
public TreePage()
{
    InitializeComponent();
 
    if (App.ShowAds)
    {
        timer = new DispatcherTimer();
        timer.Tick += new EventHandler(timer_Tick);
        ah = new AdHelper(AdPlaceHolder, true);
        this.Loaded += new RoutedEventHandler(ah.PhoneApplicationPage_Loaded);
    }
 
}
 
void timer_Tick(object sender, EventArgs e)
{
    timer.Stop();
    VisualStateManager.GoToState(this, "TreeListState", true);
}
 
protected override void OnBackKeyPress(CancelEventArgs e)
{
    if (lastActiveListBox != null)
    {
        e.Cancel = true;
        lastActiveListBox = null;
        if (App.ShowAds)
        {
            timer.Start();
        }
        else
        {
            VisualStateManager.GoToState(this, "TreeListState", true);
        }
    }
    base.OnBackKeyPress(e);
}

This time the animation displays smoothly, independent of the presence or absence of an AdControl as is shown in the following video:

Animations are smooth when started on a Timer Tick

It would have been great if I could have explained why the AdControl in combination with the hardware Back button influences animations. For right now I assume this is a bug in the AdControl. At least, the work around shown in the blog entry is relatively simple and is not a big influence on either the memory footprint or the performance of your Windows Phone application. When a new version of the AdControl is available, I will make sure to test the identical scenario again and update this blog entry when results have changed.

EvenTiles and Push Notifications

In the previous part of EvenTiles, you saw that applications running on 256-MB Devices cannot use Periodic Agents. Of course the application is still working, but the content of the backside of a Secondary Tile, when pinned to the start screen, does not alter. Since 256-MB Windows Phone Devices fully support Push Notifications, it is possible to change the Secondary Tile content with a little extra effort. In this episode of EvenTiles we will take a look at adding Tile Notifications to the application. Those Tile Notifications are delivered to individual Windows Phone devices through the Microsoft Push Notification Service, just like all other Push Notifications.

In this blog entry we will concentrate on the client side, mainly providing code that registers the application. To test the application, we will make use of a little ASP.NET application that is based on the sample that is introduced in the How to Send and Receive Tile Notifications for Windows Phone article. It is beyond the scope of this blog entry to show how to host a web service (for instance by making use of Azure functionality).

NOTE: The ASP.NET test application cannot be created using Visual Studio 2010 Express for Windows Phone. You either need at least Visual Studio 2010 Professional or the free Visual Web Developer 2010 Express to create the test application.

Push Notifications on Secondary Tiles

Something that is not entirely clear in the referred How to article, or in the documentation around Push Notifications on MSDN is the fact that sending Tile Updates through Push Notifications is not limited to the Application Tile, but you can also use the same approach to update Secondary Tiles. Since we are dealing with a Secondary Tile in the EvenTiles application, we will focus on updating a Secondary Tile. In the ASP.NET test application we will create the following message to update our tile:

Updating a Seondary Tile

// Create the Tile message.
string tileMessage = "<?xml version=\"1.0\" encoding=\"utf-8\"?>" +
"<wp:Notification xmlns:wp=\"WPNotification\">" +
    "<wp:Tile ID=\"/MainPage.xaml?TileId=Secondary\">" +
      "<wp:BackContent>" + TextBoxBackContent.Text + "</wp:BackContent>" +
      "<wp:Count>" + nrRuns.ToString() + "</wp:Count>" +
   "</wp:Tile> " +
"</wp:Notification>";

By explicitly specifying the ID of a tile you can inform the Push Notification Service that you want to update a specific (Secondary) Tile. Omitting the ID passes the update to the Application Tile. Since EvenTiles creates the Secondary Tile as shown below, passing the Tile Notification message as shown above will update the Secondary Tile if it is pinned to the Start Screen. In the sample we only update the BackContent of the Secondary Tile and the count on the front of it, but it is possible to update more properties of the Secondary Tile. Of course it is important to use the same URI for the Secondary Live Tile when updating it through a Tile Notification.

Creating a Secondary Tile

private void btnInstall_Click(object sender, RoutedEventArgs e)
{
    StandardTileData NewTileData = new StandardTileData
    {
        BackgroundImage = new Uri("Background.png", UriKind.Relative),
        Title = "EvenTiles",
        Count = 0,
        BackBackgroundImage = new Uri("BackBackTile.png", UriKind.Relative),
        BackTitle = "EvenTiles",
        BackContent = App.ActualSecBackContent
    };
    ShellTile.Create(new Uri("/MainPage.xaml?TileId=Secondary", UriKind.Relative), NewTileData);
}

In order to receive Tile Notifications in EvenTiles, the application needs to create a HttpNotificationChannel or attach to an already created channel if the application is started again on a particular Windows Phone device. The following code snippet shows how to setup a new notification channel. If the channel is successfully opened, it will pass a URI through the ChannelUriUpdated event handler. This URI is used to send notifications to the particular Windows Phone Device that received this URI from the Push Notification Service. This URI is unique for the application and the phone on which the application is running. If the channel already exists, this method simply starts listening for channel changes or errors through the ChannelUriUpdated and ErrorOccurred events respectively.

Getting a Notification Channel

public class TileNotifications
{
    public const string tileNotificationChannel = "EvenTilesChannel";
 
    public void SetupChannel()
    {
        var pushChannel = HttpNotificationChannel.Find(tileNotificationChannel);
        if (pushChannel == null)
        {
            pushChannel = new HttpNotificationChannel(tileNotificationChannel);
            pushChannel.ChannelUriUpdated += new EventHandler<NotificationChannelUriEventArgs>(PushChannel_ChannelUriUpdated);
            pushChannel.ErrorOccurred += new EventHandler<NotificationChannelErrorEventArgs>(PushChannel_ErrorOccurred);
            pushChannel.Open();
            pushChannel.BindToShellTile();
        }
        else
        {
            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 a web service.
            System.Diagnostics.Debug.WriteLine(pushChannel.ChannelUri.ToString());
        }
    }

If you want to send out push notifications from a web service, the Windows Phone application typically would send this URI to a web service, that in turn uses it to deliver the push notifications to the registered device. In our test application we simply display the URI in the debug windows of Visual Studio to be able to copy it to our ASP.NET test application.

If you are no longer interested in receiving Tile Notifications for your application, you can close a previously opened HttpNotificationChannel, make sure to dispose of it and also make sure to unsubscribe to events to prevent against leaking memory. The following code snippet shows how you can stop receiving Tile Notifications:

Closing a Notification Channel

public void CloseChannel()
{
    var pushChannel = HttpNotificationChannel.Find(tileNotificationChannel);
    if (pushChannel != null)
    {
        pushChannel.ChannelUriUpdated -= PushChannel_ChannelUriUpdated;
        pushChannel.ErrorOccurred -= PushChannel_ErrorOccurred;
        pushChannel.Close();
        pushChannel.Dispose();
        App.GetLiveTileNotifications = false;
    }
}

Finally, in our EvenTiles application we implement some simplified event handling to react on push channel changes and errors. This implementation is for demonstration purposes only and can be used to manually pass a channel URI to an ASP.NET application or to close down / reinitialize the push channel on certain errors. The following code snippet shows how we simply write the channel URI to the Output Window of Visual Studio.

Handling Push Channel Events

void PushChannel_ErrorOccurred(object sender, NotificationChannelErrorEventArgs e)
{
    switch (e.ErrorType)
    {
        case ChannelErrorType.ChannelOpenFailed:
            App.GetLiveTileNotifications = false;
            break;
        case ChannelErrorType.PayloadFormatError:
            SetupChannel();
            break;
        default:
            CloseChannel();
            break;
    }
}
 
void PushChannel_ChannelUriUpdated(object sender, NotificationChannelUriEventArgs e)
{
    System.Diagnostics.Debug.WriteLine(e.ChannelUri.ToString());
    App.GetLiveTileNotifications = true;
}

To send Tile Notifications to EvenTiles, make sure to run EvenTiles and enable Tile Notifications through the Settings Page. Once Tile Notifications are enabled, you can copy the channel URI from the Visual Studio Output Window and paste it in the ASP.NET test application. After this step, you can send tile updates to EvenTiles.

The ASP.NET test application does so in a ThreadPool thread. You can specify the number of updates and the time between updates. Each time another update is send, the count property that will be displayed on the front side of the Secondary Tile that EvenTiles pinned on the start screen will be updated.

Even though Background Agents are not supported on 256-MB devices, we have a nice workaround by making use of Push Notifications because they are fully supported. Of course this means that you need to invest more in server side programming, but it also means that the end user experience of a Windows Phone application can be very similar on both a 512-MB device and a 256-MB device. For this to work, the target device must have a network connection.

The complete sample code for EvenTiles so far can be downloaded here. If you want to test the application on a 256-MB device (emulator), you will need to download and install the Windows Phone 7.1.1 SDK Update as well. The ASP.NET test application is also available as a separate download. In order to run this test application, you need a version of Visual Studio 2010 that supports creating and debugging ASP.NET applications.

The following video shows how to subscribe to Tile Notifications from within the EvenTiles application and how to test the newly added functionality by means of an APS.NET test application.

Using Push Notifications to update Live Tiles on Windows Phone

EvenTiles and 256-MB Windows Phone Devices

In part 18 of the continuing story of EvenTiles we will take a look at targeting additional Windows Phone devices that will shortly hit the market in several countries. A few weeks ago, the Windows Phone 7.1.1 SDK Update became available for download. This SDK contains everything you need to develop Windows Phone applications that target the new 256-MB devices. Compared to Windows Phone 7.5 devices, these devices have less memory available, but they can run almost all applications that will run on Windows Phone 7.5 devices as long as they don’t use excessive amounts of memory and as long as they don’t make use of generic background services.

Even though the latter is no problem for most applications (especially since users might have disabled background processing for a particular application on Windows Phone 7.5 devices), in the case of EvenTiles this is kind of an interesting limitation. After all, EvenTiles was originally created to show you how to develop Windows Phone applications, but background processing became one of the more important features of the application. Having said that, EvenTiles will definitely run on 256-MB Windows Phone devices. The only exception is the fact that the background of the Secondary Tile that can be pinned to the Start Screen will only contain one single string.

Let’s just take a look at how to detect if a Windows Phone application is running on a 256-MB device and how we can limit functionality in that particular case. Since background processing is unavailable on a 256-MB device, it makes a lot of sense to remove the functionality to start and re-schedule a PeriodicTask when EvenTiles runs on such a device. The code to start / stop a PeriodicTask in EvenTiles can be found in the MainPage class in two separate methods (StartPeriodicAgent and RemovePeriodicAgent). This code is also used in the MainPage constructor to optionally renew the PeriodicTask when the Even Tiles application is started.

After installing the Windows Phone 7.1.1 SDK Update, you will not only get a new emulator that allows you to test your application on a 256-MB target, but you will also have the ability to check the amount of memory that your target device can use to distinguish between 256-MB and 512-MB Windows Phone devices. To do so, you will have to inspect the value of a property inside the DeviceExtendedProperties. This value can be retrieved through the ApplicationWorkingSetLimit property, which returns a long integer. The interesting thing about this property is that it may or may not exist on particular Windows Phone devices. If the property exists, it will give back a value representing the current application’s memory working set limit on a device. If this value contains the equivalent of 90 MB, the application is running on a 256-MB Windows Phone device, otherwise it is running on a 512-MB device. However, if the application is running on a device that does not contain the latest Windows Phone operating system update, the ApplicationWorkingSetLimit property will not be defined and an exception will be thrown when trying to retrieve the value of that property. In this case, the exception can be treated as ‘expected’ behavior for 512-MB devices. This means we can detect the device we are running on by making use of the following code snippet:

Running on a 256-MB Device?

public const string keyIsLowMemDevice = "K_256MB";
public static bool IsLowMemDevice { get; private set; }
 
private IsolatedStorageSettings appSettings = IsolatedStorageSettings.ApplicationSettings;
 
// Code to execute when the application is launching (eg, from Start)
// This code will not execute when the application is reactivated
private void Application_Launching(object sender, LaunchingEventArgs e)
{
    if (!appSettings.Contains(keyIsLowMemDevice))
    {
        try
        {
            Int64 result = (Int64)DeviceExtendedProperties.GetValue("ApplicationWorkingSetLimit");
            if (result < (long)(90 * 1024 * 1024))
                IsLowMemDevice = true;
            else
                IsLowMemDevice = false;
        }
        catch (ArgumentOutOfRangeException)
        {
            // Windows Phone OS update not installed, which indicates a 512-MB device. 
            IsLowMemDevice = false;
        }
        appSettings[keyIsLowMemDevice] = IsLowMemDevice;
    }
    else
    {
        IsLowMemDevice = (bool)appSettings[keyIsLowMemDevice];
    }
}

In this code snippet, we store a boolean value in the application settings to indicate if we are running on a low memory device. To determine the device on which the application is running, we inspect the DeviceExtendedProperties once. The reason to do this only once is to not continuously run into exceptions, which would in fact hurt performance during application initialization on a device that does not have the latest operating system update. Once we know on which device we are running, we can now either enable or disable background processing as is shown in the next code snippet that takes care of pinning / removing a Secondary Tile as a result of clicking the install button:

No Background Agent on 256-MB

private void btnInstall_Click(object sender, RoutedEventArgs e)
{
    if (secondaryTileInstalled)
    {
        var secondaryTile = ShellTile.ActiveTiles.FirstOrDefault(x => x.NavigationUri.ToString().Contains("TileId=Secondary"));
        if (secondaryTile != null)
        {
            if (!App.IsLowMemDevice)
            {
                RemovePeriodicAgent();
            }
            secondaryTile.Delete();
            btnInstall.Content = txtInstallTile;
            secondaryTileInstalled = false;
        }
    }
    else
    {
        if (!App.IsLowMemDevice)
        {
            StartPeriodicAgent();
        }
 
        StandardTileData NewTileData = new StandardTileData
        {
            BackgroundImage = new Uri("Background.png", UriKind.Relative),
            Title = "EvenTiles",
            Count = 0,
            BackBackgroundImage = new Uri("BackBackTile.png", UriKind.Relative),
            BackTitle = "EvenTiles",
            BackContent = App.ActualSecBackContent
        };
 
        ShellTile.Create(new Uri("/MainPage.xaml?TileId=Secondary", UriKind.Relative), NewTileData);
    }
}

From a functional point of view, it now makes perfect sense to run EvenTiles on 256-BM devices as well. However, we can take it one step further if you want to have different data on the back side of a Secondary Tile. Since Push Notifications are fully supported on 256-MB Windows Phone devices, you can use those to update the application tile, thus we will extend EvenTiles with Push Notification support.

There are even more optimizations that we can make when EvenTiles is running on a 256-MB device. To transfer data between the application and its PeriodicTask we were using a file, as explained when we discussed how data can be exchanged between different processes. This means that we don’t need that file when running on a 256-MB device. This makes running the application on a 256-MB device even more efficient. In case of a 256-MB device, we only store the string that needs to be displayed in the application settings. On all other devices, we also store that string in a file through the TileData helper class so the PeriodicTask can retrieve it, as shown in the following code snippet.

No transfer on 256-MB device

protected override void OnNavigatedFrom(System.Windows.Navigation.NavigationEventArgs e)
{
    if (!App.ActualSecBackContent.Equals(tbBackContent.Text))
    {
        App.ActualSecBackContent = tbBackContent.Text;
        if (!App.IsLowMemDevice)
        {
            TileData.SecondaryBackContent = tbBackContent.Text;
            TileData.ShowDefaultSecondaryBackContent = false;
        }
 
        var TileToFind = ShellTile.ActiveTiles.FirstOrDefault(x => x.NavigationUri.ToString().Contains("TileId=Secondary"));
 
        if (TileToFind != null)
        {
            StandardTileData NewTileData = new StandardTileData
            {
                BackContent = tbBackContent.Text
            };
 
            TileToFind.Update(NewTileData);
        }
    }
    base.OnNavigatedFrom(e);
}

If you are running EvenTiles on either a 256-MB Device or a 512-MB Device you don’t really experience any difference in performance. The application runs well, and it does not start noticeably slower on a 256-MB Device. Of course, EvenTiles uses only a limited amount of memory. The only difference you will notice is that the backside of the Secondary Tile will not display alternating texts. The reason is the absence of Background Agents on 256-MB devices, as you can see in the different screen dumps of both a 256-MB and a 512-MB emulator.

The complete sample code for EvenTiles so far can be downloaded here. If you want to test the application on a 256-MB device (emulator), you will need to download and install the Windows Phone 7.1.1 SDK Update as well. After installing this update, you can even run your application simultaneously on a 512-MB and a 256-MB emulator and compare the behavior on both of them.

The following video shows how to detect if your application is running on a 256-MB device and it shows how to limit functionality in that case.

Limiting functionality when running on 256-MB Windows Phone Devices

In the next episode of EvenTiles we will start talking about Push Notifications.

EvenTiles and TrialMode

In part 17 of EvenTiles we will take a look at Trial Mode. When an application supports trial mode, users can first try the application before buying it. It is up to you as the application developer to determine which functionality is available in the application when running in trial mode. Even though trial mode makes your application slightly more complex, the advantage of implementing trial mode is that you will only have to submit one single version of your application that customers can either try or buy. The application is started with either a trial license or a full license (when the user purchased the application). Inside the application, you can make use of an API to determine if a user is running your application in trial mode or not. From a technical point of view, there are no restrictions to trial mode, so you can even provide full application functionality in trial mode. Of course that does not make sense, because you typically want to use trial mode to invite end users to try your application after which they hopefully get so excited about your application that they determine to buy it.

NOTE: Be careful with providing a limited time to execute a fully functional application in trial mode, because end users can simply reinstall your application to again run the application for a certain amount of time in trial mode.

Let’s assume that EvenTile has two different modes of operation, implemented through Trial Mode. In Trial Mode, EvenTiles is fully functional without restrictions, however, the application will display ads on the main page (adding the actual advertisements to EvenTiles will be covered later in this series). As soon as users purchase EvenTiles, advertisements will be disabled. In trial mode, the application also contains functionality to retrieve location information in order to receive localized advertisements, although the user can disable location retrieval through the Settings Page of the application. However, if a user purchases the application, location information will not be retrieved and it does not make sense to have a toggle switch in the Settings Page to enable / disable location retrieval. Finally, if the user runs EvenTiles in trial mode, they have the option to purchase the application from within the application’s About Page. Of course, this option is only available in trial mode, if the application is already purchases, the About Page allows a user to display more applications that were published by DotNETForDevices.

Let’s begin by finding out how we can determine if the application is currently running in Trial Mode. In order to do so, as long as the user is running the application in Trial Mode, we will check the current application’s license each time the application starts or becomes the foreground application, and set a Boolean property accordingly. We also store the current value of that Boolean property in our application settings. When a user has purchased the application, we only have to check the application settings which results in faster starting / resuming of the application. The following code snippet shows how to determine if we are running in Trial mode:

Running in Trial Mode?

public const string keyTrialMode = "K_TRIAL";
public static bool IsTrialMode { get; private set; }
 
private void Application_Launching(object sender, LaunchingEventArgs e)
{
    if (!appSettings.Contains(keyTrialMode))
    {
        appSettings[keyTrialMode] = true;
    }
 
    IsTrialMode = (bool)appSettings[keyTrialMode];
 
    if (IsTrialMode)
    {
        CheckTrialMode();
    }
}
 
private void CheckTrialMode()
{
    IsTrialMode = new LicenseInformation().IsTrial();
}

This snippet only shows checking for Trial Mode when the application is launched. We first determine if we already stored the current license type in our application settings. If we assume we are running in Trial Mode we need to check if the license type has chanced since the last time the user ran the application. Since correct license information will only be added when the application is downloaded from the Windows Phone Marketplace, it might be a little tricky to test this functionality. When you installed the application locally on an unlocked device during testing of your application, or when you execute the application from within Visual Studio, the LicenseInformation.IsTrial method always returns false. With a little bit of conditional compilation, we can easily change this for test purposes. In the following code snippet you can see that we can test Trial mode when we are running the application in Debug mode and when the TRIAL symbol is defined. By simply setting this symbol to NO_TRIAL we can test the application for both different license types.

Testing Trial Mode

#if DEBUG
#define TRIAL
#endif
 
using System.Windows;
using Microsoft.Phone.Marketplace;
 
namespace EvenTiles
{
    public partial class App : Application
    {
        private void CheckTrialMode()
        {
#if ! TRIAL
            IsTrialMode = new LicenseInformation().IsTrial();
#endif
        }

In the OnLaunching method of the application, the IsTrialMode property is initialized to true and optionally modified by executing the CheckTrialMode method. If you want to test the application as if it was purchased by a user, you can simply change TRIAL to NO_TRIAL, recompile and execute the application again.

NOTE: If you take this approach, make sure that you install a clean copy of the application to a device or the emulator when switching back to trial mode. The way the code is organized, once the IsTrialMode property is set to false, the call to the LicenseInformation.IsTrial method is never executed again. To install a clean copy, make sure to rebuild your application in Visual Studio before deploying it, instead of simply building the application. After a rebuild, not only the application is replaced on the target device, but the entire IsolatedStorage area of the application is cleaned.

Testing a purchased app

#if DEBUG
#define NO_TRIAL
#endif
 
using System.Windows;
using Microsoft.Phone.Marketplace;
 
namespace EvenTiles
{
    public partial class App : Application
    {
        private void CheckTrialMode()
        {
#if ! TRIAL
            IsTrialMode = new LicenseInformation().IsTrial();
#endif
        }

Since Debug is not set in release mode, you will always call the LicenseInformation.IsTrial method when the application is deployed to a device.

Since we now have determined if the application is running in Trial Mode or not, we can simply use this information to display / hide the location retrieval toggle button on the Settings Page. Also, when can alter the functionality of one of the buttons on the About Page. If the application runs in Trial Mode, the user can purchase the application from within the About Page. If the user already has purchased the application, they can use the same button to check more applications from the same publisher, as shown in the following code snippet:

Changing button behavior

public partial class AboutPage : PhoneApplicationPage
{
    public AboutPage()
    {
        InitializeComponent();
 
        btnMore.Content = App.IsTrialMode ? "Purchase EvenTiles now" : "More from DotNETForDevices";
    }
 
    private void btnMore_Click(object sender, RoutedEventArgs e)
    {
        if (App.IsTrialMode)
        {
            MarketplaceDetailTask detailTask = new MarketplaceDetailTask();
            detailTask.Show();
        }
        else
        {
            var searchTask = new MarketplaceSearchTask
            {
                ContentType = MarketplaceContentType.Applications,
                SearchTerms = "DotNETForDevices"
            };
            searchTask.Show();
        }
    }
}

When the application is running, it either shows the location toggle switch and it provides different functionality in the About Page.

The following video shows how to add Trial Mode to the EvenTiles application. It also shows how you can test this functionality by making use of some conditional compilation.

Adding TrialMode to the application and testing TrialMode.

To be able to experiment with the functionality of EvenTiles as it is right now, the sample code is available for dowload here. In the next episode of EvenTiles we will talk about adding support to run EvenTiles on 256-MB Windows Phone devices.

You can already install the latest version of EvenTile on your own Windows Phone. from Marketplace. Remember that the application is not meant to be extremely useful, although it contains similar functionality that “serious” applications have. Just go ahead and get here: http://www.windowsphone.com/en-US/search?q=EvenTiles (or search on your phone for EvenTiles in the Marketplace application).

EvenTiles from Start to Finish–Part 16

In the previous episode of this series about how to develop a Windows Phone application from scratch you learned how to create the UI of a more or less typical About Page using Expression Blend. The About Page contains nothing fancy, just a number of TextBlocks and a few Buttons. Right now we are ready to add some functionality to the About Page to

Display the application’s version in a TextBlock
Submit an email containing remarks and/or suggestions to the application’s publisher
Submit a review for the application
Check Marketplace for more applications, available from the same publisher

In itself, these are all small, relatively easy and partly unrelated actions. However, the latter 3 items, even though different, all have something in common. In order to achieve the desired result, we will make use of functionality that is available in a Windows Phone, but outside of our application. To use that specific functionality, we will make use of different Windows Phone Launchers. You can think of a Launcher as a separate application that can be shared by our applications to allow users to perform some common tasks in a uniform and consistent way. The fact that a Launcher starts a separate, built-in application, has some consequences for our application that makes use of the Launcher. When the application we launched becomes active, our application will be moved to the background. This means that our application will temporarily be paused and even be tombstoned in low memory / resource situations. Since we already took care of properly dealing with our application being moved to the background (see episode 7 about Tombstoning), this is not a big deal but it is good to realize what is happening under the covers of the Windows Phone platform.

Note: Usually Launchers are mentioned together with Choosers because they provide similar functionality and operate more or less the same. The big difference between them is that a Chooser (as the word implies) is capable of selecting some data (for instance a picture) and return the selected item to our application. Choosers will be covered in a later episode of EvenTiles.

As always, it makes a lot of sense to see things in action and to take a look at actual code. That is the reason why, besides these series of blog entries, there are also accompanying videos and sample code available for download.

Retrieving the application’s version number

The first goal we want to achieve is to retrieve the version number of our application and display it in the About page. Since our application stores its own version number in its manifest file, we want to retrieve it from there.

NOTE: The version number must also be specified when submitting an application to the Windows Phone Marketplace. According to the documentation, this version number must match your application’s version number but maintaining it in your manifest file is a separate activity. There is yet another version number, stored in the application’s AssemblyInfo.cs file and modifiable through the project properties. In EvenTiles we ignore the latter and retrieve the version number immediately from the application’s manifest file.

Application version numbers consist of major, minor, build, and revision components. To match the version number as it is showed in the Windows Phone Marketplace, we only want to display the major and minor parts of the application. Since the application manifest file is just another XML file, we can easily retrieve the version number from it.

Version info in manifest file

<App xmlns="" 
     ProductID="{883385e6-52e5-4835-83db-8a17499b5767}" 
     Title="EvenTiles" 
     RuntimeType="Silverlight" 
     Version="1.0.0.0" 
     Genre="apps.normal" 
     Author="Maarten Struys" 
     Description="Sample description" 
     Publisher="DotNETForDevices">

To retrieve the version number and to display it in a Textblock inside the About Page, we can just load the XML from the manifest file and find the value of the version attribute of the App element. The reason why this works is because the application manifest file (WMAppManifest.xml) is deployed to the phone as part of the XAP file.

Get version from manifest file

private string GetVersionNumber()
{
    string[] version = XDocument.Load("WMAppManifest.xml").Root.Element("App").Attribute("Version").Value.Split('.');
 
    StringBuilder sb = new StringBuilder(version[0]);
    sb.Append(".");
    sb.Append(version[1]);
    versionNumber = sb.ToString();
 
    return versionNumber;
}
 
private void PhoneApplicationPage_Loaded(object sender, RoutedEventArgs e)
{
    tbVersion.Text = GetVersionNumber();
}

Sending an email

A nice feature inside a Windows Phone application is the possibility for end users to get in touch with you through email. Making this as easy as possible for end users might result in you getting some useful feedback about your application and might also increase the user’s satisfaction with your application, which in turn might lead to better and more reviews. To send an email programmatically to a fixed email address is very simple. You simply can make use of the EmailComposeTask and even pre-populate information in the email to make it easier for the end user to send out an email. The following code shows how to send an email programmatically:

Using the EmailComposeTask

private void btnEmail_Click(object sender, RoutedEventArgs e)
{
    StringBuilder sb = new StringBuilder("Feedback / Support for EvenTiles ");
    sb.Append(versionNumber);
 
    var emailComposeTask = new EmailComposeTask
    {
        To = "mstruys@hotmail.com",
        Subject = sb.ToString()
    };
    emailComposeTask.Show();
}

NOTE: In order to test this functionality, you have to use a physical device. The Windows Phone Emulator will throw an exception when using the email compose task.

Submitting a review

If you know how to use one Windows Phone Launcher you basically know how to use them all. Since we already saw that sending an email is a very simple operation (creating a new object, setting some properties and calling the Show method on the object), submitting a review should not be difficult. The following code shows how to allow your users to submit a review by using the MarketplaceReviewTask Launcher:

Submitting a review

private void btnReview_Click(object sender, RoutedEventArgs e)
{
    MarketplaceReviewTask reviewTask = new MarketplaceReviewTask();
    reviewTask.Show();
}

Of course, this code can be extended, for instance by storing in the application settings if a review has already been submitted. If so, we can for instance remove the button to submit a review from the application. We can also verify if we currently have a data connection in order to submit a review. All this functionality is omitted in this sample code.

Checking for more applications

Using the same approach as described before, we can also allow the user to look for more applications that we already published on the Windows Phone Marketplace. This can be achieved by using the MarketplaceSearchTask, again in a similar way:

Finding apps on Marketplace

private void btnMore_Click(object sender, RoutedEventArgs e)
{
    var searchTask = new MarketplaceSearchTask
    {
        ContentType = MarketplaceContentType.Applications,
        SearchTerms = "DotNETForDevices"
    };
    searchTask.Show();
}

The MarketplaceSearchTask is a very nice marketing instrument because you can guide users of your application to other Windows Phone applications you have published.

The following video shows how to create the functionality we described in this episode of EvenTiles. It also shows two of the described Launchers in action, one running in the emulator, one on a physical device.

Using Launchers inside a Windows Phone Application

To be able to experiment with this working implementation of EvenTiles, especially to understand how the application interacts with the PeriodicTask through a file in IsolatedStorage, the sample code is available for dowload here. In the next episode of EvenTiles we will talk about implementing Trial Mode in your application to allow users to try the application before optionally buying it.

If you want to see EvenTiles already in action on your Windows Phone, you can also install the latest free version from Marketplace. Remember that this application is not meant to be extremely useful, although it contains similar functionality that “serious” applications have. Just go ahead and get your free copy of EvenTiles from Marketplace at this location: http://www.windowsphone.com/en-US/search?q=EvenTiles (or search on your phone for EvenTiles in the Marketplace application).

EvenTiles Until Now (A Windows Phone Development Series)

Looking at all the different topics that the EvenTiles series covers, I think it makes sense to at least have a table of contents for the series so far. For instance, if you are interested in reading something about tombstoning, it is not necessary to read through the entire series (although of course I invite you to do so anyway). At this moment, EvenTiles explains how to use Windows Phone Tiles, including Secondary Tiles. It also show how you can update content on your Tiles locally by using a Background Agent. Also don’t forget that all source code is available and each individual episode of EvenTiles contains a demo on video as well. The latest sample source code can be downloaded.

Here is the table of contents for the first 14 parts of EvenTiles:

Introducing the EvenTiles application

Creating a new project in Visual Studio 2010 Express for Windows Phone
Defining an Application Tile from within the WMAppManifest.xml file
Using the emulator to run the application

PageNavigation and ApplicationBar

Using Expression Blend to create an Application Bar
Navigating to different pages by using the NavigationService

Using the Silverlight for Windows Phone Toolkit in your application

Defining page transitions in XAML and using them in your application
Using styles in XAML
Declaring and using a ToggleSwitch control

Creating the Settings Page

Designing a Windows Phone page using Expression Blend
Executing code as a result of page navigation (using OnNavigatingTo and OnNavigatingFrom)
Using event handlers to execute code on user interaction with UI elements

Using IsolatedStorage

Storing data in between different times an application executes
Introducing the application life cycle
Using IsolatedStorageSettings to persist information

Using the Isolated Storage Explorer Tool

Examining the contents of our application’s IsolatedStorage

Fast Application Switching and Tombstoning

A Windows Phone Application’s life cycle
Saving application state when moved to the background
Restoring application state when returning to the foreground

More on Tombstoning

Maintaining Page State
Restoring a page to exactly the same situation it was when the application moved to the background
Restoring focus of input UI elements

Creating a Secondary Tile

Creating a Secondary Tile inside your application
Navigating from the Secondary Tile to the application
Determine if a Secondary Tile is currently visible on the Start screen of a Windows Phone through a lambda expression
Setting the front and back contents of a Secondary Tile

Background Agents

Different types of Background Agents
Properly creating a PeriodicTask
Starting and stopping a PeriodicTask
Relation between an Application and a Background Agent

Debugging Background Agents

Using conditional compilation to test Background Agents
Properly using the LaunchForTest method
Using the debugger to debug a PeriodicTask

The lifetime of PeriodicTask

Rescheduling a PeriodicTask
Exceptions that might be thrown when scheduling a PeriodicTask

Communication between an Application and its PeriodicTask

Passing data between an application and a PeriodicTask
Protecting variables against simultaneous access by different threads
Using a Mutex to synchronize threads

Exchanging data between an Application and its PeriodicTask

Using a file in IsolatedStorage to exchange data between an application and a PeriodicTask

Even though there are many more episodes of EvenTiles planned, attention will now move beyond tiles as we focus on using built-in applications and accessing device hardware.

MessageBox, Navigation and Application Life Cycle

One of our applications failed certification today because of an issue I should have known about. Even though the scenario in which an exception occurs is fairly easy, solving the problem properly involves a little work and a little thinking. Other blog entries have been written about this particular problem, although suggested solutions did not seem to work for me. Let me first show the original code:

MessageBox and Navigation

private void TurnCard_Click(object sender, System.Windows.RoutedEventArgs e)
{
    MessageBoxResult mr = MessageBoxResult.Cancel;
 
    if (nrTimesClicked > 2)
    {
        mr = MessageBox.Show("Continuing now might confuse you. Try again tomorrow?", 
            "Continuing tomorrow?", MessageBoxButton.OKCancel);
    }
 
    if (mr == MessageBoxResult.OK)
    {
        NavigationService.GoBack();
    }
    else
    {
        Random r = new Random();
        int card = r.Next(cardPages.Length);
        NavigationService.Navigate(new Uri(cardPages[card], UriKind.Relative));
        nrTimesClicked++;
    }
}

Running this code and clicking the Start button on the phone while the MessageBox is visible results in the following exception when running with the debugger attached (it results in an application termination when running stand-alone):

The NavigationFailed event is raised. This is caused by the fact that the MessageBox returns when clicking the phone’s Start button with a return value of MessageBoxResult.Cancel. Since in the above code fragment, the Cancel button is used to navigate to some page, even though the application is supposed to go to the background in order to display the start screen on the phone, navigation fails. The interesting part is that the application does not have a clue that the user pressed the Start button on the phone. So some thinking is required to fix this issue.

Single stepping through the problematic method TurnCard_Click showed another behavior:

This at least made clear that indeed the call to the NavigationService caused the problem. To solve the problem, what can be done is protecting calls to the NavigationService by catching this particular exception:

Protecting the Navigate method

private void TurnCard_Click(object sender, System.Windows.RoutedEventArgs e)
{
    MessageBoxResult mr = MessageBoxResult.Cancel;
 
    if (nrTimesClicked > 2)
    {
        mr = MessageBox.Show("Continuing now might confuse you. Try again tomorrow?", 
            "Continuing tomorrow?", MessageBoxButton.OKCancel);
    }
 
    if (mr == MessageBoxResult.OK)
    {
        NavigationService.GoBack();
    }
    else
    {
        Random r = new Random();
        int card = r.Next(cardPages.Length);
        try
        {
            NavigationService.Navigate(new Uri(cardPages[card], UriKind.Relative));
        }
        catch (InvalidOperationException)
        {
            ;
        }
        nrTimesClicked++;
    }
}

This does solve the problem, although I don’t like it that an exception is thrown in a situation that the operating system should somehow prevent us against (maybe by returning some other value when the MessageBox returns without the user clicking on one of its buttons). If you want to have a little more flexibility, and don’t mind coding a bit more, there is another possible solution. Instead of using a MessageBox, you can make use of the Guide.BeginShowMessageBox method that is defined in the XNA Framework. This method is a bit more complex, but also much more flexible then its Silverlight counterpart. BeginShowMessageBox is asynchronous, which means that you need to take care with calling code that is supposed to run on the UI Thread.

Using BeginShowMessageBox

private void TurnCard_Click(object sender, System.Windows.RoutedEventArgs e)
{
    if (nrTimesClicked > 2)
    {
        ShowContinueMessage();
    }
    else
    {
        Random r = new Random();
        int card = r.Next(cardPages.Length);
        nrTimesClicked++;
        NavigationService.Navigate(new Uri(cardPages[card], UriKind.Relative));
    }
}
 
private void ShowContinueMessage()
{
    List<string> mbOptions = new List<string>();
    mbOptions.Add("OK");
    mbOptions.Add("Cancel");
    string msg = "Continuing now might confuse you. Try again tomorrow?";
    string title = "Continuing tomorrow?";
    Guide.BeginShowMessageBox(title, msg, mbOptions, 0, MessageBoxIcon.Alert, EnteredAnswer, null);
    messageBoxVisible = true;
}
 
private void EnteredAnswer(IAsyncResult ar)
{
    int? result = Guide.EndShowMessageBox(ar);
 
    if (result != null)
    {
        messageBoxVisible = false;
    }
 
    if (result != null && result == 0)
    {
        this.Dispatcher.BeginInvoke(delegate
        {
            NavigationService.GoBack();
        });
    }
    else if (result != null)
    {
        Random r = new Random();
        int card = r.Next(cardPages.Length);
        this.Dispatcher.BeginInvoke(delegate
        {
            NavigationService.Navigate(new Uri(cardPages[card], UriKind.Relative));
        });
    }
}

The interesting code can be found in the EnteredAnswer method, where we retrieve the key the user entered in the message box. Since EndShowMessageBox returns a nullable integer, it has this nice way of using null in those cases where the user did not click any key (in other words, for instance when the message box is removed as a result of the application going to the background). So now we have a way of detecting if we can navigate (result has a value other then null). The sample code also sets a boolean variable messageBoxVisible, which is used in combination with PhoneApplicationPage.State to display the message box again when the user returns to the application. Hopefully this time the application will pass certification.

EvenTiles from Start to Finish–Part 14

In the previous episode of this series about how to develop a Windows Phone application from scratch we found out that special care must be taken when data must be passed between an application and its PeriodicTask. You learned how data can be protected against mutual access by using a Mutex object. You also learned that you cannot pass data directly from one to another, because the application and its PeriodicTask execute inside different processes.

In this episode of EvenTiles you will learn how you can make use of IsolatedStorage to pass data from the application to the PeriodicTask. Since we already created a separate project in the EvenTiles solution that is taking care of passing data, we can simply modify functionality in that project (EvenTilesComm) to use a file to pass data between the application and its PeriodicTask. Data protection against mutual access is already in place, so we can concentrate on file access. Hopefully the design decision in part 13 to make use of private methods that are called each time we access a public property inside the TileData class starts to make sense now.

What we want to achieve is the following:

From inside the application we can store a string containing content for the backside of a Secondary Tile in a file at any time
Our PeriodicTask executes approximately once per 30 minutes and it either displays the string passed by the application on the backside of the Secondary Tile or it displays a default string that is defined inside the PeriodicTask
The content of the backside of the Secondary Tile needs to toggle each time the PeriodicTask executes
If the EvenTiles user modifies the string to be displayed inside the Settings page, it will immediately be displayed on the Secondary Tile (if it exists)

In order to pass data between the application and the PeriodicTask we will extend the private retrieve / store methods inside the TileData class by adding a call to a couple of other private methods. Those new private methods will use a file in IsolatedStorage to read / write data from, meaning we can effectively pass data between the application and its PeriodicTask.

Properties to access Tile Data

private static string RetrieveSecondaryBackContent()
{
    mtx.WaitOne();
 
    try
    {
        RetrieveTileContent();
        return secondaryBackContent;
    }
    finally
    {
        mtx.ReleaseMutex();
    }
}
 
private static void StoreSecondaryBackContent(string content)
{
    mtx.WaitOne();
 
    try
    {
        secondaryBackContent = content;
        PersistTileContent();
    }
    finally
    {
        mtx.ReleaseMutex();
    }
}

A new string to be displayed on the back side of a Secondary Tile will be stored by the application each time users modify their own tile text in the Settings Page of the EvenTiles application (something that will also be done initially when the application starts). The PeriodicTask simply retrieves that data (since now the data is persisted in a file this will work properly) and displays it on the back side of the Secondary Tile. Each time data needs to be stored a new file is created in IsolatedStorage or an existing file is overwritten. Each time data needs to be retrieved, we check if a file containing that data exists. There are small ways to optimize data access in the TileData class, because right now we simply read / write all file content when retrieving / storing single property values. However, this approach simplifies the code and the overhead with only two different variables is very small.

Using IsolatedStorage

private const string contentFileName = "EvenTileContent.txt";
 
private static void PersistTileContent()
{
    using (var store = IsolatedStorageFile.GetUserStoreForApplication())
    {
        using (var contentStream = new StreamWriter(store.CreateFile(contentFileName)))
        {
            contentStream.WriteLine(showDefaultSecondaryBackContent.ToString());
            contentStream.WriteLine(secondaryBackContent);
        }
    }
}
 
private static void RetrieveTileContent()
{
    using (var store = IsolatedStorageFile.GetUserStoreForApplication())
    {
        if (store.FileExists(contentFileName))
        {
            using (var contentStream = new StreamReader(store.OpenFile(contentFileName, FileMode.Open)))
            {
                showDefaultSecondaryBackContent = Convert.ToBoolean(contentStream.ReadLine());
                secondaryBackContent = contentStream.ReadToEnd();
            }
        }
    }
}

With the way we organized the functionality inside the TileData class in the previous episode of this development series, these are the only new methods necessary in order to pass data. When the user installs a Secondary Tile for the EvenTiles application and modifies its back string content through the Settings page, this is the result (changing the back content of the Secondary Tile every 30 minutes):

The following video shows EvenTiles in action with proper transfer of data between the application and its PeriodicTask.

Data transfer between an Application and a PeriodicTask through IsolatedStorage

Right now we have the basic functionality of EvenTiles more or less ready, although the About Page still needs to get some content. That is something we will work on in the next part of EvenTiles. After that we will cover much more in the upcoming episodes of EvenTiles including but not limited to

using ads in the application
retrieving location information inside the application
taking pictures
modifying pictures
using alarms and notifications
using Visual Studio’s integrated Performance Analysis to find performance bottlenecks inside the application
submitting the application for certification

EvenTiles will continue soon so stay tuned for the next episode.

If you want to see EvenTiles already in action on your Windows Phone, you can also install the latest version from Marketplace. Remember that this application is not meant to be extremely useful, although it contains similar functionality that “serious” applications have. Just go ahead and get your free copy of EvenTiles from Marketplace at this location: http://www.windowsphone.com/en-US/search?q=EvenTiles (or search on your phone for EvenTiles in the Marketplace application).

EvenTiles from Start to Finish–Part 13

In the previous episode of this series about how to develop a Windows Phone application from scratch we fixed some issues to properly start and renew a PeriodicTask. Now we are ready to find out how an application can communicate with its PeriodicTask.

In today’s EvenTiles episode, you will learn why you cannot simply use a variable to communicate between the application and the PeriodicTask. In my opinion that is important, because understanding why some things are not working makes you a better Windows Phone developer and decreases the chance of having hard to trace bugs inside your own applications. In order to separate the functionality to transfer data between the application and its PeriodicTask, we are going to create a new project inside the EvenTiles solution.

The project will be of type Windows Phone Class Library and we will call it EvenTilesComm. In its initial version, this class library will contain one single class with the name TileData. It is used to store the text that the user can enter in the Settings Page of the EvenTiles application in order to allow the PeriodicTask to display this string on the back of the Secondary Tile once it is created. In order to vary the text on the back of the Secondary Tile, TileData will also contain a boolean variable indicating which string needs to be displayed on the Secondary Tile’s backside (either the string passed by the application or a default string that is defined inside the PeriodicTask).

To be able to access TileData from within both the EvenTiles application and the PeriodicTask, it contains two static properties. A string property to store / retrieve the message that is defined through the Settings Page and a boolean property that defines which string needs to be displayed from within the PeriodicTask. The string property is always written by the application and read by the PeriodicTask. The boolean variable is both written by the application and the PeriodicTask but only read by the PeriodicTask. Because of the fact that the PeriodicTask and the application are running inside their own, separate process in different threads, and since they are running completely unsynchronized from each other, there is a possibility that they both want to access one of the properties of TileData at the same time. To prevent this potential dangerous situation (dangerous because it can leave the properties in an undefined state when one of the two different threads want to access them while the other is updating them), both properties are protected by a Mutex synchronization object.

NOTE: The following (initial) implementation of the TileData class will not work properly, but it is shown here to help you understand what it means that an application and its PeriodicTask belong to each other, but are completely separated from each other at the same time. You will have to wait a little while for a working solution, because that will be introduced in the next episode of EvenTiles.

Threadsafe Data Access

public class TileData
{
    private static Mutex mtx = new Mutex(false, "MtxSync");
 
    private static string secondaryBackContent;
    private static bool showDefaultSecondaryBackContent;
 
 
    public static string SecondaryBackContent
    {
        get
        {
            return RetrieveSecondaryBackContent();
        }
        set
        {
            StoreSecondaryBackContent(value);
        }
    }
 
    public static bool ShowDefaultSecondaryBackContent
    {
        get
        {
            return RetrieveShowDefaultSecondaryBackContent();
        }
        set
        {
            StoreShowDefaultSecondaryBackContent(value);
        }
    }
 
    private static string RetrieveSecondaryBackContent()
    {
        mtx.WaitOne();
 
        try
        {
            return secondaryBackContent;
        }
        finally
        {
            mtx.ReleaseMutex();
        }
    }
 
    private static void StoreSecondaryBackContent(string content)
    {
        mtx.WaitOne();
 
        try
        {
            secondaryBackContent = content;
        }
        finally
        {
            mtx.ReleaseMutex();
        }
    }
 
    private static bool RetrieveShowDefaultSecondaryBackContent()
    {
        mtx.WaitOne();
 
        try
        {
            return showDefaultSecondaryBackContent;
        }
        finally
        {
            mtx.ReleaseMutex();
        }
    }
 
    private static void StoreShowDefaultSecondaryBackContent(bool showDefaultContent)
    {
        mtx.WaitOne();
 
        try
        {
            showDefaultSecondaryBackContent = showDefaultContent;
        }
        finally
        {
            mtx.ReleaseMutex();
        }
    }
}

If you look at the source code of the TileData class, you can see that we are using a two properties through which we are calling a few private methods to actually store or retrieve data. You will also see that we define a single Mutex inside the TileData class. This Mutex has a name, meaning it can be used to synchronize threads over multiple processes. This is important, since EvenTiles and its PeriodicTask will execute in separate processes. If we take a look at one of the individual retrieval methods, you will see how the single Mutex that is defined in TileData is used.

Retrieving data

private static string RetrieveSecondaryBackContent()
{
    mtx.WaitOne();
 
    try
    {
        return secondaryBackContent;
    }
    finally
    {
        mtx.ReleaseMutex();
    }
}

In this method, we access the variable secondaryBackContent only when the method WaitOne on our Mutex returns. When WaitOne returns, our method has exclusive access to the variable secondaryBackContent until we call the method ReleaseMutex on our Mutex. At that moment, another thread that is waiting for the same Mutex will be granted access. Every method that uses of a Mutex to get access to protected data must under all circumstances call ReleaseMutex when it is done. That is the reason why we are adding a try / finally block. The code in the finally block will execute, even when exceptions are thrown. In this way, we prevent our application from a potential deadlock situations (where multiple threads are waiting on each other to free up a synchronization object that is never being freed).

The way data is protected for EvenTiles works properly, which can be verified by debugging the application and deliberately skipping a call to ReleaseMutex from within the EvenTiles application (which is fully explained in the accompanying video as well). Doing so will result in the PeriodicTask waiting forever for the Mutex, because it will never be released by the application. This at least proves that both EvenTiles and its PeriodicTask are making use of the same Mutex that they both need to own before being able to access variables.

There is still a potential problem, because we are calling the WaitOne method without parameters, which means that we will wait indefinitely until the Mutex becomes available. In our simple example this is sufficient, but in a real application you most likely want to wait for a specific time and take action upon timeouts.

However, there is a way bigger problem with the current implementation of our newly created TileData class. We already saw that the Mutex is properly shared between EvenTiles and its PeriodicTask, but what about the public properties. The following screen dump shows you what is wrong with the TileData class right now. Even though the variable secondaryBackContent is set by the EvenTiles application, it seems that it is not initialized when the PeriodicTask retrieves the variable (both through the appropriate properties).

Since our EvenTiles application and its PeriodicTask are running in separate processes, they are completely separated from each other, meaning that they get their own copies of variables they both want to access, even though these variables are defined in a separate project. This is a good thing (even though we have to solve the problem), because otherwise all variables used by every process on the phone would need a unique name. The following video shows EvenTiles in action in combination with its PeriodicTask. It shows how the Mutex works and how passing data fails.

Protecting variables against simultaneous access by multiple threads

To be able to experiment with this wrong implementation of EvenTiles, especially to understand how the application interacts with the PeriodicTask, the sample code is available for dowload here.

Instead of using ‘simple’ variables to pass data between EvenTiles and its PeriodicTask, we will have to make use of IsolatedStorage and have them share data through a file. That will be the topic of the next episode of EvenTiles.

EvenTiles from Start to Finish–Part 12

In the previous episode of this series about how to develop a Windows Phone application from scratch we talked about debugging a PeriodicTask. Before digging deeper into exchanging data between an application and its PeriodicTask, we need to talk a little more about scheduling the PeriodicTask and about expiration of a PeriodicTask.

Going back to part 10 of the EvenTiles series, the PeriodicTask was created inside the MainPage.xaml.cs file in a method called StartPeriodicAgent. This private method takes care of stopping a currently active agent before creating a new one. It also handles an exception that might be thrown when an attempt is made to start a new PeriodicTask while the user has disabled background processing for the EvenTiles application, which they can do from inside the Phone Settings.

However, after submitting EvenTiles to Marketplace, I noticed an exceptionally high crash count in the application (as you can see from my AppHub dashboard). Since I want to share all details about developing this application, but also about the application’s life cycle, it is only fair to share the number of crashes to date, a number I am not proud off.

For starters, the first version of EvenTiles called LaunchForTest in release mode which results in a thrown exception as shows up in the call stack of various crash incidents. Also, the application does not count on other applications making use of background agents on a particular device. To preserve memory, but mainly battery power on the device, the number of background agents that can run at the same time is limited. It varies depending on the hardware capabilities of the device and might differ between devices, but it is a small number and therefore the limit can easily be reached. When this limit is reached, a SchedulerServiceException will be thrown whenever you attempt to add a periodic task. Of course you much handle this exception to prevent your application against crashing, since you are adding your periodic task from inside your application.

So, to create a periodic task, the following code should be used (which is an extension to the code that we used in part 10 of the series):

Correctly adding the agent

private void StartPeriodicAgent()
{
    RemovePeriodicAgent();
 
    var evenTilesPeriodicTask = new PeriodicTask(evenTilesPeriodicTaskName);
    evenTilesPeriodicTask.Description = "EvenTilesPeriodicTask";
 
    try
    {
        ScheduledActionService.Add(evenTilesPeriodicTask);
#if DEBUG_TASK
        ScheduledActionService.LaunchForTest(evenTilesPeriodicTaskName, TimeSpan.FromSeconds(30));
#endif
        App.PeriodicTaskScheduled = true;
    }
    catch (InvalidOperationException ex)
    {
        if (ex.Message.Contains("BNS Error: The action is disabled"))
        {
            MessageBox.Show("Background agents for this application are disabled.");
        }
    }
    catch (SchedulerServiceException)
    {
        MessageBox.Show("Can't schedule your background agent. There might be too many background agents enabled. You can disable background agents through the phone's settings application.");
    }
}

If you take a look at how a periodic task is created you will also see that a App.PeriodicTaskScheduled is set to true. This static property is maintained in the App.xaml.cs file, its value is stored / retrieved from the IsolatedStorageSettings (see part 5 of EvenTiles for more information).

The reason to add this boolean property is to find out if the application did schedule a PeriodicTask. If a PeriodicTask was added for the application, you must realize that the PeriodicTask will age and eventually it will expire unless it is rescheduled by the application. A PeriodicTask will expire if it has not been rescheduled for 14 days from the time it was scheduled. Since the application is responsible for adding a PeriodicTask, it means that the PeriodicTask will only continue to run if the application is activated at least once every two weeks and if the application makes sure to reschedule the PeriodicTask. The approach that EvenTiles takes right now is to check if at some time a PeriodicTask was scheduled. If so, it will be rescheduled as soon as the EvenTiles’ MainPage is created.

NOTE: We could have used another way to determine if a PeriodicTask was scheduled, for instance by verifying if a SecondaryTile is currently available on the StartScreen.

Making use of IsolatedStorageSettings, we will add logic to the app.xaml.cs file to properly store and retrieve the App.PeriodicTaskScheduled property when the application is started, activated, deactivated and terminated.

To begin, a new property and a new const string to identify the value in the IsoloatedStorageSettings are created in app.xaml.cs as follows:

public const string keyPTScheduled = "K_PTS";
 
public static bool PeriodicTaskScheduled { get; set; }

In the constructor, the PeriodicTaskScheduled property is explicitly initialized to false. Finally, the value of PeriodicTaskScheduled is stored / retrieved in the various application life cycle events:

Store/Retrieve property value

// Code to execute when the application is launching (eg, from Start)
// This code will not execute when the application is reactivated
private void Application_Launching(object sender, LaunchingEventArgs e)
{
    if (appSettings.Contains(keyPTScheduled))
    {
        PeriodicTaskScheduled = (bool)appSettings[keyPTScheduled];
    }
 
    if (!appSettings.Contains(keyActSecBackContent))
    {
        appSettings[keyActSecBackContent] = DefaultSecBackContent;
    }
    ActualSecBackContent = (string)appSettings[keyActSecBackContent];
}
 
// Code to execute when the application is activated (brought to foreground)
// This code will not execute when the application is first launched
private void Application_Activated(object sender, ActivatedEventArgs e)
{
    if (!e.IsApplicationInstancePreserved)
    {
        PeriodicTaskScheduled = (bool)appSettings[keyPTScheduled];
        ActualSecBackContent = (string)appSettings[keyActSecBackContent];
    }
}
 
// Code to execute when the application is deactivated (sent to background)
// This code will not execute when the application is closing
private void Application_Deactivated(object sender, DeactivatedEventArgs e)
{
    appSettings[keyPTScheduled] = PeriodicTaskScheduled;
    appSettings[keyActSecBackContent] = ActualSecBackContent;
}
 
// Code to execute when the application is closing (eg, user hit Back)
// This code will not execute when the application is deactivated
private void Application_Closing(object sender, ClosingEventArgs e)
{
    appSettings[keyPTScheduled] = PeriodicTaskScheduled;
    appSettings[keyActSecBackContent] = ActualSecBackContent;
}

Finally, we will use this property inside the MainPage.xaml.cs file when the page is constructed to determine if we need to reschedule a PeriodicTask:

Rescheduling PeriodicTask?

public MainPage()
{
    InitializeComponent();
    if (App.PeriodicTaskScheduled)
    {
        StartPeriodicAgent();
    }
}

Each time the PeriodicTask is scheduled, the App.PeriodicTaskProperty is set to true and a Secondary Tile is created. If the Secondary Tile is removed, the App.PeriodicTaskProperty is set to false as well.

The following video shows you how to modify the existing EvenTiles project to improve the way the PeriodicTask is scheduled as well as the functionality needed to reschedule the PeriodicTask:

Rescheduling a PeriodicTask

If you want to take a look at the source code that we have available for EvenTiles so far, you can download the entire solution belonging to this episode:

Download EvenTiles Episode 12 Source Code

After downloading and unzipping the sample code, you can open the EvenTiles solution in Visual Studio 2010 Express for Windows Phone. You must have the Windows Phone SDK 7.1 installed on your development system to do so. If you have a developer unlocked phone you can deploy the application to your phone, if you don’t have a developer unlocked phone you can still experiment with this application inside the emulator.

If you want to see EvenTiles already in action on your Windows Phone, you can also install the latest version from Marketplace. Remember that this application is not meant to be extremely useful, although it contains similar functionality that “serious” applications have. Just go ahead and get your free copy of EvenTiles from Marketplace at this location: http://www.windowsphone.com/en-US/search?q=EvenTiles (or search on your phone for EvenTiles in the Marketplace application).

When EvenTiles continues with part 13, you will learn how to exchange data between an application and its background agent.