Category: Notes On the Revolution

Great developers like Laurent Bugnion, Rob Eisenberg and Rocky Lhotka write Frameworks.

At the opposite end of the spectrum are developers like me.  I write helper classes.  Usually I don’t even do that and simply resort to copy and pasting from text files I have saved all over my harddrive.

In the zip file you will find a ViewModel base class designed specifically for doing MVVM in a Windows Phone Silverlight application.  It can be used with either the Satellite VM pattern or the Anchor VM pattern as described in the Patterns of Windows Phone Architecture series.  It supports Blendability, State persistence, Tombstoning and Xaml-only instantiation.

Also included are the helper classes for saving state described in this post.

Basic usage looks like this:

public class MainViewModel: 
    SerializableViewModelBase<MainViewModel>{}

All the features mentioned above come free simply by inheriting the base class.  Add a property, rinse, repeat.

And here’s the implementation below.  The code in the base constructor takes the currently newed up instance and throws it into the static instance. 

You’ll also note that unlike a typical Singleton implementation, the instance property is not static.  This allows XAML instantiation to work properly.  A protected Singleton property is provided if you want the Instance property to be static in the derived class.  To implement a static Instance property in the derived class, just add one with the new qualifier like this:

public static new MainViewModel Instance
{
    get { return Singleton; }
}

BackupMore and RestoreMore can be overridden to save additional state data that might not get serialized with the ViewModel but belongs with it nonetheless (for instance, private fields that need to be saved off).

InitializeDesigner and InitializeInstance can be overriden to perform any initialization logic.  Since with XAML instantiation using a static Instance can create your object more than once, the base class is written so these two methods are only called on the first instantiation of the singleton.  Additionally, they automatically perform forking logic for instantiation code running in the designer versus instantiation code at runtime.

Your comments and advice are, as always, welcome.

public abstract class SerializableViewModelBase<T>
    : INotifyPropertyChanged
    where T : SerializableViewModelBase<T>, new()
{

    private static T _instance;
    private static object _lockObject = new object();

    /// <summary>
    /// Initializes a new instance of 
    /// the <see cref="SerializableViewModelBase&lt;T&gt;"/> 
    /// class.
    /// </summary>
    public SerializableViewModelBase()
    {
        lock (_lockObject)
        {
            if (IsInstanceEmpty)
            {
                _instance = (T)this;
                Initialize();
            }
        }
    }

    /// <summary>
    /// Gets a value indicating whether 
    /// the singleton instance T is empty.
    /// </summary>
    /// <value>
    ///     <c>true</c> if this instance is empty;
    ///     otherwise, <c>false</c>.
    /// </value>
    protected static bool IsInstanceEmpty
    {
        get { return _instance == null; }
    }

    /// <summary>
    /// Override to perform runtime intialization.
    /// </summary>
    virtual protected void InitializeInstance() { }
    /// <summary>
    /// Override to perform initialization for 
    /// the designer.
    /// </summary>
    virtual protected void InitializeDesigner() { }

    private void Initialize()
    {
        if (DesignerProperties.IsInDesignTool)
            InitializeDesigner();
        else
            InitializeInstance();
    }

    /// <summary>
    /// Gets the singleton instance of type T.
    /// </summary>
    /// <value>The instance.</value>
    protected static T Singleton
    {
        get
        {
            lock (_lockObject)
            {
                if (IsInstanceEmpty)
                    new T();
            }
            return _instance;
        }
    }

    /// <summary>
    /// Gets the singleton instance of type T.
    /// </summary>
    /// <value>The instance.</value>
    public T Instance
    {
        get
        {
            return Singleton;
        }
    }

    private string _title;
    /// <summary>
    /// Gets or sets the Title.
    /// </summary>
    /// <value>The title.</value>
    public string Title
    {
        get { return _title; }
        set
        {
            _title = value;
            OnPropertyChanged("Title");
        }
    }

    /// <summary>
    /// Occurs when a property value changes.
    /// </summary>
    public event PropertyChangedEventHandler PropertyChanged;

    protected void OnPropertyChanged(string propertyName)
    {
        if (null != PropertyChanged)
            PropertyChanged(this
            , new PropertyChangedEventArgs(propertyName));
    }

    /// <summary>
    /// Backs up the class instance.
    /// </summary>
    /// <param name="store">The data store.</param>
    /// <returns></returns>
    public static bool Backup(IDataStorage store)
    {
        _instance.BackupMore(store);
        return store.Backup(typeof(T).Name, _instance);
    }

    /// <summary>
    /// Restores the class instance.
    /// </summary>
    /// <param name="store">The data store.</param>
    public static void Restore(IDataStorage store)
    {
        _instance = store.Restore<T>(typeof(T).Name);
        _instance.RestoreMore(store);
    }

    /// <summary>
    /// Override this method to backup additional state.
    /// </summary>
    /// <param name="store">The store.</param>
    protected virtual void BackupMore(IDataStorage store) { }

    /// <summary>
    /// Override this method to restore additional state.
    /// </summary>
    /// <param name="store">The store.</param>
    protected virtual void RestoreMore(IDataStorage store) { }
}

The Anchor ViewModel pattern described in part 2 of this series is especially well adapted to Hub style layouts where related user controls are organized under a common parent.  For instance, a Pivot Control can have a MainViewModel object assigned to its DataContext.  If the MainViewModel class has properties with additional ViewModels, for example DetailsName, DetailsAddress, and so on, each of these properties can be used as the DataContexts of the Pivot Items contained in it.

Here’s a simple illustration of what that would look like:

<controls:Pivot 
    DataContext="{Binding  
    Source={StaticResource MainVM}}" 
    Name="pivot1" Title="{Binding Title}" 
    >
    <controls:PivotItem 
        DataContext="{Binding DetailsName}"
        Header="{Binding Title}">
        <StackPanel >
            <TextBox Text="{Binding FirstName, Mode=TwoWay}"/>
            <TextBox Text="{Binding LastName, Mode=TwoWay}" />
        </StackPanel>
    </controls:PivotItem>
</controls:Pivot>

Using the tip from Tombstoning Simplified, tombstoning your application only requires a single call in order to save to transient storage not only the MainViewModel but also all of its dependent ViewModels:

private void Application_Deactivated(object sender
    , DeactivatedEventArgs e)
{
    MainViewModel.Backup(new TransientDataStorage());
}

This pattern work less well if your phone application consists of unrelated pages with unrelated view models backing them. 

In order to maintain the one line tombstoning code, you can still have a RootViewModel that consists only of properties for each ViewModel in the application.  The RootViewModel can be assigned to the DataContext of the PhoneApplicationFrame of your application, and each subsequent page in the app can simply have its DataContext bound to the properties of the RootViewModel.

Practically speaking, this is an effective architecture.  It will accomplish everything you need in your app for tombstoning. 

On an aesthetic level, however, I find it displeasing to have unrelated ViewModels dependent on one another.  Additionally, having a super ViewModel, the purpose of which is only to host other ViewModels, makes my eye twitch.

In my own applications I use a different pattern called the Satellite ViewModel pattern.  It complements the Anchor ViewModel pattern and shouldn’t be considered opposed to it.  Each pattern ought to be used where it is most appropriate to do so.

3. Satellite ViewModel

Satellites orbit the earth without any awareness of each other.  Each can be communicated with independently of its fellow crafts.  Where the Anchor ViewModel pattern privileges one object above all others, satellites are all equal with respect to one another.

In order to implement the Satellite View Model Pattern for Windows Phone applications, we will simply take advantage of one of the oldest and best-known design patterns: The Singleton.  In order to make it play well in the Phone environment, however, we will give it a little twist.

The goals of this pattern are:

1. to preserve state for a View (a PhoneApplicationPage or UserControl) even when the View is out of scope.
2. to allow fine-grained access to Views as needed
3. to support easy backup to transient or isolated storage if the application is tombstoned or simply terminated.
4. to provide an MVVM architecture that is Blendable.

A ViewModel, at minimum, should of course implement INotifyPropertyChanged.  Here is the boiler-plate implementation most people use:

public class MainViewModel : INotifyPropertyChanged
{
    public event PropertyChangedEventHandler PropertyChanged;

    protected void OnPropertyChanged(string propertyName)
    {
        if (null != PropertyChanged)
            PropertyChanged(this
                , new PropertyChangedEventArgs(propertyName));
    }
}

To allow for general access to this ViewModel while preserving state no matter what happens to associated Views, we implement the singleton pattern:

protected static MainViewModel _instance;

private static object _lockObject = new object();

public static MainViewModel Instance
{
    get
    {
        lock (_lockObject)
        {
            if (_instance == null)
                _instance = new MainViewModel();
        }
        return _instance;
    }
}

So far this is pretty standard code.  We’ve even added a standard thread-safety measure with the lock keyword.

The Singleton Pattern (as well as the related Factory Method Pattern) typically implements a private no parameter constructor in order to prevent instantiation using the new() keyword.

We can’t do this for windows phone for two reasons.

First, both Isolated Storage and transient storage to the State object use XML serialization in a partial trust environment.  Consequently, if we want to backup our ViewModels to persistent or transient storage, our ViewModels must have public no param constructors.

Second, in order to make our ViewModels blendable, we also require public no param constructors since Silverlight for Phone does not support referencing static classes in XAML.  The constraints of the Silverlight environment on the phone force us down certain architectural paths and we are obligated to tweak some old tried-and-true patterns in order to create new ones.

In order to support both blendability and serialization, our MainViewModel’s constructor will look like this:

public MainViewModel(){}

It’s awkward, I grant you. 

With respect to serialization, we are required to have a public no param constructor even if it has no code in it.  Furthermore, when the ViewModel is deserialized, the constructor is never actually called (even though we were required to have it).  If you are using a base class for your ViewModels, as many people do, you must also provide a public no param constructor for your base class  (yes! even if it is marked as an abstract base class).

In order to instantiate our ViewModel in XAML and use it as our DataContext, we will add it to our class DataContext attribute using some special syntax. The XAML for assigning a MainViewModel instance to the page’s DataContext looks like this:

d:DataContext="{d:DesignInstance local:MainViewModel,
IsDesignTimeCreatable=True}" 

Instantiating the MainViewModel instance in XAML like this makes our VM blendable.  The point of making the MainViewModel blendable is to be able to visualize how the View and the ViewModel work together.  Additionally, you may want to show data when you are designing the application which you do not want to show when you are actually running the application.  You can handle this in the Constructor method (the one we originally didn’t want to have) for your VM like so:

    public MainViewModel()
    {
        if (DesignerProperties.IsInDesignTool)
        {
            Title = "Design Mode";
        }
        else
        {
            Title = "My Application";
        }
    }

The IsInDesignTool is the magic sauce that tells us whether we are running this code through a designer or in a live application.

On the XAML side, there is an additional chunk of XAML I haven’t shown you yet.  The code presented so far will allow you to instantiate and run code in the designer only.  In order to have VM code that runs in both the designer and at runtime, however, we will set the DataContext again.  This will look like we are duplicating code, but we aren’t really. 

The purpose of this code segment is simply to set the PhoneApplicationPage’s DataContext to the Instance property for the running application as well as the design-time application (for runtime purposes, of course, it isn’t necessary to perform binding in the xaml.  It could just as well be done programmatically in the Page’s constructor):

    <phone:PhoneApplicationPage 
    ...
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d"
    d:DataContext="{d:DataInstance local:MainViewModel,
    IsDesignTimeCreatable=True}" >
    <phone:PhoneApplicationPage.DataContext>
        <Binding Path="Instance">
            <Binding.Source>
                <local:MainViewModel/>
            </Binding.Source>
        </Binding>
    </phone:PhoneApplicationPage.DataContext>
    ...

Now to put in some code for tombstoning.  For this we just require two static methods, one for serializing the VM and one for rehydrating it.  Using the helper classes from here the serialize/deserialize code on MainViewModel looks like this:

private string token = "MainViewModel";

public static bool Backup(IDataStorage store)
{
    return store.Backup(token, _instance);
}

public static void Restore(IDataStorage store)
{
    _instance = store.Restore<MainViewModel>(token);
}

In the App class, we hook into the phone services events to call Backup and Restore for all of our VMs.  The code below assumes that we have three ViewModels we want to save off.  RestorePersistentData and BackupPersistentData are simply custom methods for saving to IsolatedStorage explained in this Tip. 

They are in this sample code simply to illustrate that any data you want to save off when the application permanently terminates should also be saved off when you prepare your app for tombstoning since there is no guarantee the application will be revived after tombstoning :

private void Application_Activated(object sender
    , ActivatedEventArgs e)
{
    RestorePersistentData();

    var store = new TransientDataStorage();
    TwitterDetailsViewModel.Restore(store);
    ContactsViewModel.Restore(store);
    MainViewModel.Restore(store);
}

private void Application_Deactivated(object sender
    , DeactivatedEventArgs e)
{
    var store = new TransientDataStorage();
    MainViewModel.Backup(store);
    ContactsViewModel.Backup(store);
    TwitterDetailsViewModel.Backup(store);

    BackupPersistentData();
}

private void Application_Launching(object sender
, LaunchingEventArgs e)
{
    RestorePersistentData();
}
       
private void Application_Closing(object sender
    , ClosingEventArgs e)
{
    BackupPersistentData();
}

To summarize, the Satellite ViewModel – which is really a somewhat deviant mixing of the Singleton pattern and the ViewModel pattern to make them work on the Phone – is intended to accomplish four goals:

1. Support a stateful phone application architecture.
2. Allow easy accessibility to ViewModels.
3. Facilitate tombstoning scenarios.
4. Provide a Blendable ViewModel pattern.

If you don’t like some of the jury-rigging required to make the above code work, I would highly recommend you look at Laurent Bugnion’s ViewModel Locator pattern: http://www.galasoft.ch/mvvm/getstarted/ .  As of this writing, the MVVM Light ViewModel base class doesn’t deserialize correctly because it doesn’t have a public no param constructor.  To work around this, you simply have to copy the BaseViewModel class into your own implementation and add a constructor.

[Note: this code was cleaned up on 10/17/10 to use the DataInstance extension for design time binding to the DataContext.  Many awkward issues regarding instantiation go away by using this syntax.]

When the WP7 beta dev tools were released, developers were pleased to find several new events hanging off of Shell.PhoneApplicationService for managing a phone application’s life cycle: Launching, Closing, Activated and Deactivated.  The first two events are obviously thrown when an application is first launched and when it is closed down (either by hitting the back button past the first page in the app or, interestingly, by throwing an unhandled exception).

The Activated and Deactivated events are thrown when the application is interrupted mid-run – typically by launching a Windows Phone task or by hitting the Windows button on the phone.  This is a scenario known as tombstoning.

If you are not yet familiar with the concept of tombstoning or simply need a refresher, please read Yochay Kiriaty’s post on the subject here.

These new events give Silverlight for WP7 developers a way to manage application state outside of the navigation events on each page.  Two design considerations must be taken into account, however, in order to take advantage of this centralized way of persisting state information.  1. All data that needs to be persisted between application runs or during tombstoning must be accessible from the event handlers for the four lifecycle events.  2. If application data persistence is handled outside of each page, another mechanism is required for persisting page state information as well as model data between page instantiations.

2. Anchor ViewModel

The Pledge

An anchored boat is able to stay in one place while currents wash away unmoored items floating on the ocean.  Anything tethered to the boat, or tethered to something tethered to the boat, is likewise stationary.  This is the main concept behind an Anchor ViewModel phone architecture.

While the developer has little control over the lifespan of a PhoneApplicationPage, he can nevertheless control the life of the state of the page if he is using an M-V-VM pattern.  There are several artifacts in the application that ViewModels can be tethered to and which survive the constant newing up and dereferencing of Views in a Silverlight app for the phone.  The Application itself can serve as an anchor.  It has a RootVisual, the PhoneApplicationFrame, which hosts (typically) a MainPage.xaml PhoneApplicationPage that doesn’t go out of scope until the application is terminated.  ViewModels can be tethered to any of these objects in order to give them a lifespan beyond the lifespan of their respective Views.

The Windows Phone Databound Application Template that is provided with Visual Studio for Windows Phone demonstrates this anchoring technique.  In this sample template, the MainViewModel object hangs off of the App class.  When the MainPage view is instantiated, the App’s MainViewModel instance is assigned to the MainPage view’s DataContext. At this point, the lifecycle of MainViewModel is tethered to the lifecycle of App rather than to the lifecycle of MainPage.

The DetailsPage view, in turn, retrieves its DataContext from a ViewModel hanging off of MainViewModel which hangs off of App.  The lifecycle of the ItemViewModel is tethered to the lifecycle of MainViewModel which in turn is anchored to the App class.

The Turn

This is more evident if we change the default application based on the Windows Phone Databound Application Template a little.  First, MainViewModel can be modified to include a SelectedItem property:

private ItemViewModel _selectedItem;
public ItemViewModel SelectedItem 
{
    get { return _selectedItem; }
    set 
    { 
        _selectedItem = value;
        NotifyPropertyChanged("SelectedItem");
    }
}

Then the ListBox in MainPage.xaml should have it’s SelectedItem attribute bound to this property:

<ListBox x:Name="MainListBox" 
            SelectedItem="{Binding SelectedItem, Mode=TwoWay}" 
            ItemsSource="{Binding Items}"

We simplify the MainListBox’s SelectionChanged event handler like so:

// Handle selection changed on ListBox
private void MainListBox_SelectionChanged(object sender
    , SelectionChangedEventArgs e)
{
    // If selected index is -1 (no selection) do nothing
    if (MainListBox.SelectedIndex == -1)
        return;

    // Navigate to the new page
    NavigationService.Navigate(new Uri("/DetailsPage.xaml"
        , UriKind.Relative));
}

Finally, in our details page, we would set the DataContext in the constructor rather than in the OnNavigatedTo method:

public DetailsPage()
{
    InitializeComponent();
    if (DataContext == null)
        DataContext = App.ViewModel.SelectedItem;
}

The point to remember here is that when the DetailsPage view goes out of scope through a back page navigation, the VM for DetailsPage continues to exist in memory and remains accessible because it is tethered to MainViewModel. 

More importantly, if we change a property on the ItemViewModel we are using for the DataContext of DetailsPage, these changes would be persisted back to MainViewModel after we navigate away from DetailsPage, and would remain persisted for as long as the current App is held in memory.

The Prestige

The payoff to this pattern is that we can now handle tombstoning by persisting all of our VMs centrally in a few lines of code:

string _appToken = "all_vms";

private void Application_Activated(object sender
    , ActivatedEventArgs e)
{
    var store = PhoneApplicationService.Current.State;
    if (store.ContainsKey(_appToken))
        viewModel = store[_appToken] as MainViewModel;
}

private void Application_Deactivated(object sender
    , DeactivatedEventArgs e)
{
    var store = PhoneApplicationService.Current.State;
    if (store.ContainsKey(_appToken))
        store[_appToken] = viewModel;
    else
        store.Add(_appToken, viewModel);
}

Because all view models are anchored to MainViewModel, saving our top level view model will also automatically serialize and later deserialize all the of VMs hanging off of MainViewModel as well as the state of their properties.

We have effectively made the entire default Databound Phone Application sample “tombworthy”.   If you now tombstone the application while navigated to the DetailsPage (for instance by pressing the Windows button at bottom center), it will be restored when you return to the application.

In an application with 5, 10 or more VMs, this will be very handy.

The next post in this series will cover the Satellite ViewModels pattern, which uses many of the same principles but allows greater control over how and what state gets persisted.