Windows Dev Center

Upgrade Windows Phone 8 apps to Windows Phone Silverlight 8.1

In Visual Studio 2013 with Update 2 or later, you can quickly and easily upgrade your existing Windows Phone 8 app to Windows Phone Silverlight 8.1. By upgrading your app, you can use many of the new features in the Windows Phone 8.1 development platform without completely rewriting your app. For more info about these new features, see Supported features for Windows Phone Silverlight 8.1 apps.

Important noteImportant Note:

You must have Windows Phone SDK 8.0 installed before you can open or upgrade Windows Phone 8 apps in Visual Studio 2013. Windows Phone SDK 8.0 is an optional component of Visual Studio 2013. If you didn’t select Windows Phone SDK 8.0 when you installed Visual Studio 2013, you can run Setup again to add it to your existing installation.

This topic contains the following sections.

 

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.

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 .

    Menu option to upgrade Windows Phone 8 project

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

    Prompt when upgrading Windows Phone 8 project

    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

    Windows Phone 8 project before upgrade

    Windows Phone 8 project after upgrade
  4. 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.

  5. 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

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.

Show:
© 2015 Microsoft