RArcher.Phone.Toolkit


Original article date 21st Jan, 2014.
Updated 25th March and 25th September 2014

The Windows Phone developer community is friendly, helpful and extremely knowledgeable. In the spirit of openness and cooperation I have consistently encountered from other developers, I'd like to make available the reusable framework we use to create our Windows Phone 8 apps.

This project is now archived. For WinRT 8.1 development projects (Windows 8.1 and Windows Phone 8.1) please see the RArcher.WinRT.Toolkit project page

Quick Links


Note

Note that, for a proven, robust and reliable way of creating MVVM-based apps you should refer to well-established frameworks such as MVVM Light.

It should also be noted that RArcher.Phone.Toolkit makes use of the WPtoolkit, Portable.Ninject, Coding4Fun.Toolkit and Cimbalino.Phone.Toolkit toolkits. I particularly want to thank Pedro Lamas, author of the wonderful Cimbalino toolkit. I met Pedro in April 2013 at a Phone Dev Camp at Nokia's London HQ. He was extremely helpful and encouraging during the early stages of the design and coding of my roundup app - thanks Pedro!

What is it?

RArcher.Phone.Toolkit is an experimental lightweight toolkit for creating Windows Phone 8 apps, based on the MVVM design pattern.

The toolkit was originally designed as a set of reusable classes for use with the roundup app, with the intention being that these classes be generically reusable in future WP8 projects. After the initial release of roundup, I decided to refactor all the reusable stuff into a collection of toolkit packages which became RArcher.Phone.Toolkit.*. I then reworked roundup to use the toolkit, thus "proving" the reusable nature of the toolkit. The current version of roundup that's in the Windows Phone store uses the toolkit.

An obvious question at this point is, "Why didn't you use MVVM Light, Caliburn Micro, or a similar well-established MVVM framework?" The answer is simple: I wanted the knowledge and insights to be gained from creating my own (simple) MVVM framework.

So, is my framework/toolkit a "better" or valid alternative to MVVM Light? No, definitely not! As I noted earlier, if you want a proper MVVM-enabling toolkit for WP8 projects, you should go for MVVM Light.

However, by creating RArcher.Phone.Toolkit I did gain a better understanding of what it takes to create MVVM-based apps for Windows Phone 8. And the toolkit also provides some useful things I haven't seen elsewhere. For example, I've found maintaining app state to be an error-prone chore. The toolkit provides a base class (ModelBase) which allows View Model objects to automatically save/restore properties as and when required. All you need to do is decorate a property with the [AutoState] attribute and ModelBase takes care of all the load/save mechanics. I did a write-up on the principles of the mechanism a few months back.

namespace WPLifecycleDemo.Model
{
    public class MainPageViewModel : ModelBase
    {
        private string _myProp;
        
        [AutoState(defaultValue:"Hello World")]
        public string MyProp
        {
            get { return _myProp; }
            set { _myProp = value; OnPropertyChanged();}
        }
:
:

As I create new projects that use RArcher.Phone.Toolkit, I'll refine and improve the toolkit. I'll also create Visual Studio templates and other related assets and make them available to the community via NuGet, GitHib and this project page.

Where do I get it?

The toolkit consists of the following packages, all of which are available via NuGet:

The source for RArcher.Phone.Toolkit may be downloaded as a zip archive.

A Visual Studio 2013 project that demonstrates the use of RArcher.Phone.Toolkit may be downloaded here

How to use RArcher.Phone.Toolkit in your projects

Update: 24 March 2014:

A Visual Studio 2013 New Project template is now available for download. This provides all the required scaffolding needed to use the toolkit, and is equivalent to carrying the manual steps outlined below. Simply copy BasicMvvMApp.zip to:

C:\Users\{user}\Documents\Visual Studio 2013\Templates\ProjectTemplates\Visual C#\Windows Phone  

This will add the template for creating new RArcher.Phone.Toolkit-based projects to Visual Studio's list of C# > Windows Phone templates (you'll need to re-start Visual Studio after adding the template):

Once you've created a new project using the template, simply build and run the app.

How to add new views

When adding new views, make sure to:

  1. Create a new ViewModel class and interface. Store the files in the ViewModel folder. Use the IMainViewModel.cs and MainViewModel.cs files as examples
  2. Create the new view (using the normal Visual Studio Add | New Item command) in the View folder
  3. Update the ViewModelLocator class by adding a property that returns the new view's ViewModel class. Use the MainViewModel property as an example
  4. Add an IoC binding for the new ViewModel. See the InitializeIocBindings() method in App.xaml.cs. Use the binding for IMainViewModel as an example
  5. In the new view's xaml file, set the DataContext to be the correct ViewModel property in the ViewModelLocator class:

    <!-- Get the relevant ViewModel for this View via the ViewModelLocator -->
    <phone:phoneapplicationpage.datacontext>
        <binding source="{StaticResource ViewModelLocator}" path="MyNewViewModel" />
    </phone:phoneapplicationpage.datacontext>     
  6. In the new view's class definition:

    • Create a property named "ViewModel", which is a reference to the view's ViewModel
    • Initialize the property in the constructor:

      ViewModel = this.DataContext as IMyNewViewModel;
      
    • Override the OnNavigatedTo() method and add the following call to the ViewModel to restore state:

      ViewModel.RestoreState();
      
    • Override the OnNavigatedFrom() method and add the following call to the ViewModel to save state:

      ViewModel.SaveState();
      

How to manually add support for RArcher.Phone.Toolkit to your projects