Migrating your Windows Phone 8 app to a Windows Runtime XAML app

[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]

This topic describes features of Windows Phone 8.1 that map to features you may have used in your Windows Phone 8 app. It also calls out some Windows Phone 8 features for which there is no Windows Phone Store equivalent.

Windows Phone 8 features for which there is no Windows Phone Store equivalent

There is a small set of features that were available for Windows Phone 8 apps for which there are no equivalents for Windows Phone Store apps. If your app uses one of these features you can choose to maintain your Windows Phone 8 app, which will run on both Windows Phone 8 and Windows Phone 8.1 devices. If you want to take advantage of some of the new features that are available for Windows Phone Store apps, but need to use any of these features, you can upgrade your app to Silverlight 8.1. For more info on upgrading, see Windows Phone Silverlight 8.1 apps.

Feature mapping from Windows Phone 8 to Windows Phone 8.1

The following sections will help you to discover the features of Windows Phone 8.1 that map to features you may have used in your Windows Phone 8 app.

Background processing

Windows Phone 8 apps use managed ScheduledTaskAgent objects to perform tasks while the app is not in the foreground. Windows Phone 8.1 apps use Windows Runtime Background Tasks to implement this behavior. The way that you implement these is similar. You define a class that implements your background task. When the system runs your background task, it calls the Run method of your class where you implement your app-specific code. For more info on Background Tasks, see Supporting your app with background tasks.

Transferring data in the background

Windows Phone 8 apps use the BackgroundTransferService class to transfer large files in the background. Windows Phone 8.1 apps use APIs in the Windows.Networking.BackgroundTransfer namespace to do this. The features use a similar pattern to initiate transfers, but the new API has improved capabilities and performance. For more information, see Transferrring data in the background.

Background audio

Windows Phone 8 apps used the managed classes in the Microsoft.Phone.BackgroundAudio namespace to play audio while the app is not in the foreground. Windows Phone 8.1 apps use the Windows Runtime classes in the Windows.Media.Playback namespace. This new method uses a similar Background Tasks pattern as other background processing apps. For more information, see Overview: Background audio (Windows Phone Store apps).

Files and storage

Windows Phone 8 apps have read-only access to the optional SD card. Windows Phone 8.1 apps have read-write access to the SD card. For more info, see Access the SD card in Windows Phone apps.

For info about accessing photos, music, and videos in Windows Phone 8.1 apps, see Access media libraries in Windows Phone apps.

Maps and directions

To display a map, Windows Phone 8 apps use the Map control in the Microsoft.Phone.Maps.Controls namespace. Windows Phone 8.1 apps use the new MapControl in the Windows.UI.Xaml.Controls.Maps namespace. For more info, see How to display maps in the Map control.

To get locations and addresses, Windows Phone 8 apps use GeocodeQuery and the ReverseGeocodeQuery classes in the Microsoft.Phone.Maps.Services namespace. Windows Phone 8.1 apps use the MapLocationFinder class in the Windows.Services.Maps namespace. For more info, see How to get locations and addresses with Map services.

To get routes and directions, Windows Phone 8 apps use the RouteQuery class in the Microsoft.Phone.Maps.Services namespace. Windows Phone 8.1 apps use the MapRouteFinder class in the Windows.Services.Maps namespace. For more info, see How to get locations and addresses and How to get routes and directions.

To overlay map tiles from another source on a map, Windows Phone 8 apps use the TileSource class in the Microsoft.Phone.Maps.Controls namespace. Windows Phone 8.1 apps use the MapTileSource class in the Windows.UI.Xaml.Controls.Maps namespace. For more info, see How to display tiled images on a map with tile sources.

To display a map or directions in the built-in Maps app, Windows Phone 8 apps use the MapsTask in the Microsoft.Phone.Tasks namespace. Windows Phone 8.1 apps use the bingmaps: Uri scheme. For more info, see How to display maps and directions in the built-in Maps app.

To download offline maps or to update maps that were previously downloaded, Windows Phone 8 apps use the MapDownloaderTask and the MapUpdaterTask in the Microsoft.Phone.Tasks namespace. Windows Phone 8.1 apps call the ShowDownloadedMapsUI and ShowMapsUpdateUI methods of the MapManager class in the Windows.Services.Maps namespace. For more info, see How to download and update offline maps.

Globalization and Localization

Windows Phone 8 apps use the CultureInfo class to help globalize an app. Windows Phone 8.1 apps use MRT (Modern Resource Technology), which was introduced in Windows 8 and enables the dynamic loading of app resources (localization, scale, and theme) at runtime in the Visual Studio design surface. For more information, see Guidelines for files, data, and globalization.

UI Automation

Windows Phone 8 apps use managed UI Automation classes in the .NET Framework defined in the System.Windows.Automation namespace. This is also true of Silverlight 8.1 apps. Windows Phone Store apps use UI Automation classes defined in the Windows.UI.Xaml.Automation namespace.

Controls

Windows Phone 8 apps use controls defined in the Microsoft.Phone.Controls namespace and the System.Windows.Controls namespace. This is also true of Silverlight 8.1 apps. Windows Phone Store apps use controls defined in the Windows.UI.Xaml.Controls namespace. Note that the equivalent of the Panorama control is the Hub in the new namespace. The Windows Phone Store version of the Pivot control is Pivot, and it is still Windows Phone-only. But Hub, ListView, GridView, SemanticZoom, CommandBar, and many others, are controls that you can also use in Windows Store apps.

The equivalent of LongListSelector is SemanticZoom in the new namespace. You can do grouped data with ListView and GridView, but SemanticZoom is the control that lets you switch between those two semantic views. Note, this is not optical zooming, this is zooming between the semantics of a list of items and a list of groups (of items).

Applying a tilt effect to a Button in a Windows Phone 8 app requires the Windows Phone Toolkit. In a Windows Phone Store app, you can use Windows Runtime theme animations instead, and these are already built into the default Styles of the common controls. For example, Button has a PointerDownThemeAnimation element in the Pressed state of its default template. See Animating pointer actions (Windows Runtime apps using C#/VB/C++ and XAML).

In Windows Phone 8 apps, you can’t bind the properties of the ApplicationBarIconButton. In Windows Phone Store apps, you can use bindings and static resource references with AppBarButton objects on a CommandBar. This means that you can define bindings to properties and commands of your viewmodel and bindings to localized strings declaratively in the XAML markup.

Graphics

In a Windows Phone 8 app, the type of the Clip property is Geometry. This is also true of Silverlight 8.1 apps. But in a Windows Phone Store app, the type of the Clip property is the more restrictive RectangleGeometry type. That means that the clipping area can only be rectangular. If you see XAML parse errors because you’ve used the Clip property with stream geometry, then delete the Clip attribute from your markup and add it as property element syntax similar to the following: <UIElement.Clip><RectangleGeometry Rect="10 10 50 50"/></UIElement.Clip>.

In a Windows Phone 8 app, the RadialGradientBrush type, and the OpacityMask property, are available. This is also true of Silverlight 8.1 apps. But in a Windows Phone Store app, there is no RadialGradientBrush type and no UIElement.OpacityMask property. In some cases, you may be able to get a similar visual effect using an image. But also remember that the Microsoft design principles encourage keeing your graphics clean and uncluttered by removing anything that's superfluous. Microsoft design is typified by simplified visuals, typography, and motion. If your app follows the same principles then it will seem more like a built-in app.

Monetization

Trial Windows Phone 8 apps give the user a chance to buy the fully-licensed version of the app by calling the Show()()() method. This is also true of Silverlight 8.1 apps. Trial Windows Phone Store apps call RequestAppPurchaseAsync(Boolean).

Speech

Windows Phone 8 apps using speech features need to declare the ID_CAP_SPEECH_RECOGNITION capability. This is also true of Silverlight 8.1 apps. Windows Phone Store apps using speech features need to declare the Microphone capability.

Windows Phone 8 apps use classes for Voice Commands defined in the Windows.Phone.Speech.VoiceCommands namespace. This is also true of Silverlight 8.1 apps. Windows Phone Store apps use classes for Voice Commands defined in the Windows.Media.SpeechRecognition namespace, and the VCD schema has been augmented to support hints, topics, and inline dictation.

Windows Phone 8 apps use classes for Speech Recognition defined in the Windows.Media.SpeechRecognition namespace. This is also true of Silverlight 8.1 apps. Windows Phone Store apps use classes for Speech Recognition which have been modernized and augmented and which are in the Windows.Media.SpeechRecognition namespace.

Windows Phone 8 apps use classes for Speech Synthesis (aka Text-To-Speech) defined in the Windows.Phone.Speech.Synthesis namespace. This is also true of Silverlight 8.1 apps. Windows Phone Store apps use classes for Speech Synthesis in the Windows.Media.SpeechSynthesis namespace. These are the same classes you can use in Windows Store apps.

Tiles, toasts and notifications

In Windows Phone 8, apps use the Microsoft Push Notification Service (MPNS) to send push notifications. For more info, see Push notifications for Windows Phone 8.

Windows Phone Store apps use the Windows Notification Service (WNS) to send push notifications. For more info, see Push notifications using the Windows Notification Service.

Windows Phone 8 apps create and update tiles, and send local toasts using the APIs found in Microsoft.Phone.Shell and Microsoft.Phone.Notification.

Windows Phone Store app use the APIs from the Windows.UI.Notifications, Windows.UI.StartScreen and Windows.Networking.PushNotifications namespaces.

Wallet

To interact with Wallet, Windows Phone 8 and Silverlight 8.1 apps use the APIs in the Microsoft.Phone.Wallet namespace. For more info, see Wallet for Windows Phone 8.

Windows Phone Store apps interact with Wallet using the APIs in the Windows.ApplicationModel.Wallet namespace. For more info, see Wallet for Windows Phone Store apps.

In-app navigation

The behavior of the Back button has changed. For more info, see Handling the Back Button in a Windows Phone app.

Device status

Windows Phone 8 apps use the DeviceStatus class in the Microsoft.Phone.Info namespace to get info about the device on which an app is running. There is no Windows Runtime equivalent for the Microsoft.Phone.Info namespace. Here are some properties and events that you can use in Windows Phone 8.1 apps in place of the members of the DeviceStatus class.