UPDATE December 2, 2013: Sander van de Velde pointed out two small bugs in the template that prevented proper usage out of the box (thanks, Sander!). These have been fixed in the updated template (found at the end of the post) and additionally a small change has been made to the RelayCommand.cs class, allowing for the usage of CommandParameters with RelayCommands.
With the imminent release of Windows 8.1 on October 18th, developers are going to have to think differently about some aspects of their apps. Whether it be things like the new Window size model or the settings charms flyouts with the new SettingsFlyout control, the implementation of Windows 8.1 apps will be different if developers want to use the native features fully.
To help speed things along, I’ve decided to update my Windows starting template to cover Windows 8.1 and Windows Phone 8 in a Visual Studio 2013 solution. Windows Phone 7 SDK support has been removed in Visual Studio, so the new template does not cover that anymore either. Like the previous template, the goal here is to provide some basic MVVM plumbing and some extra handy functionality to re-use in apps that are being built on the platform, while sharing as much code as possible between the platforms through file linking. More details on the implementation and download links below.
To remain parity with the previous template, I’ve decided to keep the solution similar with the Common projects in place:
The “master” common layer which holds the actual source files for the Models, ViewModels, Commands, Converters, some helper classes, Localization resources and the Services that hold the data retrieval logic.
The Common.Phone project mainly inherits its files from the Common.Win project through file linking, but holds some source files of its own where it makes sense (more on that further along the post)
The Windows 8.1 project which references the Common.Win project and holds the Views and app package specific assets
The Windows Phone 8 project which references the Common.Phone project and holds the Views and app package specific assets
If you’re not familiar with the Model-View-ViewModel pattern, this template offers a great way to get to know the pattern by examining an actual implementation that does not rely on frameworks such as Caliburn Micro or MVVM Light Toolkit.
The template offers the following functionality:
- Windows 8.1 BasePage, which serves as a base for all pages (more detail below)
- Localization in place with English supported for both platforms
- BaseConverter, which solves the IValueConverter differences between the platforms
- Some basic useful converters
- RelayCommand from the Windows 8.1 SDK, extended with functionality to pass a CommandParameter
- ErrorMessage helpers to quickly display error messages from code
- AppInitialization class to provide users with a “wizard” experience when the app is first opened or loads settings on subsequent loads
- ViewModelLocator to reference ViewModels in a static singleton way
- BaseViewModel with INotifyPropertyChanged implementation and a default IsDataLoaded property to bind loading UI to
- A settings page to hold some basic settings and a corresponding ViewModel that automatically stores the settings
- An about page that shows some app information, links/buttons to review the app or contact the author and a privacy statement for the app
- A sample API implementation, calling an API that I host, which returns Foursquare venues
- My StorageHelper NuGet package for easy storage access
- My ReviewNotifier NuGet package to remind users to review the app after 5 launches
Notes on implementation
The BasePage class serves as the core base for all the pages in the application. What this gives you is the implementation of the NavigationHelper, as shown in the default Windows 8.1 SDK templates, but also adds three VisualStates that are being called when the app is either wider than tall (Default), taller than wide (Portrait) or below 500px wide (Minimal). This allows for an easy implementation in the page to handle the new Window size model in Windows 8.1.
My initial implementation of the Windows Phone starting template relied on the Twitter v1 API, which got shut down. I replaced that with an implementation of My Movie API, but for this update I decided to create a small Foursquare service proxy to eliminate further dependencies on services that need to be available.
Furthermore, this time around the FoursquareService uses the HttpClient from the SDK on Windows 8.1 and the same HttpClient from the Microsoft.Net.Http NuGet package on Windows Phone to provide a common way to do web requests.
If you’ve used my previous template, you may have noticed that the Converters had a lot of #ifdef statements in them. This was due to the difference in the signatures of the Convert and ConvertBack methods of the IValueConverter interfaces on both platforms. This time around, I decided to clean things up by providing a specific BaseConverter class in both Common projects, which handle the signature difference, but expose a common API to the inheriting classes, so they can be shared without the #ifdef statements around each method.
The solution references several NuGet packages, so make sure to check for updates when you download it. The NuGet packages used are:
As usual, please share any feedback you have on the template, so I can improve it where needed. For questions, use the comments below or find me on Twitter!