WP7 and WP8 co-development and porting guide

Introduction

This document describes how to successfully develop applications targeting both Windows Phone 7 and Windows Phone 8 platforms with minimal maintenance effort and without compromising quality or features. Instead of one-way porting, it is worthwhile to support both platforms, since the cost of this is low compared to the benefits of wider device base. We refer to this approach as co-development.

The Windows Phone 8 platform, along with the new devices, offers a great number of new features and enhancements that provide the means to develop stunning applications. Whether you are adding Windows Phone 8 support to your existing application or developing a new one, do not pass the exciting new possibilities provided by the Windows Phone 8 and new Lumia devices. So instead of going by "the least common denominator" approach, do utilise the new feature set and push the boundaries of your application without losing the compatibility to Windows Phone 7.

In short, co-development means sharing the same code base for both platforms and having platform specific parts of implementation that are cross-platform compatible. The amount of code that can be shared varies, depending on the application type and technologies used, but fortunately with common abstraction techniques and proper amount of time spent in the design of the project architecture you can increase the size of the shared code base.

The techniques covered in this documentation apply regardless of whether you are about to port your existing Windows Phone 7 application to Windows Phone 8 or creating a new Windows Phone 8 application that also supports the existing Windows Phone 7 device base.

Note: See this article for app submission tips for Windows Phone 7 and Windows Phone 8.

Platform comparison

  Windows Phone 7 Windows Phone 8
Screen size 800 x 480 (Nokia Lumia 510, 610, 710, 800, 900) 800 x 480 (Nokia Lumia 820)
1280 x 720
1280 x 768 (Nokia Lumia 920)
Development frameworks, technologies and programming languages Silverlight Silverlight
XNA XNA*
C# C#
HTML5 HTML5**
  DirectX
  C++
  Visual Basic

* XNA on Windows Phone 8 is deprecated in terms that it will not be future proof. For instance, you can no longer create new XNA based applications for Windows Phone 8, but Windows Phone 7 XNA applications are fully supported and continue to run on Windows Phone 8.

** The HTML5 support has been significantly improved for Windows Phone 8, and this is something you should consider when creating new applications for Windows Phone 8 and planning to back-port them to Windows Phone 7.

Also note that XAML used in Silverlight does not mix with C++. However, you can mix C# and C++, which is especially great in case you need to port your C++ application logic from another platform. Furthermore, DirectX is the framework with which you would most benefit from using C++. However, since DirectX is not supported on Windows Phone 7, it is not covered in this documentation.

The new APIs

Nokia Lumia devices running on Windows Phone 8 introduce a great set of new APIs. The most notable of these are:

  • Nokia Maps
  • Proximity API (NFC, Bluetooth, WiFi)
  • Lenses (extend the viewfinder experience with unique camera functionality)
  • Advanced capture APIs (control the advanced camera properties like ISO, white balance, and exposure)
  • Nokia MixRadio API (launch tasks in Nokia MixRadio from you application)

With Nokia Maps the map experience in Windows Phone devices has been greatly improved, and developers get to use the very same features that are provided with the Nokia Maps application. APIs for Bing Maps are still supported, so all the Windows Phone 7 applications using them will also work on Windows Phone 8 devices. Note that Bing Maps API, like XNA, is deprecated and thus not future proof. Learn more of the Nokia Maps from the article Guide to the Maps.

With the Proximity API you can create apps that send data between devices using NFC, interact with NFC tags, and establish a Wi-Fi, Bluetooth, or Wi-Fi Direct connection between your app and an instance of your app on a near-by device. Learn more of the Proximity API usage from the article Using NFC to establish a persistent connection.

There is also a separate article on the advanced capture APIs, Advanced Photo Capturing, describing the usage of these APIs with an extensive example application.

With Nokia MixRadio API you can build applications that help users to find music and provide detailed information about the music they are interested in. To learn more about Nokia MixRadio API, see the article Nokia MixRadio API.

Supporting multiple resolutions

Windows Phone 8 supports phones that have WVGA, WXGA, and 720p resolutions, while Windows Phone 7 only supports WVGA. The following table describes the resolutions and aspect ratios that are supported in Windows Phone 7 and Windows Phone 8:

  Resolution Aspect ratio Scale Scaled resolution
WVGA 480 x 800 15:9 1x scale 480 x 800
WXGA 768 x 1280 15:9 1.6x scale 480 x 800
720p 720 x 1280 16:9 1.5x scale, 80 pixels taller 480 x 853

As graphic assets of an application may take a lot of space, it is recommended to use only graphic assets optimised for WXGA resolution. They have the highest quality and automatically scale down to other resolutions. Because of the ratio difference between 720p and other resolutions, there might be some cases when a customised image for 720p resolution is wanted, for example for a page background. An example of how to dynamically select the best resolution for a specific graphic asset is given in section "Runtime adaptation" of this topic.

For splash screen, a single WXGA 768 x 1280 SplashScreenImage.jpg image is recommended. It is automatically scaled to the phone resolution. If pixel-perfect splash screens for all resolutions are wanted, you should additionally have the following three files in the root folder of the application:

  • SplashScreenImage.Screen-WVGA.jpg
  • SplashScreenImage.Screen-WXGA.jpg
  • SplashScreenImage.Screen-720p.jpg

For Tile and App icons it is similarly recommended to use only WXGA image, as it is automatically scaled down to WVGA and 720p screens. Creating a separate image for every applicable tile size enables tailoring the contents of the tile (graphics, captions, details) to make the most of the available space. The following table summarises the correct size of the tile images for the different tile templates supported in Windows Phone 8:

WXGA resolution tile size Flip and Cycle templates Iconic template Flip tile example
Small 159 x 159 pixels 110 x 110 pixels
Medium 336 x 336 pixels 202 x 202 pixels
Wide 691 x 336 pixels N/A

Techniques overview

There are several techniques that help you to develop and maintain your cross-platform application. See the following table for techniques and suitable application types. These techniques can be combined, and in many cases you will end up using more than just one. Do note that the Windows Phone 7 apps will work out-of-the-box on Windows Phone 8, and sometimes it is not necessary to do anything, especially if the app does not require any additional features. It is strongly recommended, however, to at the very least compile the application for Windows Phone 8 target to achieve the best performance.

Technique Suitable app type
Two top-level projects All
Using linked source code files Silverlight applications and applications which contain platform specific resources such as images
Runtime adaptation All
Compile-time adaptation Applications with C# code
Portable class libraries Applications with portable business logic, MVVM based applications

The following sections describe each of these co-development techniques in more detail.

Two top-level projects

This technique is the preferred approach in developing applications targeting both Windows Phone OS 7.1 and Windows Phone 8. With this approach you can use all the other techniques to isolate version-specific sections and share code to minimise duplication, ensure consistency, and make maintenance easier. The technique can be applied to a new application targeting both Windows Phone 7 and Windows Phone 8 platforms as well as to upgrading an already existing Windows Phone 7 application to take advantage of the new Windows Phone 8 features. The basic idea is to have a single Visual Studio solution with two top-level projects targeting different platforms, as shown in the minimal example screenshot below. Both projects have their own copies of source files that may use platform specific features and images independently.

For new applications targeting both Windows Phone 7 and Windows Phone 8 platforms, just create a new project – <project>_WP75 – targeting Windows Phone OS 7.1, and then add a new project – <project>_WP8 – targeting Windows Phone 8 for the same solution and start developing the application for both platforms in parallel.

For an already existing Windows Phone 7 application, you should first make a backup copy of the existing project and then follow the steps below to start developing with two top-level projects.

Prepare the files and folders using File Explorer:

  1. Rename the Windows Phone 7 project folder from <project> to <project>_WP7.
  2. Rename the .csproj file in WP7 project folder: from <project>.csproj to <project>_WP7.csproj.
  3. Make a copy of the renamed project folder and rename it to <project>_WP8.
  4. Rename the .csproj file in this copied folder to <project>_WP8.csproj.

Create a solution with platform specific projects for Windows Phone 7 and Windows Phone 8:

  1. Open your Windows Phone 7 solution in Microsoft Visual Studio Express 2012 for Windows Phone.
  2. Remove the original Windows Phone 7 project (which cannot be found, as the project folder name and .csproj file name have been changed).
  3. Add Windows Phone 7 project to the solution.
  4. Add Windows Phone 8 project to the solution.
  5. Right-click on the Windows Phone 8 project and select "Upgrade to Windows Phone 8.0".

Using linked source code files

With this technique you can share code and resource files between several projects. Continuing with the same minimal example, let's assume that we have noticed that instead of having the source code duplicated in two projects, we can share the same code between the projects. First we delete the duplicated files (MainPage.xaml & MainPage.xaml.cs) from the Windows Phone 8 project by right-clicking the MainPage.xaml file and selecting delete.

You can add shared files as links in two ways:

  • Select the file you want to link. Hold down the Alt key and drag the file to the target project. Notice the icon indicating that the file is linked.

  • Or, right-click on the target project and select Add > Existing Item. In the Add Existing Item dialog, select the file and click the arrow next to the Add button, then select "Add As Link".
           

You can later choose to replace the linked files with Windows Phone 8 specific files whenever the need arises. Just remove the linked file from the Windows Phone 8 project and add a new Windows Phone 8 specific file – for example, an image with greater resolution or xaml file with Windows Phone 8 specific features.

Runtime adaptation

Having multiple resolutions to support, relative sizes and layouts should be used to render the application pages correctly in all phone models. Instead of hard-coding the size and position of controls in the page, place the controls in a grid and use * or Auto to size and position the controls on the pages. The following code example and screenshots demonstrate how to adapt to multiple resolutions in Silverlight.

<phone:PhoneApplicationPage
    ...
     
     <!--LayoutRoot is the root grid where all page content is placed-->
     <Grid x:Name="LayoutRoot" Background="Transparent">
     
     ...
     
    <!--ContentPanel - place additional content here-->
         <Grid x:Name="ContentPanel" Grid.Row="1" Margin="12,0,12,0">
             <Grid.RowDefinitions>
                 <RowDefinition Height="Auto"/>
                 <RowDefinition Height="*"/>
                 <RowDefinition Height="Auto"/>
             </Grid.RowDefinitions>
             <Grid.ColumnDefinitions>
                 <ColumnDefinition Width="*"/>
                 <ColumnDefinition Width="*"/>
                 <ColumnDefinition Width="*"/>
                 <ColumnDefinition Width="*"/>
             </Grid.ColumnDefinitions>
      
             <TextBox x:Name="MySearchTermBox" Grid.Row="0" Grid.ColumnSpan="3"/>
             <Button Grid.Row="0" Grid.Column="3" Content="Find"/>
             <maps:Map x:Name="MyMap" Grid.Row="1" Grid.ColumnSpan="4" CenterChanged="MyMap_CenterChanged"/>
             <TextBlock Text="+" Foreground="Red" FontSize="50"
                         Grid.Row="1" Grid.ColumnSpan="4" HorizontalAlignment="Center" VerticalAlignment="Center"/>
             <TextBlock x:Name="MyLatitude" Grid.Row="2" Grid.Column="0" Grid.ColumnSpan="2" Text="Latitude:"/>
             <TextBlock x:Name="MyLongitude" Grid.Row="2" Grid.Column="2" Grid.ColumnSpan="2" Text="Longitude:"/>
         </Grid>

    </Grid>

</phone:PhoneApplicationPage>
WVGA WXGA 720p

The following code example demonstrates how to dynamically load images depending on the screen resolution. The example relies on the fact that all the images have been named as <image_name>_<resolution_type>.png.

public Uri GetScaledImageUri(String imageName) 
{
    int scaleFactor = (int)Application.Current.Host.Content.ScaleFactor;
    switch (scaleFactor)
    {
        case 100: return new Uri(imageName + "_wvga.png", UriKind.RelativeOrAbsolute);
        case 150: return new Uri(imageName + "_720p.png", UriKind.RelativeOrAbsolute);
        case 160: return new Uri(imageName + "_wxga.png", UriKind.RelativeOrAbsolute);
        default:  throw new InvalidOperationException("Unknown resolution type");
    }
}

...

// Next line will load a correct image depending on the resolution of the device
MyImage.Source = new BitmapImage(GetScaledImageUri("myImage"));

The following methods can help you to find out the current screen resolution of the device in runtime:

public bool IsWvga
{
    get
    {
        return Application.Current.Host.Content.ScaleFactor == 100;
    }
}

public bool IsWxga
{ 
    get
    {
        return Application.Current.Host.Content.ScaleFactor == 160;
    }
}

public bool Is720p 
{
    get
    {
        return Application.Current.Host.Content.ScaleFactor == 150; 
    }
}

The following code block demonstrates how to get runtime information on the platform the code is running on:

public bool IsRunningOnWP8
{
    get
    {
        return Environment.OSVersion.Version.Major >= 8;
    }
}

Compile-time adaptation

You can use conditional compilation symbols to isolate platform specific code in your application. This comes handy when you have separate projects for Windows Phone 7 and Windows Phone 8 applications. First you need to define a conditional compilation symbol which you then use in C# code to isolate platform specific code.

Defining conditional compilation symbol:

  • Right click on the Windows Phone 8 project and select Properties.
  • Open up the Build page of Project Designer and insert WP8 into Conditional compilation symbols. After this, they should contain something like this: SILVERLIGHT;WINDOWS_PHONE;WP8

Isolating version specific sections of code:

  • Isolate Windows Phone 8 specific code using conditional compilation symbols.
// Separate implementations for different OS versions
#if WP8
    // code using enhancements introduced in Windows Phone 8 
#else
    // code using Windows Phone OS 7.1 features 
#endif


// A new Windows Phone 8 feature
#if WP8
    // code using new Windows Phone 8 feature
#endif 

Portable class libraries

Portable class libraries are a form of code sharing where you compile the cross-platform parts of your application into a library that you then reference from the platform specific code; e.g., user interface (UI) layer. This approach is especially useful for applications with generalised business logic that can be easily ported. Despite the isolation of the shared code, interaction with the platform specific implementation can be achieved using abstractions. For instance, you can create an abstract interface for the platform specific business logic, include that in your library, and implement the interface in the platform specific layer.

Learn more at http://msdn.miscrosoft.com/en-us/library/gg597391.aspx.

Case study

For a complete hands-on tutorial on how to upgrade an application to Windows Phone 8 to make use of the platform's new features without losing compatibility with Windows Phone 7, see:


Last updated 19 November 2013

Back to top

Was this page helpful?

Your feedback about this content is important. Let us know what you think.

 

Thank you!

We appreciate your feedback.

×