Wednesday, May 29, 2013

Sharing App Content using MVVM and the Okra App Framework

One of the key differentiating features of the Windows Store application model in Windows 8 is the availability of system provided “charms” for common tasks such as sharing, search and application settings. In this post I will focus on sharing, and how the Okra App Framework makes it easy to incorporate this functionality into applications using the MVVM pattern.

How to share content the Windows 8 way?

The MSDN documentation details how to share content from Windows Store apps in C#/VB. The first step is to get a reference to the application’s DataTransferManager, and then register for its DataRequested event. When the user selects the share charm this event is fired, passing a DataRequestedEventArgs object to the event handler.

There are a number of problems with this approach in the context of an MVVM application,

  • The content to share should be determined dynamically based upon the page displayed and any user selected content. In the MVVM pattern this is best accomplished by the view-model, and not by a single event handler.
  • The application specific sharing code is passed a DataRequestedEventArgs object (which is a sealed class with no public constructors). This makes unit testing this code difficult.
  • Supporting pull operations (see the MSDN documentation on this topic) requires additional event handler registration, not following the typical Task based async support used elsewhere.

Sharing content with the Okra App Framework

The Okra App Framework overcomes these problems, whilst maintaining the power of the sharing contract by allowing view-models to implement a simple, easily unit-testable, IShareable interface. The framework will handle all the other infrastructure required for application sharing. Since the IShareable interface is applied to the view-model, a ‘ViewPhoto’ page can share an individual photo, whilst a ‘ViewAlbum’ page can share the whole album (or selected photos if the user has done so).

The first step in adding sharing support to an application is to add a reference to an IShareSourceManager in the application bootstrapper.

public class AppBootstrapper : OkraBootstrapper
{
    [Import]
    public IShareSourceManager ShareSourceManager { get; set; }
}

You can then add the IShareable interface to any view-model that has suitable data to share,

[ViewModelExport("MyPage")]
public class MyViewModel : IShareable
{
    public void ShareRequested(IDataRequest dataRequest)
    {
        ...
    }
}

You will notice that the ShareRequested method is passed an IDataRequest object in which to return the data to share. This is a unit-testable wrapper around the WinRT DataRequest object and the standard MSDN documentation can be followed from this point to respond to the share request. For example to share some text you would implement this as follows,

[ViewModelExport("MyPage")]
public class MyViewModel : IShareable
{
    public void ShareRequested(IDataRequest dataRequest)
    {
        dataRequest.Data.Properties.Title = "...";
        dataRequest.Data.Properties.Description = "...";
 
        request.Data.SetText("Hello World!");
    }
}

Sharing content asynchronously (optional)

There are occasions when you may wish to only download the data once the user has completed the share request (e.g. when sharing a large file from a web service) – these are known as pull operations. The Okra App Framework provides extension methods to allow you to implement pull operations using the async features of .Net. For each SetXXX(…) method, Okra provides a corresponding SetAsyncXXX(…) method. For example, the code below demonstrates how to return text returned from some async method call. Note the signature of the GetShareTextAsync(…) method.

[ViewModelExport("MyPage")]
public class MyViewModel : IShareable
{
    public void ShareRequested(IDataRequest dataRequest)
    {
        ...
 
        request.Data.SetAsyncText(GetShareTextAsync);
    }
 
    private async Task<string> GetShareTextAsync(string formatId, DateTimeOffset deadline)
    {
        string text = await SomeAsyncMethod();
        return text;
    }
}

Sunday, May 12, 2013

Windows Store MVVM Templates for Visual Studio

If you have ever tried to create a Windows Store application using the MVVM pattern then you will probably have found that the Visual Studio project and item templates are a bit cumbersome. I often find myself adding a new page to my projects using one of the default templates, only to need to rewrite it to follow the MVVM pattern before I can even start adding application specific logic. What if there was a way to take advantage of the selection of project and page templates provided by Visual Studio, but have them produce fully MVVM compliant code?

Well today I’d like to announce the release of a free extension for Visual Studio 2012 (including the Express editions for Windows 8) that provides just that. It is based upon the open source Okra App Framework, and provides almost all of the Visual Studio Windows Store templates in an MVVM friendly manner.

Installing the Extension

The “Windows Store MVVM Templates for the Okra App Framework” extension is available for download from the Visual Studio Gallery, or available directly in the Visual Studio Extensions and Updates manager (the recommended method). Instructions for installing via Visual Studio are available at the Downloading the Okra App Framework page in the Okra App Framework documentation.

What Templates are Provided?

There are two types of template included, project templates and item templates. The project templates are designed to get you started with a new application and provide exactly the same behaviour as the default Visual Studio templates (but written following the MVVM pattern).

  • Okra Basic App - A single-page Okra App Framework project with no predefined controls or layout.
  • Okra Grid App - A three-page Okra App Framework project that navigates among grouped items arranged in a grid. Dedicated pages display group and item details.
  • Okra Split App - A two-page Okra App Framework project that navigates among grouped items. The first page allows group selection while the second displays an item list alongside details for the selected item.

Also included are a number of item templates that allow you to add new pages to any existing Okra App Framework based application, whether created using the project templates or not.

  • Basic Page (MVVM)
  • Split Page (MVVM)
  • Items Page (MVVM)
  • Item Detail Page (MVVM)
  • Grouped Items Page (MVVM)
  • Group Detail Page (MVVM)
  • Search Contract (MVVM)
  • Share Target Contract (MVVM)
  • Settings Pane (MVVM)
 

What do the MVVM Pages Look Like?

All the page templates (and each of the pages in the project templates) include the following files,

  • A XAML file containing the UI design, as well as an associated code-behind file. Since we are following the MVVM pattern this code-behind file contains very little logic.
  • A view-model that contains the properties and logic for the page.
  • In addition a file for design-time data is provided. This allows you to easily layout complex user interfaces in the designer with a visual representation of how the resulting page will look.

Summary

As I have discussed the new “Windows Store MVVM Templates for the Okra App Framework” make it quick and easy to implement pages following the MVVM pattern for use in Windows Store applications. The behaviour of all the templates has been designed to be identical to the default Visual Studio templates, with the added benefit of clean separation of code, unit testability and design-time data.