Migrating a Windows Phone 7 app to a Windows Store app using XAML

Porting a Microsoft Silverlight app for Windows Phone to a Windows Store app built for Windows using C++, C#, or Visual Basic is relatively easy to do, although it does present some challenges. Most of your knowledge and experience will transfer to the model for Windows Store apps using XAML, as will much of your XAML UI design.

Your app-porting effort will have two main parts:

• Adapting your UI to take advantage of new Windows UI capabilities and design guidelines. Although you can reuse your design, you will typically rewrite most or all of your XAML code.
• Moving from the Silverlight APIs called in your code-behind files to the corresponding Windows Runtime APIs. Depending on your app, you may be able to port most of your code without change but you will typically need to rewrite 10% to 30% of it.

In many cases, your code will remain the same or nearly the same. XAML-based UI APIs in the Windows Runtime are modeled closely on the Silverlight for Windows Phone versions, although there are some differences. Additionally, the .NET APIs for Windows Store apps are available, which are a subset of the full .NET Framework and are similar to the APIs in the .NET Framework for Silverlight. In some cases, however, familiar .NET APIs have been moved to the Windows Runtime and have a somewhat different design. Furthermore, Microsoft XNA is not currently supported.

The amount of effort required to successfully port your app will largely depend on whether your app makes significant use of APIs that are not included in the Windows Runtime and the .NET APIs for Windows Store apps. This topic provides general porting guidance and resources to help you locate APIs and determine how much of your code you will have to replace.

This topic focuses on porting Windows Phone apps, but you will find additional useful info in the following topics relevant to all .NET and XAML-based projects (such as Windows Presentation Foundation (WPF) and non-phone Silverlight apps).

• Porting Silverlight or WPF XAML/code to a Windows Store app
• .NET for Windows Store apps overview

Preparing to port a Windows Phone 7 Silverlight app

Before you begin porting your Windows Phone 7 app, think about these considerations.

• Do you want to port your app rapidly or invest in greater maintainability? See the Improving maintainability section for a few techniques that you can use to single-source your project or to help reuse code and binaries between projects targeting different platforms.
• The resolution of a Windows Phone 7 device is 800x480 (WVGA) in landscape mode, and 480x800 in portrait mode. A Windows 8 device can have multiple possible portrait and landscape resolutions, in a variety of aspect ratios. How will your interface and assets scale? See Plan for different form factors for some ideas.
• A Windows Phone 7 interface is touch-specific. Your Windows 8 interface should support touch as well, but also support other input methods like mouse and keyboard. Will your interface feel cumbersome to someone who is not using touch? See Plan for accessibility for info on keeping your app useful regardless of user input method.
• Do you have phone-specific functionality in your Windows Phone 7 app? Are you aware of equivalent networking technologies in the Windows Runtime? If you have extensive support for phone or provider features, you may need to redevelop them to be more network or provider independent.
• Is your app a game that relies on XNA components for graphics rendering? If so, you must port your graphics code to Microsoft DirectX using C++. For more info, see Creating a DirectX game. You can also use DirectX in combination with XAML and with components written in managed languages. For more info, see DirectX and XAML interop and Creating Windows Runtime Components.

General porting process

If you want to port your app quickly to optimize your time to market, you can follow these steps:

1. Launch Microsoft Visual Studio Express 2012 for Windows 8 and create a new Windows Store app using C++, C#, or Visual Basic. Choose a project template that best matches your app layout and functionality. For more info, see Jumpstart your Windows Store app using templates (C#, C++, Visual Basic).
2. Copy the folders, code, and asset files that you want to reuse in the new project.
3. In the Visual Studio Solution Explorer, click Show All Files.
4. Select the files and folders that you copied, and then right-click them and select Include In Project.
5. Perform a global search and replace to replace "System.Windows" with "Windows.UI.Xaml".
6. Copy any reusable parts of your original XAML code into the new project's XAML files, or into newly created XAML files as necessary. You can sometimes copy and reuse small chunks of XAML such as styles and data templates or the contents of simple layout elements, but not the outermost elements (typically PhoneApplicationPage elements).
7. Build the project to generate errors, then use these errors to identify parts of your code to update or replace. Sometimes the updates required will be as minor as parameter type changes. Other updates will require you to use Windows Runtime APIs instead of .NET APIs for Windows Store apps. To identify which APIs are supported, use this topic for guidance in combination with .NET for Windows Store apps overview and Porting Silverlight or WPF XAML/code to a Windows Store app.
8. Comment or stub out any code that you cannot easily update until your project builds.
9. Update or replace the commented-out code one issue at a time until your port is complete.

Improving maintainability

If you want to make it easier to maintain your app on multiple platforms, consider using the following techniques:

• Before you port your code, refactor it to make it as reusable as possible. In particular, you can avoid issues with UI API differences by applying design patterns such as Model-View-ViewModel (MVVM), which separate your UI logic from your business logic. With MVVM, your model and view model code will be largely unchanged on different platforms, while your view code (your XAML) will be customized for the platform.
• Share reusable code files between projects instead of maintaining multiple copies targeting different platforms. To do this in Visual Studio, right-click the project in Solution Explorer, select Add Existing Item, select the files to share, and then click Add As Link.
• If you want to include some platform-specific code in your shared files, use conditional compilation. This works only with C#, C++, and Visual Basic code. For XAML, you must maintain separate code files.
• Create cross-platform library assemblies using the Portable Class Library. The portable class library includes the subset of .NET APIs that are available in the .NET Framework for Silverlight, the .NET APIs for Windows Store apps, and the full .NET Framework. Portable class library assemblies are binary compatible with all three platforms, and therefore represent the easiest way to reuse code. However, to create projects that target the portable class library, you must use Microsoft Visual Studio Professional 2012 or better.

Porting your user interface

Most of the layout types from Silverlight, such as Canvas, Grid, and StackPanel, are also present in the Windows Runtime XAML namespaces. Migrating a basic user interface structure should be straightforward, although you should adjust your Grid and layout settings to accommodate multiple resolutions greater than 800x480.

Of course, your phone UI is likely designed specifically for the small screen size of the phone, and simply scaling it up is not necessarily the best design. Instead, you should re-imagine your UI for the capabilities of Windows Store apps and the different form factors of Windows 8 devices. Of course, one of these capabilities is the snapped view, for which your phone UI design might be useful.

For more info and design guidelines, see the following topics:

• Making great Windows Store apps
• Plan for different form factors
• Guidelines for layouts
• Designing the user experience
• Guidelines for user interaction
• Using the design checklist

After you have made the adjustments to the XAML file that defines the layout of your app, you'll need to update the code-behind to use Windows Runtime APIs instead of Silverlight ones. For user interface elements, there is a reasonably consistent mapping between the two API libraries.

Here are the Windows Runtime XAML namespaces that are largely equivalent to their Silverlight user interface namespace peers.

Note that the following Silverlight XAML namespaces do not have a direct analog in the Windows Runtime:

• System.Windows.Ink
• System.Windows.Media.Effects
• System.Windows.Messaging

Differences between Silverlight and Windows Store apps using XAML

While the look-and-feel of the UI is common to both Windows Phone 7 and Windows 8, there are a number of differences between the UI capabilities of the two platforms. The following sections describe some key differences. However, you should consult the API reference to determine exactly which features are supported. Additional info about Windows Store apps with XAML in general can be found at Roadmap for creating Windows Store apps using C#, C++, or VB.

Controls and layout

The XAML controls in the Windows Runtime are based on the Silverlight controls, but may have different or missing functionality. For example:

• The Windows Runtime does not include the Pivot and Panorama controls available in Silverlight for Windows Phone. These controls are designed for the phone form factor, and help users navigate experiences that are larger than the phone screen. Your Windows Store apps will usually have more screen space, and should take advantage of the greater flexibility of the Grid control. You can also use the FlipView control to provide a simple paging experience.
• The AppBar control in the Windows Runtime provides a similar experience to the phone ApplicationBar, but is significantly more flexible, supporting custom layouts and data binding.
• Windows Phone apps can declare which device orientations they support, and can thereby restrict the layout flexibility required. For Windows Store apps, you should design your UI to look great regardless of device orientation and screen size. For more info, see Plan for different form factors.

For more info on controls, see Controls by function.

Tiles and notifications

Tiles for Windows Store apps have behaviors similar to Live Tiles for Windows Phone 7, although there are some differences. For more details on the use of tiles in a Windows Store app using C++, C#, or Visual Basic, read Creating tiles.

Notifications are an extension of the push notification model in Windows Phone 7. For more details on the use of notifications in a Windows Store apps, read Sending toast notifications.

For info and tutorials on using tiles, toast, and notifications in a Windows Store app using C++, C#, or Visual Basic, read Working with tiles, badges, and toast notifications.

Data scenarios

Windows Store apps do not currently include built-in support for data-intensive scenarios such as line of business (LOB) scenarios. For example, there are no APIs for client-side SQL and no local database. However, you can still retrieve data from the network by using custom services and OData calls, shape and format the data by using client-side LINQ, and bind to it by using XAML-based controls.

Data binding is mostly unchanged. For example, you can implement INotifyPropertyChanged and INotifyCollection to receive change notifications and update your UI accordingly. However, the data-related features of Windows Store apps currently have the following limitations:

• There is no built-in support for data-entry validation and the IDataErrorInfo and INotifyDataErrorInfo interfaces.
• The Binding class does not include the extended formatting properties available in Silverlight. However, you can still implement IValueConverter to provide custom formatting.
• The IValueConverter methods take language strings as parameters instead of CultureInfo objects.
• The CollectionViewSource class does not provide built-in support for sorting and filtering, and grouping works differently. For more info, see Data binding with XAML and the Data binding sample.

Navigation

Silverlight for Windows Phone apps require a page-based navigation structure in order to integrate with the platform and make use of the hardware Back button. There is a similar navigation framework available for Windows Store apps, but because of the different platform requirements, there are a few differences:

• When you navigate to a page in a Windows Store app, you do not use a URI addressing scheme. Instead, you specify the type of the target page as indicated in the x:Class attribute of the page's XAML definition. You can optionally pass a parameter object as well.
• The navigation framework for Windows Store apps does not include support for fragment navigation, journal (back stack) modification, or URI mapping.

For more info, see QuickStart: Navigating between pages.

Mapping Windows Phone 7 APIs to Windows Runtime APIs

The following table provides very rough mapping of Windows Phone 7-specific APIs to their Windows Runtime counterparts. This table does not suggest a one-to-one mapping of functionality; any platform may have more or less functionality than its counterpart.

Related topics

Porting Silverlight or WPF XAML/code to a Windows Store app

.NET for Windows Store apps overview

Windows Runtime reference

.NET for Windows Store apps

Planning apps

Designing the Windows Store app user experience

Guidelines for user interaction

Creating a DirectX game

DirectX and XAML interop

Creating Windows Runtime Components

Build date: 3/5/2013