Platform compatibility and breaking changes for Windows Phone Silverlight 8.1 apps

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

This topic describes the areas in which Windows Phone Silverlight 8.1 apps behave differently than Windows Phone 8 apps, and describes changes you may need to make to your app after you upgrade it to Silverlight 8.1

General exception handling guidance

After upgrading your app to Silverlight 8.1 you still may find that your app encounters runtime errors that it didn’t before upgrading. There may be APIs that are documented as potentially throwing an exception, but because the exception never occurred during development, your code does not make the call from within a try block. When debugging your upgraded app, keep this in mind and look for unhandled exceptions as a source of new runtime errors. In some cases, you may want to write additional code to handle the exception.

Silverlight 8.1 apps are terminated when the user backs out of them

Silverlight 8.1 and Windows Phone 8 apps are terminated when the user uses the Back button to navigate backward past the first page of the app. This is different than the behavior of Windows Phone Store apps, which are paused when the user backs out of them. You can force your app to use the behavior of Windows Phone Store apps by setting PauseOnBack, which causes your app to be suspended when the user navigates backward past the first page of the app.

Silverlight 8.1 apps resume instead of replace on relaunch

On Windows Phone 8, the default behavior when the user launches an app from the Apps list or its primary tile is for a new instance of the app to be launched, replacing any existing instance of the app. Developers could override this behavior by modifying the app manifest, described in Enabling Fast Resume in the app manifest file. A Silverlight 8.1 app is always resumed when launched, instead of replacing any running instance. This behavior matches the behavior of Windows Phone Store apps. However, Silverlight 8.1 and Windows Phone 8 apps are terminated when the user uses the Back button to navigate backward past the first page of the app. After an app is terminated this way, any launch of the app will result in a new instance being created.

Continuous background execution is not supported for Silverlight 8.1 apps

Windows Phone 8 apps can continue to run in the background after the user navigates away from the app under certain conditions. This feature is not available for Silverlight 8.1 apps. If you need this feature, you should continue to use a Windows Phone 8 app. For more information, see Running location-tracking apps in the background for Windows Phone 8.

Background agents may receive less CPU time on Silverlight 8.1 unless more is requested

For a managed Windows Phone 8 ScheduledTaskAgent to be able to access Silverlight 8.1 features, it runs on the modern execution stack, which is converged with Windows. This uses a different CPU quota mechanism than Windows Phone 8. In some cases, a Silverlight 8.1 background agent might find that it gets less CPU time than it did previously. If that happens, the app may choose to call RequestAccessAsync()()(). This will increase the CPU quota given to the agent.

Silverlight 8.1 apps must use separate hosts for their VoIP, periodic, and background audio agents

In Silverlight 8.1, managed background agents (periodic, background audio, and VoIP) run on top of Windows Runtime background tasks. If you have two or more VoIP, background audio, or periodic background agents, you must specify the task to be launched in a separate host, declared in the AppX manifest.

AudioPlayerAgent and AudioStreamingAgent not supported for Silverlight 8.1 apps

The AudioPlayerAgent and AudioStreamingAgent classes, which supported background audio playback for Windows Phone 8 apps, are not supported in Silverlight 8.1. If you want to support background audio playback, you can continue to use a Windows Phone 8 app or create a Windows Phone Store app, which supports new background audio APIs.

WalletAgent not supported for Silverlight 8.1 apps

The WalletAgent, which supports Near Field Communication (NFC) in Windows Phone 8 apps, is not supported in Silverlight 8.1. If you want to support NFC you must use the new NFC APIs and implement NFC background tasks.

Silverlight 8.1 apps cannot declare in-process background tasks

You declare a background task with an Extension element in the app manifest. When doing this, you should not include the Executable attribute. The following syntax is permitted.

<Extensions>
  <Extension Category="windows.backgroundTasks" EntryPoint="AgHost.BackgroundTask">
  ...
  </Extension>
</Extensions>

OutOfProc ActivatableClasses cannot specify a DLL as the server path except for VoIP

In Windows Phone 8, you can specify a DLL as an OutOfProcessServer for ActivatableClasses. This is acceptable in the WMAppManifest.xml, but a DLL is not acceptable in the AppX manifest, and it fails schema validation. The AppX manifest requires an EXE and there's no way to specify an EXE host with a given DLL server. The app must be updated to use an EXE as the OutOfProcessServer. Apps using Windows Runtime OutOfProc activation must use a custom host and remove the run-time statements that explicitly register the Windows Runtime classes or the activation factories from within their app code.

Localized tiles unsupported with Windows Notification Service

If your Windows Phone 8 app uses resource files to provide localized text for tiles, described in How to build a localized app for Windows Phone 8, your tiles will continue to function properly when you upgrade to Silverlight 8.1 as long as you continue to use the Microsoft Push Notification Service framework for your app’s push notifications. This is the default behavior when upgrading. If you choose instead to move to the Windows Notification Service, which is used by all Windows Phone Store apps, the localized text will be inaccessible and will not be displayed on your tiles. For information about choosing the push notification service for your app, see Choosing MPNS or WNS for a Windows Phone Silverlight 8.1 app.

Silverlight 8.1 apps can’t use Managed Windows Runtime components

Silverlight 8.1 apps can’t use managed Windows Runtime components or managed Windows Runtime background tasks. Silverlight 8.1 apps can continue to use Windows Phone 8 background agents that have been upgraded with the rest of the app to Silverlight 8.1. Silverlight 8.1 apps also can use native Windows Runtime components, or they can build a managed component as a regular class library instead.

Both project types in a Silverlight 8.1 app cannot depend on the same Portable Class Libraries that use System.Net.Http.HttpClient or System.IO.Compression

When you create a Portable Class Library (PCL) and reference it from both a Silverlight 8.1 app and a Windows Runtime Component project that implements a background task for that app, you cannot use the .NET classes in the Microsoft HTTP Client Libraries or Microsoft Compression NuGet packages. If you share a dependency on these packages across both project types, or on a third-party portable library that uses these packages, errors will occur. Instead, to create a PCL that can be shared between these project types, use the Windows Runtime classes in the Windows.Web.Http.HttpClient namespace and classes in the Windows.Storage.Compression namespace in your portable library. To do this, the portable library must target Windows Phone 8.1 and Silverlight 8.1. Optionally, target Windows 8.1. For more information, see the Supported Features section of Cross-Platform Development.

Declaring a DefaultTask in the WMAppManifest.xml file is required

The DefaultTask element in the WMAppManifest.xml specifies the app page that will be displayed when the app is initially launched. In Windows Phone 8, this element is optional, but Silverlight 8.1 apps must specify a default task. For more information, see Tasks element.

Specifying supported screen resolutions in the WMAppManifest.xml file is not supported

You can include a ScreenResolution element in the app manifest for a Windows Phone 8 app to specify the screen resolutions supported by the app. The Windows Phone Store uses this information to hide the app from devices with unsupported screen resolutions. This feature is not supported for Silverlight 8.1 apps.

App bar behavior varies on different devices

On Windows Phone 8.1 devices, the size of the ApplicationBar in terms of Silverlight’s logical pixels is not constant across different screen sizes/densities.  In a app, the DefaultSize and MiniSize properties on ApplicationBar report the occluded size.  In a Windows Phone 8 app, they continue to report the same values as on a Windows Phone 8 device.

On larger screens, an opaque ApplicationBar consumes less space, leaving more for the app to display content.  The DefaultSize and MiniSize properties on ApplicationBar can be used at run time to determine how much space is occluded.

Declare the Pictures Library capability in Package.appxmanifest to access KnownFolders.CameraRoll

If your app uses Windows.Storage.KnownFolders.CameraRoll to access the pictures library on the device, you need to add the Pictures Library capability in your Silverlight 8.1 app’s Package.appxmanifest file or you will get an “access denied” error when attempting to access the property. For more info about the manifest files for Silverlight 8.1 apps, see Upgrade Windows Phone 8 apps to Windows Phone Silverlight 8.1.

Silverlight/XNA rendering interop is blocked

Silverlight and XNA rendering interop is not officially supported in Windows Phone 8, but it is not fully blocked. Some apps may have used some XNA rendering functionality. Silverlight 8.1 apps can’t use XNA rendering at all.

Use Windows.System.MemoryManager to determine your app’s memory usage

Windows Phone 8 apps use ProcessCommittedLimit or ApplicationMemoryUsageLimit to determine their current memory usage. This property always has a value of 0 when accessed from a Silverlight 8.1 app. Silverlight 8.1 app should instead use the properties of the Windows.System.MemoryManager to manage app resources. To get the current memory usage of your app, use the Windows.System.MemoryManager.AppMemoryUsage property.

Don’t call WaitForPendingFinalizers on the main Silverlight thread

An app should not call WaitForPendingFinalizers()()() on the main Silverlight thread because there is no guarantee that the method will terminate.

Changes in COM threading model

For Silverlight 8.1 apps, the foreground app runs in the Application Single-Threaded Apartment (ASTA). This is a change from Windows Phone 8 foreground apps, which use the Multithreaded Apartment (MTA) model. If your app calls CoInitializeEx from the main Silverlight thread and it returns RPC_E_CHANGED_MODE, your app will need to provide marshalling support for any types that are not meant to run on the Silverlight main thread. Alternatively, you could define their types to implement IAgileObject.

Background agents continue to use the MTA model.

Change to error code returned by CoInitializeEx

In Windows Phone 8, calls to CoInitializeEx returned E_NOTIMPL. In Windows Phone 8.1, in both Windows Phone 8 and Silverlight 8.1 apps, the error returned is RPC_E_CHANGED_MODE.

When upgrading an app with a background task that calls RunWithActivationFactories, you must handle the failure case

The background task host for Silverlight 8.1 apps calls RunWithActivationFactories(IGetActivationFactory) during the initialization sequence. This is a change from Windows Phone 8. If you upgrade your app from Windows Phone 8 to Silverlight 8.1 and your background task calls RunWithActivationFactories, CO_E_ALREADYINITIALIZED will now be returned from the call. You should update your code to handle this error. Your app should ignore the error and continue.

A VoIP foreground app will be terminated if its background agents crash or are terminated for any reason

In Windows Phone 8, if a VoIP background agent crashes or is forcibly terminated for any reason, the foreground VoIP app can continue to run. In Silverlight 8.1 apps, if a VoIP background agent crashes or is forcibly terminated for any reason, this will also terminate the foreground VoIP app. This is because VoIP apps on Silverlight 8.1 are managed at the package level, not the individual process level, and both the background and foreground parts of the app belong to the same app package.

Auto-upgraded VoIP apps must manually correct the Package.appxmanifest file

A Windows Phone 8 app with VoIP background agents when auto-upgraded to Silverlight 8.1 requires further changes to be supported.

Call MFStartup before using MediaEngine to play background sound

On the Windows Phone OS 8.0, apps that play background music by using the MediaEngine from Microsoft Media Foundation are not required to call the MFStartup function to initialize the platform before instantiating the MediaEngine. On the Windows Phone OS 8.1 and later, however, apps are required to call the MFStartup function to initialize the platform before instantiating the MediaEngine, as documented in the description for the IMFMediaEngineClassFactory::CreateInstance method. If you don't call MFStartup, the MediaEngine starts in a shutdown state and playback isn't possible. Before the app closes, remember to call the MFShutdown function one time for every previous call to MFStartup.

Silverlight 8.1 apps must support all screen resolutions

In Windows Phone 8 apps, you can specify in the app manifest file (in the ScreenResolutions element) that your app supports some but not all of the available screen resolutions. In Windows Phone Silverlight 8.1 apps, you have to support all screen resolutions.

• When you create tile assets at design time, choose a resolution that scales well across different resolutions.

• When you load image assets at run time, load assets appropriate for the current resolution, or load high-resolution assets and let the platform scale the assets to the current resolution.

The ScreenResolutions element still exists in the Xml of the WMAppManifest.xml file, but is no longer displayed in Manifest Designer, and is ignored when you publish your Silverlight 8.1 app.

Changes in Silverlight APIs

This section lists the changes in Silverlight APIs between Windows Phone 8 and Silverlight 8.1.

Changes in Common Language Runtime (CLR) behavior

This section lists several small changes in behavior that were made to the Common Language Runtime (CLR) between the release of Windows Phone 8 apps and Silverlight 8.1. If your app uses the following APIs, you may need to make some small adjustments to your app after upgrading to Silverlight 8.1.

XDocument.Load(@"assets\PhoneTest.xml");

Uri myUri = new Uri("ms-app://s-1-15-2-123456789-3297869828-1925210038-511929589-250463720-3381006342-2815560950");

new Uri("http://test.com/?MpnToken=67%3d").ToString();
// previous result: "http://test.com/?MpnToken=67%3d"
// new result: "http://test.com/?MpnToken=67="