Friday, September 24, 2010

Chrysalis – Tombstoning support (Part I - Introduction)

As I discussed in my previous post, when you are writing Silverlight (or XNA) based Windows Phone 7 applications, one of the considerations you must make is regarding supporting the “tombstoning” of your application. At any point during its execution your application may receive notification that you must save any state and exit, to possibly (but not always) be restarted at a later point. This however is you application’s view – to the user they must believe that you application was waiting patiently in the background, unaware of the tearing down and restarting that is actually occurring.

If you are following the Model-View-ViewModel presentation pattern then the best placed entity in the system to know about what state to persist when tombstoning is the ViewModel. You have to firstly ensure that the application subscribes correctly to the PhoneApplicationService.Deactivated and PhoneApplicationService.Activated events. These must pass the requests onto the ViewModel which must store its state in the correct locations. Upon reactivation the ViewModel must know that it has some stored state, retrieve it and then restore the UI to that before the deactivation.

Transparently handling these steps is one of the key features of the Chrysalis framework.

How to use Chrysalis for Tombstoning?

Supplied with yesterdays drop of the Chrysalis framework is a sample calculator application. Whilst not particularly useful, it is intended to show how Chrysalis simplifies tombstoning. At its heart is the CalculatorViewModel.

   1: public class CalculatorViewModel : ViewModelBase
   2: {
   3:     // *** Fields ***
   4:     
   5:     private int numberX = 10;
   6:     private int numberY = 5;
   7:     
   8:     // *** Properties ***
   9:     
  10:     public int NumberX
  11:     {
  12:         get
  13:         {
  14:             return numberX;
  15:         }
  16:         set
  17:         {
  18:             numberX = value;
  19:             OnPropertyChanged("NumberX");
  20:             OnPropertyChanged("Total");
  21:         }
  22:     }
  23:     
  24:     public int NumberY
  25:     {
  26:         get
  27:         {
  28:             return numberY;
  29:         }
  30:         set
  31:         {
  32:             numberY = value;
  33:             OnPropertyChanged("NumberY");
  34:             OnPropertyChanged("Total");
  35:         }
  36:     }
  37:     
  38:     public int Total
  39:     {
  40:         get
  41:         {
  42:             return NumberX + NumberY;
  43:         }
  44:     }
  45: }

This derives from Chrysalis.ViewModelBase base class and includes three properties. The properties ‘NumberX’ and ‘NumberY’ are editable and both bound to TextBoxes in the associated UI (CalculatorView.xaml). The ‘Total’ property simply returns the sum of the two other values and is bound to a read-only TextBox in the UI. Property changed notifications are raised by calling OnPropertyChanged(…) on the base class.


At this stage everything will look familiar to the Silverlight or WPF developer, and the application will run as expected,


Calculator


The problem occurs if we now deactivate and reactivate the application. In the emulator provided with the developer tools you can do this by clicking the “Start” button to return to the start page, then clicking “Back” to return to your application. This will result in all values being reset to their initial values as we are not persisting any state. Remember though that the user should believe that the application has been sitting patiently in the background, and expects all the values to be consistent with that.


To solve this problem Chrysalis.ViewModelBase provides a couple of virtual methods that you can override.



protected virtual object SaveState() {...}
protected virtual void RestoreState(object state) {...}

The SaveState() method is called when your application is being deactivated and can return some state to be persisted. The RestoreState(…) method is called when your application is being activated and returns the state so that you can restore the property values, and hence the UI.


Also, to enable the Chrysalis support we need to add a couple of lines to the App.xaml. Firstly an ‘xmlns’ definition at the top of the file to reference the Chrysalis.Services namespace, and the <csv:ChrysalisService/> item in the ApplicationLifettimeObjects section. Appart from those changes (shown in the code below) ,the rest of the App.xaml file can be left as is.



   1: <Application 
   2:     ...
   3:     xmlns:csv="clr-namespace:Chrysalis.Services;assembly=Chrysalis">
   4:  
   5:     <Application.ApplicationLifetimeObjects>
   6:         ...
   7:         <csv:ChrysalisService/>
   8:     </Application.ApplicationLifetimeObjects>
   9:  
  10: </Application>

For our calculator sample we do this with a class ‘CalculatorViewModelState’. Note: This class must be declared with public scope. Since this will be serialized transparently by the phone for the duration of deactivation, we need it to be public otherwise we will receive a SecurityException when the phone tries to deserialize it.



   1: // *** Overriden Base Methods ***
   2:  
   3: protected override object SaveState()
   4: {
   5:     return new CalculatorViewModelState()
   6:     {
   7:         NumberX = numberX,
   8:         NumberY = numberY
   9:     };
  10: }
  11:  
  12: protected override void RestoreState(object state)
  13: {
  14:     CalculatorViewModelState vmState = (CalculatorViewModelState)state;
  15:  
  16:     if (vmState != null)
  17:     {
  18:         NumberX = vmState.NumberX;
  19:         NumberY = vmState.NumberY;
  20:     }
  21: }
  22:  
  23: // *** Sub-classes ***
  24:  
  25: public class CalculatorViewModelState
  26: {
  27:     public int NumberX { get; set; }
  28:     public int NumberY { get; set; }
  29: }

We simply set the properties and return the state within the SaveState() method, and restore the values in the RestoreState(…) method. If you now try to tombstone the application, the state will be persisted on exit, and on returning the UI will look and perform identically to how it did prior to deactivation.


Success!


Navigation and Storing State


You may notice that in the sample application we have a button that takes us to a second page of the application – CalculatorInformationPage.xaml. We should also be able to restore any application state if we navigate to this page, tombstone, return to the application, and navigate back to the calculator page.


No need to worry though, since the Chrysalis framework ensures that this occurs transparently without having to write any further code. This works by calling SaveState()/RestoreTo(..) when a user navigates away from and back to the page, and handling the persistence of the state as required.


Summary


As you will have seen, the Chrysalis framework allows Silverlight developers using the MVVM pattern to simplify the persistence of state during tombstoning on their applications. By simply overriding two methods, the ViewModel itself can specify what state to persist, and the framework handles all the plumbing required to store and retrieve this.


In my next posts I will be discussing how this all works under the covers and when you should be returning state vs when you should be using isolated storage. After that, I will be releasing and describing the next feature currently being added to Chrysalis related to choosers.


Update 17/10/2010: With the latest version RestoreState(…) should check for a null state & MainViewModel is refactored to CalculatorViewModel.

Introducing Chrysalis

In this post I am going to introduce the new Chrysalis framework available now from CodePlex at http://chrysalis.codeplex.com. Chrysalis is in an open source framework designed to simplify the development of Silverlight based Windows Phone 7 applications. Whilst it is primarily focused on Model-View-ViewModel (MVVM) related presentation patterns, it can be applied to other designs.

Many times it has been commented that if you are a Silverlight developer (and to some extent a WPF developer), then you now have the skills to write Windows Phone 7 applications. And this is almost true – with the introduction of Windows Phone 7 you can now write Silverlight applications that run on the phone as native apps (with XNA the other option for more graphically rich apps). But at the same time there are a number of new concepts that you will need to consider to write high quality software that runs within the constraints of a mobile device.

Tombstoning

The first consideration that everyone who works with Windows Phone 7 (both in Silverlight and XNA) should be aware of is the interestingly named “tombstoning”. The MSDN documentation has an excellent section on the “Execution Model Overview for Windows Phone” so I will not go into this in detail. In summary, you have to be aware that your application may be exited automatically at any point during its execution (for example when a phone call comes in) – not pushed to the background, but killed outright. At some later point you application may be reactivated, and it is you job as a developer to ensure that all application state is restored. The end user should believe that the app was sat there in the background all the time, even though you know that it was killed and restarted.

The Windows Phone 7 framework will warn you that you application is being deactivated with the PhoneApplicationService.Deactivated event. This is your opportunity to save any state required, either to one of a couple of state bags, or to isolated storage. When the application is restarted then you will receive the PhoneApplicationService.Activated event, and you can restore the UI to its former state.

In reality there is a lot to think about. Firstly you have to ensure that if you are using MVVM then your ViewModels receive the activation and deactivation events. This is complicated by the fact that the PhoneApplicationService.Activated event is often fired before your ViewModel is even created. In addition there is a lot of control state that may need to be maintained – currently focused control, position of scroll bars, etc.

Chrysalis aims to greatly simplify this process.

Choosers

In Windows Phone 7 there are a number of points at which you may need to interact with the built in phone UI, for example to take a photo with the camera, or to retrieve contact information. This is done using “Choosers” (MSDN article).

When you show a chooser we once again experience tombstoning. For the duration of the user interacting with the phone UI, our application is exited, to be restarted later when the interaction has completed. Not only do we now need to restore any state within the application, we must remember that we were calling into a chooser and what we were intending to do with the result – for example if we have multiple sets of contact information on the screen, which were we updating?

Chrysalis aims to allow you to specify a callback within your ViewModel that will receive the result from the chooser. Combined with the tombstoning support, your application should be barely aware that the application was killed and restarted. Instead the chooser will look like any other method call and callback.

Access to Hardware

Although the programming model for Windows Phone 7 is entirely managed code, there are two “flavours” of application – Silverlight and XNA. In several cases features exist within XNA, but not within Silverlight. Whilst these can be accessed by simply adding the XNA assembly references, the APIs sometimes require a different mindset.

Chrysalis aims to provide wrappers where required to make connecting to the hardware available through the XNA framework as simple as using any of the native Silverlight controls.

Summary

To conclude, the Chrysalis framework is now available at http://chrysalis.codeplex.com. While this is only a first release I encourage you to take a look at the basis provided and keep an eye on this blog as I will describe the usage and implementation of new features as they are introduced.

And please provide feedback on existing or new features, either through this blog, or on CodePlex.