Windows Phone starting template

UPDATE July 1, 2013: As Twitter have now closed their v1 API and I have created a Windows starting template recently that uses My Movie API, I’ve updated the Windows Phone starting template to use that API as well. There are a couple of small additional fixes, such as the contact e-mail address in the ContactCommand and the version numbers for both projects, so be sure to get check it out at Windows Phone starting template (July 2013)


A while back I wrote a blog post on adding Windows Phone 8 builds to your existing apps. To help out with starting a new project which you can deploy on Windows Phone 7 and Windows Phone 8 natively, I’ve created a Windows Phone starting template. You can get the template at the bottom of this blog post, which explains some of the details contained in that solution. Feel free to use/re-use/modify to your liking and let me know if you have feedback, suggestions for improvement or find any bugs!

Solution architecture

The solution is set up with three projects and follows a Model-View-ViewModel pattern:

  • WindowsPhoneMultiOSApp.Common
  • The common layer which holds the Models, ViewModels and other shared code. This includes Commands, Converters, some helper classes, Configuration and Localization resources and the Services that hold the data retrieval logic.

  • WindowsPhoneMultiOSApp.WP71
  • The Windows Phone 7.1 project which holds the Views, sample data, specific helpers that can’t be in the Common layer and the Windows Phone 7.1 specific assets.

  • WindowsPhoneMultiOSApp.WP8
  • The Windows Phone 8 project which mainly references the files from the WP71 project through file linking, except for the MainPage (reasoning below) and Windows Phone 8 specific assets.

Windows Phone 8 now offers a native LongListSelector control, which has a number of optimizations over the ListBox control. This means LongListSelector should be used on Windows Phone 8 where you previously might have used ListBox. Due to this difference, MainPage isn’t linked from the WP71 project, but actually has a different implementation in WP8 based on LongListSelector.

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.

Notes on implementation

Here’s a few notes on some of the specifics of the implementation:

Common\Helpers\ReviewNotification.cs

This file holds the logic in place to notify the user to review the app after the app is launched 5 times. An entry in the IsolatedStorage is used to track the startup count, which is maintained in the Application_Launching method of App.xaml.cs in the WP71 and WP8 projects:

var startupCounter = Storage.LoadPersistent<int>("StartupCounter");
startupCounter++;
Storage.SavePersistent("StartupCounter", startupCounter);

If you want to increase/decrease the amount of times the app should be launched, simply change the following line in ReviewNotification.cs accordingly:

if (startupCounter != 5) return;

Common\Helpers\Storage.cs

If you look at the little snippet up here that’s used in the App.xaml.cs to track the startup count, you probably notice the Storage helper class being used. This class can be used to save and load data in either the PhoneApplicationService.Current.State or IsolatedStorageSettings.ApplicationSettings dictionaries.

Common\Helpers\WebClientExtensions.cs

This little gem was taken from the Building Apps for Windows Phone 8 Jump Start series to enable the use of the async/await pattern in combination with the Windows Phone WebClient class:

var client = new WebClient();

try
{
    var response = await client.DownloadStringTaskAsync(new Uri(url));
    // Do something with response
}

Common\ViewModels\ViewModelLocator.cs

This is a very simple implementation of a ViewModelLocator that holds static singleton references to all the ViewModels in the app. The good thing about this is that you can use ViewModelLocator.NameOfViewModel anywhere in your code to manipulate your ViewModels (that doesn’t mean you should do it from anywhere in your code, though).

WP71\Helpers\AssemblyInformation.cs

This little helper class is used (as the name might suggest) to retrieve the assembly information from the WP71 and WP8 projects. In this particular implementation, it’s used to retrieve the App name in all of the Views, as well as additional information such as version and copyright in the AboutPage.

WP71\Helpers\SharedControls.cs

This one was referenced in the How to add Windows Phone 8 builds to your existing apps blog post to create a common namespace to use in XAML for Pivot, Panorama and LongListSelector. The namespace between the Windows Phone Toolkit and Controls library (where these controls reside for Windows Phone 7) and the Windows Phone 8 native assemblies is actually kept the same, but unfortunately in XAML we also need to specify the assembly which contain the controls. This gives us an easy way to use these controls in a shared XAML page, while still the Toolkit on Windows Phone 7 and the native controls on Windows Phone 8.

[...]
xmlns:h="clr-namespace:WindowsPhoneMultiOSApp.Helpers"
[...]
<h:Pivot Title="{Binding Title, Source={StaticResource Assembly}, Converter={StaticResource StringCaseConverter}, ConverterParameter=u}">
    <h:PivotItem Header="tweets">
[...]

WP71\SampleData\MainViewModelSampleData.xaml

This file, much like the default Windows Phone Databound App template, holds some static sample data, which is used in design time. This greatly improves the capabilities to style the content of the app in Blend, without having to run and retrieve actual data to see the results.

NuGet packages

UPDATE July 1, 2013: I’m using NuGet package restore to include the NuGet packages, so the actual ZIP to download remains relatively clean and small. Be sure to enable NuGet package manager restore in the options, which will download the missing packages upon building the solution!

Package Manager restore

  • Microsoft.Net.Http
  • The team that has created the new HttpClient class for WinRT created this package to bring the same implementation to Windows Phone. Not only does this include async/await support, but will allow for easier code sharing between Windows Phone and Windows 8.


There’s a few NuGet packages included in the Windows Phone starting template to make your life easier. Be sure to update these through NuGet, as they are regularly updated by the authors.

  • AppBarUtils
  • AppBarUtils is a nice library that lets you bind localized resources and commands to the ApplicationBar. Normally the ApplicationBar isn’t bindable as it’s not an actual Silverlight control (it’s managed by the shell), but this library uses the name property to create matches between the actual ApplicationBar’s buttons/menu items and behaviors/triggers to give you the same results as binding.

    <!-- Application Bar -->
    <phone:PhoneApplicationPage.ApplicationBar>
        <shell:ApplicationBar IsVisible="True" IsMenuEnabled="True">
            <shell:ApplicationBarIconButton IconUri="/Resources/Icons/feature.settings.png" Text="settingsId"/>
        </shell:ApplicationBar>
    </phone:PhoneApplicationPage.ApplicationBar>
    
    <!-- Application Bar Interaction -->
    <i:Interaction.Behaviors>
        <appbarutils:AppBarItemCommand Id="settingsId" Command="{Binding Settings}"/>
    </i:Interaction.Behaviors>
    <i:Interaction.Triggers>
        <appbarutils:AppBarItemTrigger Id="settingsId" Text="{Binding LocalizedResources.Settings, Source={StaticResource LocalizedStrings}}" />
    </i:Interaction.Triggers>
    
  • Microsoft.Bcl and Microsoft.Bcl.Async
  • This library was created by Microsoft to provide async/await behavior to Windows Phone 7 (among others) projects. Using this, we again increase sharing potential, as we can use async/await behavior across both Windows Phone 7 and Windows Phone 8 projects.

  • WPToolkit
  • As a Windows Phone developer, you must know this library. It holds tons of useful controls to be used in your apps, as well as animations, transitions, tilt effect and many more!

Downloads

Windows Phone starting template (July 2013) - WindowsPhoneMultiOSApp_Jul13.zip (129 downloads)

Original template for reference:
Windows Phone starting template - WindowsPhoneMultiOSApp.zip (140 downloads)

14 thoughts on “Windows Phone starting template

  1. Pingback: Windows Phone starting template

  2. You said the following: the files from the WP71 project through file linking, except for the MainPage (reasoning below)…

    But I can’t find the reasoning. But other than that, perfect!

  3. Pingback: Build Apps voor een gratis Windows Phone 8 - Matthijs Hoekstra

  4. Pingback: Zwarte balk

  5. Hello, maybe a stupid question but is this any different from creating an app for Windows Phone 7.1 ? Because that supports both apps for WP7 and WP8.

    • This template facilitates building native WP7 and WP8 versions of your app with a shared code-base. There’s a few things you gain from this, such as performance on WP8 and support for 720p resolutions.

      You’re right that a WP7.1 app should run on WP8, but then you would see a black bar on top on a 720p device and the app will run in “quirks” mode, which also impacts a couple of other things.

      For more info, check out the App platform compatibility article on MSDN (http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj206947(v=vs.105).aspx)

      • I see, so basically to do this I need to use the WP8 SDK because if I just post apps in the store as just a WP7.1 app it won’t be accepted in the “Build apps and get a Windows Phone 8 ” competition?

        That’s a bit of a problem since none of my computers is able to run Windows 8 64 bits at the moment.

  6. Pingback: Build apps and get a Windows Phone 8 - Rajen's Technical Tidbits

  7. Pingback: Windows starting template - Rajen's Technical Tidbits

  8. Could you turn this in a solution template? I have tried to rename the projects, but that doesn’t change the folder names. It would be very useful if you could just choose a solution template and fill in the desired name.

    • Hey Patrick, that’s definitely something I looked at, but proved to be quite difficult due to the dependencies (multiple projects, file linking). I might give it another shot in the future, but it’s probably a lot faster and easier to rename the projects, folder names and references manually. What I usually do is rename the folders first, open up the .sln and .csproj files and replace the names in there. Then open up the solution, do a find/replace in the solution and replace the names and then finally open up the manifest to make sure the correct namespace is in there as an app starting point.

Leave a Reply