Upgrade Windows Phone 8 apps to Windows Phone Silverlight 8.1

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

This topic contains the following sections.

 

Upgrade a published Windows Phone 8 app

You can upgrade a Windows Phone 8 app published in the Windows Phone Store by publishing an updated version with one of the following formats.

  • Windows Phone Store APPX package (version 8.1).

  • Windows Phone Silverlight 8.1 XAP package.

You cannot downgrade a published app with version 8.1 to version 8 or 7.1.

Files, tiles, and settings are preserved on upgrade

In the supported upgrade scenarios, the new version of the app replaces the existing version of the app on the user’s device. The following items are preserved when the new version of the app is installed.

  • The contents of the app’s local folder (isolated storage).

  • Pinned tiles associated with the app.

  • App settings.

Set the required values

The PhoneProductID and PhonePublisherID attributes of the mp:PhoneIdentity element in the Package.appxmanifest file are available to enable these upgrade scenarios. These attributes map to the ProductID and PublisherID attributes of the published Windows Phone 8 app.

  • Test. To test an upgrade scenario on a connected Windows Phone device, copy the ProductID and PublisherID attributes of the published Windows Phone 8 app manually into the PhoneProductID and PhonePublisherID attributes of the mp:PhoneIdentity element in the Package.appxmanifest file of the Silverlight 8.1 app.

    In this scenario, the Windows Phone 8 or 7.1 version of the app is already deployed on the device (but not installed from the Store), and you want to upgrade the installed app by deploying the Windows Phone 8.1 version of the app. You can’t upgrade an app installed from the the Store by deploying a new version of the app from your development computer.

  • Publish. When you submit the new version of your app to the Store, the product ID and publisher ID of the Windows Phone 8.1 version of the app are replaced to match the values of the app that you’re updating.

Upgrade your Windows Phone 8 app to Silverlight 8.1

To upgrade your Windows Phone 8 app

  1. Optionally, make a copy of the Windows Phone 8 version of the app.

    The upgrade process upgrades the app in place. If you want to continue to develop a version of the app that targets Windows Phone 8 only, make a copy of the app before upgrading it.

  2. Open the app.

    In Visual Studio 2013, open the existing Windows Phone 8 project that you want to upgrade.

  3. Upgrade the app.

    In Solution Explorer, select the project. Right-click and select **Retarget to Windows Phone 8.1 **.

    After you read the message in the following dialog box, click Yes to complete the upgrade.

    The following screenshots show the content of the project before and after upgrade. The upgraded project contains additional image files, and also contains both the Windows Phone 8 WMAppManifest.xml file and the Windows Phone 8.1 Package.appxmanifest file.

Before upgrade

After upgrade

  1. Optionally, select a notifications platform.

    If your app uses notifications, select which service and platform you want to use for notifications. For more information on the notification service options available to you, see Choosing MPNS or WNS for a Windows Phone Silverlight 8.1 app.

    To make your selection, choose either MPN or WNS as the notification service in your app’s Package.appxmanifest file. MPN is the default selection. Your selection affects not only push notifications, but all notifications used by your app.

    • When you continue to use the MPN platform, you have to use MPNS for push notifications. You also have to continue to use the Microsoft.Phone.Shell.ShellTile and Microsoft.Phone.Shell.ShellToast APIs for tile and toast notifications.

    • When you select the WNS platform, you have to use WNS for push notifications. You also have to use the Windows.UI.Notifications and Windows.UI.StartScreen APIs for tile and toast notifications.

    The notification platform that you select also determines where you have to register your tile assets, since tiles are associated with notifications.

    To continue to use Windows Phone 8 push notifications with MPNS, do the following things.

    • Leave ID_CAP_PUSH_NOTIFICATION selected in the Windows Phone 8 WMAppManifest.xml file.

    • Leave the info about your tiles on the Application UI page of the Windows Phone 8 WMAppManifest.xml file.

    If you update your code to use Windows Phone 8.1 APIs for push notifications with the WNS service, do the following things.

    • Clear ID_CAP_PUSH_NOTIFICATION on the Capabilities page of the Windows Phone 8 WMAppManifest.xml file. Push notifications do not require a capability in the Windows Phone 8.1 Package.appxmanifest file.

    • Register your tile assets on the Visual Assets page of the Windows Phone 8.1 Package.appxmanifest file.

  2. Select Windows Phone 8.1 capabilities.

    If you add new Windows Phone 8.1 features to your app, make sure you select the required capabilities on the Capabilities page of the Windows Phone 8.1 Package.appxmanifest file.

    Many Windows Phone 8 capabilities in the WMAppManifest.xml have a one-to-one mapping to a Windows Phone 8.1 capability in the Package.appxmanifest file. When this one-to-one mapping exists, you can select the capability in either one of the manifest files. Since you’re developing a Windows Phone 8.1 app, we recommend that you select the capability in the Windows Phone 8.1 Package.appxmanifest file.

    The following table compares the capabilities for Windows Phone 8 apps in the WMAppManifest.xml file to the capabilities for Windows Phone 8.1 apps in the Package.appxmanifest file.

Windows Phone 8 capability

WMAppManifest.xml

Windows Phone 8.1 capability

Package.appxmanifest

More info

ID_CAP_APPOINTMENTS

Appointments

ID_CAP_CONTACTS

Contacts

ID_CAP_IDENTITY_DEVICE

None

ID_CAP_IDENTITY_USER

None

ID_CAP_ISV_CAMERA

Webcam

ID_CAP_LOCATION

Location

Requires user consent.

ID_CAP_MAP

None

In Windows Phone 8.1, this capability is provided automatically to all applications.

ID_CAP_MEDIALIB_AUDIO

MusicLibrary

ID_CAP_MEDIALIB_PHOTO

PicturesLibrary

ID_CAP_MEDIALIB_PLAYBACK

None

In Windows Phone 8.1, this capability is provided automatically to all applications.

ID_CAP_MICROPHONE

Microphone

ID_CAP_NETWORKING

Internet (Client & Server)

ID_CAP_PHONEDIALER

None

ID_CAP_PROXIMITY

Proximity

ID_CAP_PUSH_NOTIFICATION

None

Windows Phone 8.1 apps that use push notifications with the WNS service don't require a capability.

ID_CAP_REMOVABLE_STORAGE

Removable Storage

ID_CAP_RINGTONE_ADD

None

ID_CAP_SCREEN_RECORDER

None

In Windows Phone 8.1, this capability is provided automatically to all applications.

ID_CAP_SENSORS

None

In Windows Phone 8.1, this capability is provided automatically to all applications.

ID_CAP_SPEECH_RECOGNITION

Microphone

ID_CAP_VOIP

None

ID_CAP_WALLET

None

In Windows Phone 8.1, this capability is provided automatically to all applications.

ID_CAP_WALLET_PAYMENTINSTRUMENTS

None

This capability cannot be used by third-party app developers.

ID_CAP_WEBBROWSERCOMPONENT

None

In Windows Phone 8.1, this capability is provided automatically to all applications.

None

VideosLibrary

None

Shared User Certificates

None

Enterprise Authentication

Before you publish an update, increment the version of the app

After you publish your Silverlight 8.1 app, you have to increment the app version manually in the Package.appxmanifest file before you publish an update for the app. The version number is not incremented automatically for Silverlight 8.1 apps. If the version number of the app update isn’t greater than the previous version, the package won’t be recognized as an update.

The version number is found in the manifest file in the Version attribute of the Identity element.