App platform compatibility for Windows Phone 8

05/20/2016

34 minutes to read

In this article

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

In general, the Windows Phone app platform enables apps that target Windows Phone OS 7.1 to run without modification or recompilation on Windows Phone 8. However, you should test your apps on the Windows Phone 8 emulator or on a device to make sure the apps perform as expected. The performance improvements; faster, multicore hardware support; and cosmetic differences featured in Windows Phone 8 could affect the behavior and appearance of your Windows Phone OS 7.1 app on Windows Phone 8.

In addition, there are other scenarios in which a Windows Phone OS 7.1 app may behave differently when it runs on Windows Phone 8. One scenario would be a result of source incompatibility and an applied quirks mode change. The cause of the other scenario is binary incompatibility, otherwise known as a breaking change. For the most part, because of quirks mode, source incompatibility differences are transparent to developers who target a specific version of Windows Phone. However, you may see app compatibility issues due to changes in runtime behavior, changes in what is considered a breaking change, or changes that occur when you recompile your Windows Phone OS 7.1 app for Windows Phone 8, and then quirks mode no longer applies. This topic discussed quirks and breaking changes in more detail, and lists the known breaking changes and quirks in Windows Phone 8 that affect developers.

Note

In this article, references to Windows Phone OS 7.1 also pertain to Windows Phone OS 7.0.

Definition of a quirk

Windows Phone 8 introduces feature improvements or behavior changes that may cause incompatibility issues for existing apps. For some features and APIs, rather than introducing a breaking change, the Windows Phone app platform provides a quirks mode that preserves the legacy behavior and applies it where appropriate, depending on the version of the Windows Phone the app was originally built and tested for. If the target version is Windows Phone OS 7.1, quirks mode either emulates the same behavior, or it uses the same code as Windows Phone OS 7.1. In other words, the app runs in Windows Phone 8 as it did when it was tested against the runtime it originally targeted.

Note

A third-party library that is developed for Windows Phone OS 7.1 takes advantage of quirks if it is used in a Windows Phone OS 7.1 app. However, if the library is used in a Windows Phone 8 app, it runs outside of quirks mode.

If the source code for an app that targets Windows Phone OS 7.1 is recompiled to target Windows Phone 8, quirks mode is no longer in effect. Because the app now targets Windows Phone 8, it executes the new code in all cases. Quirks mode is not an opt-in or configurable feature—it is applied automatically depending on an app's target platform.

Definition of a breaking change

For a binary incompatibility or breaking change, when an app that targets Windows Phone OS 7.1 is run on Windows Phone 8, it doesn’t operate the same because of a difference in runtime behavior. These differences in behavior are not quirked, which means you will need to modify your app for it to run the same on both platforms. For example, these changes could be small differences in the app appearance or they could be differences in the order that the code executes.

Breaking changes in Windows Phone 8

The following tables list breaking changes between the Windows Phone OS 7.1 and Windows Phone 8 platforms that are not affected by quirks mode. Some of these changes may require modification to your apps so that they run the same on Windows Phone OS 7.1 and Windows Phone 8. For info about the effect of the change and how your source code should be modified, see the Impact column of the tables.

Because of many changes in Windows Phone 8, you may encounter some issues while upgrading your project. For more info about steps you need to take and issues you may encounter when upgrading your projects, see How to upgrade an app project to Windows Phone 8.

Windows Phone-specific features

When the user clicks an ad displayed in an app and clicks the back button twice in quick succession, the app exits in Windows Phone 8. In Windows Phone OS 7.1, the user would navigate through the apps back stack.

This is a change in UI behavior and a workaround is not available. However, you must ensure that your app tombstones properly in case the user exits the app unexpectedly.

Background file transfer

The limit on the number of concurrent file transfers has increased from 5 to 25.

An exception doesn’t occur until the limit of 25 is reached. You don’t need to remove requests until the higher limit is reached.

Background file transfer

In Windows Phone 8, the background transfer service will transfer on the following data networks while the app is in the foreground. In Windows Phone OS 7.0, transfers do not occur on these data networks, regardless of whether the app is running in the foreground.

2G

EDGE

Standard

GPRS

In Windows Phone 8, transfers won’t proceed on these networks while the app is not in the foreground. This limitation is shared by the HttpWebRequest object, so performing your own transfer doesn’t provide any advantages over using background transfers. On networks that are 3G and higher, background transfers will proceed on both Windows Phone 8 or Windows Phone OS 7.1, regardless of whether the app is running in the foreground, assuming all other conditions are met.

Background transfers will occur in Windows Phone 8 that did not occur in Windows Phone OS 7.1. You should account for that in your code if you plan to target both platforms.

Choosers

Previously, calling a Chooser's Show method while navigation to the Chooser was already taking place would throw an exception. Now, the second call to Show fails silently.

You don’t need to place calls to a Chooser’s Show method in a try block.

The TrueHeading and MagneticHeading properties of the CompassReading structure return values of type double. In Windows Phone OS 7.1, these double values are returned without precision; for example, as 122.0 degrees. In Windows Phone 8, the double values of these properties are returned with precision; for example, as 122.12345 degrees.

Ensure that you are not truncating the precision from these values when manipulating or converting them; for example, if you convert them to strings and then convert them back to double values.

Digital Rights Management (DRM)

In Windows Phone 8, an app cannot properly consume DRM video as a texture; the video defaults to a black display. In Windows Phone OS 7.1 and earlier versions, DRM protected video is accessible as a texture for composition. The video is composed like any other texture content in the scene. The standard video overlay controls are not affected. The compositor blends those frames correctly.

The only way to show a frame is by passing it to the compositor for drawing as an overlay surface. In each of the following cases, the video cannot be rendered via the overlay.

Non cardinal rotation (degrees other than 0, 90, 180, 270)

Partial transparency

3-D projections (object in motion that contain video)

FM Radio

Windows Phone 8 does not support the FM radio feature. If you use the FM radio API in a Windows Phone 8 app, a RadioDisabledException will occur.

If your app calls the FM radio API, detect the OS version of the phone that is running the app, and then disable this part of your app if the device is a Windows Phone 8 phone. Otherwise, an exception occurs, and if your app fails to handle the exception, the app exits unexpectedly.

Event ordering is not exactly the same between Windows Phone OS 7.1 and Windows Phone 8. Because of this, the initial LayoutUpdated event does not have the correct dimensions the first time that it is raised on Windows Phone 8. The second time it is raised, the dimensions are correct.

The ListBox control does not display in the Toolbox if you are working in a Windows Phone 8 project. The LongListSelector control is the recommended control for displaying lists of items in Windows Phone 8 apps.

Spacing, margin, and padding in the MessageBox control was updated for Windows Phone 8.

The changes in spacing, margin, and padding could affect the layout of the control in your app. Test your Windows Phone OS 7.1 apps that use the MessageBox control on Windows Phone 8 to make sure that their appearance is unchanged.

Microsoft.Phone.Media.Extended assembly

The Microsoft.Phone.Media.Extended assembly that shipped in-ROM on Windows Phone OS 7.1 phone devices is not available on a Windows Phone 8 phone.

If you were using reflection to access the API in this assembly, because they were not publicly exposed, your app may fail on a Windows Phone 8 device. Remove the calls to this assembly and use the publicly exposed media API

Networking

In Windows Phone 8, because the Windows Phone 8 client can handle the Vary header and cache responses, a Web service call may complete much faster than in previous versions.

This change should have minimal impact. However, if you are making a web service call your code must not rely on the download taking more than 1 second. You should use milliseconds and a floating point number when checking the response time, because it could be less than 1 second.

Panel controls

In Windows Phone 8, when a control that derives from Panel (such as Canvas, GridLength, or StackPanel) has a height that is greater than 2560, the Background brush is set to black, even if the background is set to a different color.

There is no workaround for this issue.

Photo chooser task

In Windows Phone 8, the photo chooser task creates a directory in the top level of the app’s isolated storage called “PlatformData”.

If an app that targets Windows Phone OS 7.1 is deployed to a phone that is running Windows Phone 8, or you create a new app that targets Windows Phone 8 and that app uses the photo chooser task, if your app iterates over the contents of isolated storage and you want to skip over directories created by the system, skip over “PlatformData” and “Shared”.

In Windows Phone OS 7.1, the code to update the progress indicator in the system tray is synchronous. In Windows Phone 8, the code to update the progress indicator is now asynchronous.

In some cases, this change can cause no progress indicator to display in the system tray in Windows Phone 8. For example, if you use the ProgressIndicator class to set the progress indicator and immediately block the UI thread (such as, by doing resource-intensive work), then the progress indicator will not be displayed. This is because the system hasn't been able to handle the request to update the progress indicator.

There is a potential workaround for this issue. If you use a timer with a small timeout and an infinite period, and then call Dispatcher..::.BeginInvoke within the timer callback to schedule the resource-intensive work, this will enable the message queue to be processed and allow the progress indicator update to take effect before starting the resource-intensive work.

Secure Sockets Layer (SSL)

When your app makes an SSL request to a web service or web site, apps that target Windows Phone 8 contact the issuer of the site's certificate for the security certificate revocation list. This additional network request in Windows Phone 8 apps increases the time required for the SSL request. If the certificate revocation list is not received in a timely manner, the SSL request may time out, especially over a slow or unreliable network connection.

Make sure that your app handles the possibility of a timeout and retries the request or continues without the requested data.

In Windows Phone 8, the Slider control and its API have changed significantly.

HorizontalLargeIncrease, HorizontalLargeDecrease, HorizontalThumb, VerticalLargeIncrease, VerticalLargeDecrease, and VerticalThumb have been removed from the control template.

The corresponding new template parts are HorizontalFill, HorizontalTrack, and HorizontalCenterElement, VerticalFill, VerticalTrack, and VerticalCenterElement. The new template parts are all of type FrameworkElement.

If you have retemplated the Slider control in an app that you are upgrading to Windows Phone 8, you may have to modify your control template to accommodate the template parts that have been removed or added.

In Windows Phone 8, events raised by the Enter key in a TextBox when the value of its AcceptsReturn property is false (that is, when the TextBox is not a multi-line TextBox) behave differently. In apps that target Windows Phone OS 7.1, the TextInput event is raised for Enter key presses that are not handled by the TextBox. In apps that target Windows Phone 8, the TextInput event is not raised for these Enter key presses.

In apps that target Windows Phone 8, handle the KeyDown event to capture Enter key presses that are not handled by TextBox.

In Windows Phone OS 7.1, if you called the Stop()()() method of the VibrateController without previously calling its Start(TimeSpan) method, all vibrations were canceled, including those started by other apps such as the phone or a toast notification. In Windows Phone 8, if you call the Stop()()() method of the VibrateController without previously calling its Start(TimeSpan) method, nothing happens. No exception is raised.

There is no workaround required for this issue.

Video play back

On Windows Phone 8, resuming video play back after locking and then unlocking the phone has changed. On Windows Phone OS 7.1, the video opens in the paused state and the image is visible. On Windows Phone 8, the video opens in the paused state but an empty black box is displayed in place of a frame from the paused video. In both cases, the user has to click Play to resume the video.

This issue is a change in the UI experience and there is no workaround.

The WebBrowser control has several changes that affect how content displays in an app. If your app uses the WebBrowser control, it may not display the same in Windows Phone 8 as it does on Windows Phone OS 7.1.

You should deploy and test your app on the Windows Phone 8 emulator and on the device. You should look for changes in appearance to the text, bullet items, and drop-down arrows in the WebBrowser, and then determine if these changes affect the usability of your app.

The WebBrowser control may behave differently when scrolling. If your app uses the WebBrowser control, it may not have the same scrolling behavior in Windows Phone 8 as it does on Windows Phone OS 7.1.

You should test scrolling in the WebBrowser and determine if any differences affect the usability of your app.

If content displayed in the WebBrowser control uses page scale viewport settings (for example, <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no"/>), the layout may be different. In Windows Phone OS 7.1, the WebBrowser control does not account for the page scale viewport settings when rendering the layout. In Windows Phone 8, the WebBrowser control does use the page scale viewport settings when rendering the layout.

If you specify page scale viewport settings, you should test your app for layout differences.

In Windows Phone 8, a blinking cursor does not always appear in text fields.

There is no workaround. The text field works as expected.

XNA

Due to changes in when the Game.IsActive property is set, a game may not resume as expected.

Test your Windows Phone app on Windows Phone 8 by running the game, locking the device while the game is running, and then unlocking the device to see if the device resumes correctly. If it doesn’t, adjust where you check the Game.IsActive property before pausing the game.

Code that relies on a particular order of object finalization may be broken. The dependency on a particular order of finalization should be removed. In addition, code in user-defined finalizers should not make calls to managed data members.

Floating-point comparisons

Because of differences in rounding behavior in Windows Phone OS 7.1 and Windows Phone 8, floating point values may differ. This is especially true when performing equality comparisons with a constant and the result of a floating point computation.

Direct comparisons with floating point computations are generally not recommended.

Support for loading multi-module assemblies

In Windows Phone OS 7.1, the common language runtime loads multi-module assemblies; in Windows Phone 8, it does not.

Multi-module assemblies are managed assemblies that are stored in multiple files. This change poses very few compatibility issues, because the multi-module assemblies are used extremely rarely. Note that multi-module assemblies are not .NET module files compiled into a single assembly.

Support for adding mixed-mode assemblies (assemblies that target the desktop version of the .NET Framework)

In Windows Phone OS 7.1, apps with mixed-mode binaries that are not loaded execute successfully; in Windows Phone 8, they do not.

To run successfully under Windows Phone 8, the mixed-mode binaries must be removed from the app.

In Windows Phone OS 7.1, apps run on a single core, and the scheduler is less aggressive in time-slicing threads in the single core. In Windows Phone 8, applications can run on multiple cores and the scheduler is more aggressive in time-slicing threads.

Race conditions and other concurrency bugs are more likely to occur in Windows Phone 8 than Windows Phone OS 7.1. To address this issue, developers must write correct multithreaded code.

Common Intermediate Language (CIL) method size

In Windows Phone 8, there is a 256-KB limit on the size of a method's CIL.

App installation that succeeded under Windows Phone OS 7.1 may fail under Windows Phone 8. This should affect an extremely small number of apps.

This behavior conforms to the CLI specification. The NullReferenceException that results from calling a method on a null reference should be handled, or instance methods should not be invoked on null objects.

Instance field reads and writes

Instance field reads are optimized by the JIT compiler.

Applications that write to and read from an instance field on separate threads may experience failure. Such fields should be marked with the C# volatile keyword.

After putting a monitor lock on an instance field, user code replaces the field with a new value. Depending on timing, when another thread tries to lock on or pulse the field, this other thread may be working on an object which it has not put a lock on.

Incorrect use of these methods can lead to deadlock, exception, or inconsistent state modification. To work around the issue, use a different object to synchronize.

Because of differences in garbage collection, code in Windows Phone OS 7.1 that did not call Dispose on the stream before releasing all its strong references will not be garbage collected and finalized in a timely manner. As a result, other streams may not be opened against that file.

Applications should use a using statement to ensure that the object is properly disposed.

System.Reflection.Emit.ILGenerator.syncObj field

In Windows Phone OS 7.1, syncObj is a protected internal field. The field is not present in Windows Phone 8.

In Windows Phone OS 7.1, if one process exits while holding a shared mutex, another process can then acquire that mutex, in Windows Phone 8, an exception is thrown.

This change should have minimal impact. To work around the change, the first process cannot abandon the mutex, or the exception that is thrown when the second process attempts to acquire the mutex can be handled.

In some cases, floating point computations with Single values can produce different results on Windows Phone OS 7.1 and Windows Phone 8. If this is the case, explicitly cast to a Double before performing the computation.

In Windows Phone OS 7.1, the value of the Referer header set by a BitmapImage request from a URI references the installation directory of the app in the format file:///Applications/Install/<GUID>/Install/.

In versions of Windows Phone released before Windows Phone 8 (8.0.10322.0), the value of the Referer header references the installation directory of the app in a different format. This occurs for apps that target both Windows Phone OS 7.1 and Windows Phone 8.

This issue has been resolved in Windows Phone 8 (8.0.10322.0).

For apps that target Windows Phone OS 7.1, the value of the Referer header is the same as in Windows Phone OS 7.1.

For apps that target Windows Phone 8, the Referer header is not sent. This behavior is consistent with the behavior of the WebClient class on Windows Phone 8.

Applications that rely on the value of the Referer header may be broken.

The XmlSerializer class has different rules regarding what input is valid in Windows Phone OS 7.1 and Windows Phone 8. Some of these differences are quirked; see Quirks mode behavior in the .NET Framework.

To use XmlSerializer with source code recompiled to target Windows Phone 8:

Special characters in assembly names, including apostrophes ('), quotation marks ("), commas (,), and equals signs (=) must be escaped. Otherwise, the assembly cannot be loaded and an exception is thrown.