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

Applies to Windows Phone only

Porting a Microsoft Silverlight app for Windows Phone to a Windows Store app 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 markup.
  • 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).

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.
  • Updating your Windows Phone 7 app to become a universal Windows app increases the potential audience of your app, and also creates new possibilities with shared data, purchased consumables and so on. For more info, see Building universal Windows apps for all Windows devices.

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 2013 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 2013 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:

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.

Silverlight XAML namespacesWindows Runtime XAML namespaces
System.Windows Windows.UI.Xaml
System.Windows.Automation Windows.UI.Xaml.Automation
System.Windows.Automation.Peers Windows.UI.Xaml.Automation.Peers
System.Windows.Automation.Provider Windows.UI.Xaml.Automation.Provider
System.Windows.Automation.Text Windows.UI.Xaml.Automation.Text
System.Windows.Controls Windows.UI.Xaml.Controls
System.Windows.Controls.Primitives Windows.UI.Xaml.Controls.Primitives
System.Windows.Data Windows.UI.Xaml.Data
System.Windows.Documents Windows.UI.Xaml.Documents
System.Windows.Input Windows.UI.Xaml.Input
System.Windows.Markup Windows.UI.Xaml.Markup
System.Windows.Media Windows.UI.Xaml.Media
System.Windows.Media.Animation Windows.UI.Xaml.Media.Animation
System.Windows.Media.Imaging Windows.UI.Xaml.Media.Imaging
System.Windows.Media.Media3D Windows.UI.Xaml.Media.Media3D
System.Windows.Navigation Windows.UI.Xaml.Navigation
System.Windows.Printing Windows.UI.Xaml.Printing
System.Windows.Shapes Windows.UI.Xaml.Shapes

 

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 Runtime 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 Panorama control available in Silverlight for Windows Phone. The Panorama control is designed for the phone form factor, and helps users navigate experiences that are larger than the phone screen. Instead, consider the Hub control which is also available to universal Windows apps.

    Note  The Pivot control is available if you are specifically writing a Windows Phone Store app using the Windows Runtime and XAML.

  • The AppBar or CommandBar controls in the Windows Runtime provide a similar experience to the phone ApplicationBar, but are 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. However you can make use SQLite for local transactional database services. For more info, see SQLite for Windows Phone.

Storing data in the cloud is possible using Azure, see Getting Started with Mobile Services. For solutions which require both online and offline data (that is, code running on almost all mobile devices!) see: Get started with Offline Data in Mobile Services.

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:

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.

API typeSilverlight API namespacesWindows Runtime API namespaces (C#/Visual Basic)
DevicesMicrosoft.Devices, Microsoft.Devices.Radio, Microsoft.Devices.Sensors Windows.Devices.Enumeration, Windows.Devices.Enumeration.Pnp, Windows.Devices.Input, Windows.Devices.Sensors
Windows Phone app model and environmentMicrosoft.Phone, Microsoft.Phone.Info, Microsoft.Phone.Notification, Microsoft.Phone.Reactive, Microsoft.Phone.Shell, Microsoft.Phone.Tasks Windows.Networking.PushNotifications, Windows.Devices.Sms, Windows.ApplicationModel.Background, Windows.ApplicationModel.Contacts, Windows.ApplicationModel.Contacts.Provider, Windows.ApplicationModel.Core
MapsMicrosoft.Phone.Controls.Maps, Microsoft.Phone.Controls.Maps.AutomationPeers, Microsoft.Phone.Controls.Maps.Core, Microsoft.Phone.Controls.Maps.Design, Microsoft.Phone.Controls.Maps.Overlays, Microsoft.Phone.Controls.Maps.Platform Windows.Devices.Geolocation
MarketplaceMicrosoft.Phone.Marketplace Windows.ApplicationModel.Store
Networking and syndicationMicrosoft.Phone.Net, Microsoft.Phone.Net.NetworkInformation Windows.Networking, Windows.Networking.BackgroundTransfer, Windows.Networking.Connectivity, Windows.Networking.NetworkOperators, Windows.Networking.Sockets, Windows.Web.AtomPub, Windows.Web.Syndication
Programming and data modelsSystem Windows.Foundation, Windows.Foundation.Collections, Windows.Foundation.Metadata, Windows.Data.Xml.Dom, Windows.Data.Xml.Xsl, Windows.Data.Json
LocationSystem.Device.Location Windows.Devices.Geolocation, Windows.Networking.Proximity
Automation and diagnosticsSystem.Diagnostics, System.Windows.Automation.Peers Windows.Foundation.Diagnostics
Graphics (3D transforms)XNA Framework Class Library, Content Pipeline Class Library No equivalent at this time. Use DirectX in C++ for graphics rendering.
Controls and UI infrastructureMicrosoft.Phone.Controls, Microsoft.Phone.Controls.Primitives Windows.UI.ApplicationSettings, Windows.UI.Core, Windows.UI.Input, Windows.UI.Notifications, Windows.UI.ViewManagement
StorageSystem.IO.IsolatedStorage class Windows.Storage, Windows.Storage.FileProperties

 

Related topics

Migrating 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

 

 

Show:
© 2014 Microsoft