Tuesday, December 14, 2010

Chrysalis – Application and Session State

In my last few posts I have focused on the tombstoning features of the Chrysalis Windows Phone 7 application framework. In this post I will look at the related role of application and session state, and how these can ensure that data is persisted during tombstoning using the Chrysalis framework. As usual, all the source code is available on the Chrysalis CodePlex site under the “Source Code” tab.

Application and Session State

All examples of state I have discussed so far have been associated with a single page of a Windows Phone 7 application (view state), ensuring that any data entered is persisted during navigation and application tombstoning. In real applications much of the data crosses across multiple pages, and hence multiple views and view models. Application data is data that stores settings and information that is reused between multiple application instances. This includes user settings, user details as well as any downloaded data that rarely changes. Session data on the other hand is data that crosses multiple pages of an application, but is not reused between application instances, such as session keys for web services or some transient state.

When, and how the data is different for each of these types of state,

  • View state – Persisted on navigation to/from the page to the page state bag.
  • Application state – Persisted and restored upon application shutdown/startup and also during tombstoning using isolated storage.
  • Session state – Persisted during tombstoning to the application state bag.

Storing Application and Session State with Chrysalis

When working with data that crosses several pages (and therefore view models) we need a way to ensure that we can store and access the same data from each page. In the ‘Calculator’ sample provided with Chrysalis, this data is stored in the CalculatorSessionState object,

   1: public class CalculatorSessionState
   2: {
   3:     // *** Properties ***
   4:  
   5:     public string Operator { get; set; }
   6:  
   7:     ...
   8: }

This simply stores the current operator (+, –, / or *) that the calculator is using as a string. This is also displayed on the Calculator information page, and is true session state in that navigation back from the calculator page, and then returning will persist the value chosen.


Since we need to access the state from both the CalculatorViewModel and the CalculatorInformationViewModel, we need to be able to create a single instance of this state to share across both of these locations. Chrysalis provides a simple and straightforward way of creating such “singleton” objects by calling one of the ChrysalisService.GetService methods,



   1: public class ChrysalisService
   2: {
   3:     ...
   4:  
   5:     public T GetService<T>() { ... }
   6:     public object GetService(Type serviceType) { ... }
   7:  
   8:     ...
   9: }

This method will return a single instance of the requested type, initializing a new instance if this is the first such request (note that this will call, and requires, a public parameter-less constructor). Now we can call this method in the constructors of the CalculatorViewModel and the CalculatorInformationViewModel and be sure that we have the same instance in each case.


Supporting Tombstoning


So far I have shown how to share state between pages, but what happens when the application is tombstoned (see here if you wish to refresh yourself on what this means)? Since the process is killed, any state will be lost. On restart we have an entirely new process so Chrysalis will create a new instance with default values.


To provide a seamless user experience, we should persist any session state and restore it when the application is reactivated. Chrysalis makes this easy. All you have to do is to ensure that your state object implements the IHasSessionState interface. For example, the full code for CalculatorSessionState is,



   1: public class CalculatorSessionState : IHasSessionState
   2: {
   3:     // *** Properties ***
   4:  
   5:     public string Operator { get; set; }
   6:  
   7:     // *** IHasSessionState Methods ***
   8:  
   9:     void IHasSessionState.Initialize(object state)
  10:     {
  11:         SessionState sessionState = state as SessionState;
  12:  
  13:         if (sessionState == null)
  14:             Operator = "+";
  15:         else
  16:             Operator = sessionState.Operator;
  17:     }
  18:  
  19:     object IHasSessionState.SaveState()
  20:     {
  21:         return new SessionState()
  22:             {
  23:                 Operator = this.Operator
  24:             };
  25:     }
  26:  
  27:     // *** Sub-classes ***
  28:  
  29:     public class SessionState
  30:     {
  31:         public string Operator { get; set; }
  32:     }
  33: }

Now when the class is first initialised, Chrysalis will call the IHasSessionState.Initialize method. If the application has just been launched the ‘state’ parameter will be null and we can initialise with default values. When the application is subsequently tombstoned Chrysalis will call the IHasSessionState.SaveState method, from which we can return some state to persist until later reactivated. When this does occur a new instance of CalculatorSessionState is created, but this time our previously returned state is supplied as the parameter which we can restore.


Summary


We have now seen how Chrysalis can easily allow you to share session state between pages. By using the Chrysalis tombstoning support on the view model and the IHasSessionState interface on any shared state, we should no longer worry about what will happen if our application is tombstoned. Chrysalis will ensure that any state is restored to that before we were tombstoned, and your users will have a seamless experience.


Once again, you can download a zip file of the entire source code for Chrysalis and the associated sample application from the “Source Code” tab at the Chrysalis CodePlex site.

Sunday, November 21, 2010

Chrysalis – Tombstoning support (Part II - Implementation Details)

In my last post I introduced the tombstoning features of the Chrysalis Windows Phone 7 application framework. To summarise, this allowed developers using the Model-View-ViewModel presentation pattern to easily ensure that their ViewModels could maintain their state during tombstoning. In this post I will provide an overview of how Chrysalis implements this feature. As usual, all the source code is available on the Chrysalis CodePlex site under the “Source Code” tab.

The Chrysalis Service

One of the first steps when using the Chrysalis framework is to register the ChrysalisService in the App.xaml file’s ApplicationLifetimeObjects section (see my last post for details). This takes advantage of Silverlight’s application extension services (see MSDN) which allow you to register services that run at start-up of the application. The advantage of this approach is that once registered, the rest of the application can take advantage of the features of ChrysalisService without having to use any custom base classes of pages, View Models, etc.

The bulk of the initialization of the ChrysalisService happens within the StartService method, which Siliverlight calls during application start-up.

   1: void IApplicationService.StartService(ApplicationServiceContext context)
   2: {
   3:     // Set this as the current ServiceManager via the static property
   4:  
   5:     ChrysalisService.Current = this;
   6:  
   7:     // Attach to the PhoneApplicationService lifetime events
   8:  
   9:     PhoneApplicationService phoneApplicationService = PhoneApplicationService.Current;
  10:  
  11:     phoneApplicationService.Activated += new EventHandler<ActivatedEventArgs>(PhoneApplicationService_Activated);
  12:     phoneApplicationService.Deactivated += new EventHandler<DeactivatedEventArgs>(PhoneApplicationService_Deactivated);
  13:     phoneApplicationService.Closing += new EventHandler<ClosingEventArgs>(PhoneApplicationService_Closing);
  14:  
  15:     // Attach to the page navigation events
  16:     // NB: We set off a DispatcherTimer since we need to wait for the RootVisual property to be set before we can access this
  17:  
  18:     ExecuteViaDispatcherTimer(() =>
  19:         {
  20:             if (Application.Current.RootVisual != null)
  21:                 PhoneApplicationFrame_RootVisualLoaded((PhoneApplicationFrame)Application.Current.RootVisual);
  22:         });
  23: }


Firstly we store a static reference to our service so that we can find it at any other point within the application execution. After this we get the current PhoneApplicationService (added by default to all Silverlight Windows Phone 7 applications). Since Silverlight will initialize all application services in the order we have specified in the App.xaml file, this will already have been initialized. We then attach to the Activated, Deactivated and Closing events. Note that we do not need to attach to the Launching event since we can identify this if our service has been initialized without the Activated event.


The next step is to attach to navigation events to and from pages within the application. Normally you would do this by using the NavigationService class accessible from the current page, but since at this point of application execution no page is present (and hence the application’s RootVisual property is null) we have no way to access this. The ChrysalisService class overcomes this problem by queuing a request using a DispatcherTimer with a delay of 0ms. Although this sounds like it should execute immediately, the contract for the DispatcherTimer merely states that it should call the callback at least the specified time after starting. In fact this is queued up when the dispatcher next becomes free, conveniently after the RootVisual has been initialized.



   1: private void PhoneApplicationFrame_RootVisualLoaded(PhoneApplicationFrame frame)
   2: {
   3:     // Attach to the navigation events
   4:  
   5:     frame.Navigating += new NavigatingCancelEventHandler(NavigationService_Navigating);
   6:     frame.Navigated += new NavigatedEventHandler(NavigationService_Navigated);
   7:  
   8:     // Set the current page
   9:  
  10:     CurrentPage = frame.Content as PhoneApplicationPage;
  11:  
  12:     ...
  13: }

We can then use the RootVisual (which we know for Windows Phone 7 Silverlight applications will be a PhoneApplicationFrame) to attach to the Navigating and Navigated events. We also store a reference to the current page for future use, which is also updated on any successful navigation events.


Notifying the ViewModel of application events


Now the ChrysalisService is able to identify all the application events of interest, we need a way to pass this to the current ViewModel. This is done via the two interfaces, IPhoneLifetimeAware and IPhoneNavigationAware.



   1: public interface IPhoneLifetimeAware
   2: {
   3:     void Activated();
   4:     void Closed();
   5:     void Deactivated();
   6:     void Launched();
   7: }



   1: public interface IPhoneNavigationAware
   2: {
   3:     void NavigatingFrom(NavigatingCancelEventArgs e);
   4:     void NavigatedTo(NavigationEventArgs e);
   5: }

Since we are tracking the current page at any point of time, we can identify the ViewModel associated with it by using the DataContext of that page. If the returned object implements either of the above interfaces then we can call the relevant methods in response to application events.


Storing application page state


We have not yet addressed the main use of this feature, for storing state relevant to the ViewModel during tombstoning. This is done via a third interface that the ViewModel can implement (as is done by the provided ViewModelBase class), IHasSessionState.



   1: public interface IHasSessionState
   2: {
   3:     void Initialize(object state);
   4:     object SaveState();
   5: }

 

The SaveState() method is called by ChrysalisService whenever the application is Deactivated or when navigation occurs away from the respective page. From this method the ViewModel can return some state that will be automatically persisted during tombstoning.

Similarly, the Initialize(…) method is called by ChrysalisService whenever the application is Activated or when navigation occurs to the respective page. The ViewModel can then reinstate any state required to recreate the page prior to tombstoning.


Summary


I have now described how the Chrysalis application framework allows developers to easily manage any state relating to individual ViewModels (and therefore to individual pages of an application). In my next post I will describe how Chrysalis allows applications to store application state that may span several pages, and how this can easily be persisted between tombstoning and application restarts as is required.

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.