Migrating WP 8.0 Apps to WP 8.1

If you’re like me and have been developing Windows Phone apps for a while (several years in my case) then you just might have more than one app in the store. In my case, I currently have eight apps published in the Windows Phone store.

At the moment, all of these target Windows Phone 8.0 (with a few of them also still targeting Windows Phone 7.1). As we get closer to the next release of Windows (Windows 10) and the unification of the Windows and Windows Phone stores, I want to start migrating my Windows Phone 8.0 apps to Windows Phone 8.1. I want to do this because I feel that it will help me toward my goal of creating universal apps so I can provide PC/tablet versions of some of my Windows Phone apps. Also, I just want to stay current with the latest version of the OS :-)

When I started the process of converting the first app to Windows Phone 8.1 I quickly ran across several issues that took a little time and research to get resolved. As any developer would, I started taking notes so future conversions would be quicker and smoother. The results of those notes are being included below as a set of steps you can follow for migrating Windows Phone 8.0 apps to Windows Phone 8.1. Although I’ve followed these steps successfully now for upgrading several apps, I sincerely doubt I’ve ran into every possible issue. So, in other words, your mileage may vary :-)

1) Pre-Work: Protect the Code!

Before you get started, I think it’s important to mention the importance of keeping your source code in some sort of version control system. As you update your apps to support Windows Phone 8.1, you will want to ensure you can get back to previous versions of your source code in case anything goes awry (or you simply want to maintain multiple versions of your app in the Windows Phone store).

If you are already using a version control system then great! If not, I recommend checking out Visual Studio Online. It is free for up to five users (users that need access to the source code) and you can choose between Team Foundation Version Control (i.e. centralized version control) or Git-based repositories (i.e. distributed version control).

2) Retarget Projects to Windows Phone 8.1

In general, re-targeting your Windows Phone 8.0 projects to Windows Phone 8.1 is fairly straight forward – For each project in your solution that needs to be updated to Windows Phone 8.1:

1. Right-click each project and select Retarget to Windows Phone 8.1 and select Yes.
2. Perform a “Clean and Rebuild” to ensure everything compiles.
3. Repeat steps 1 & 2 for each remaining Windows Phone 8.0 project in your solution.

Once all projects have been converted and everything compiles successfully, deploy the solution to a device or emulator and ensure that it runs.

At this point, your app has been officially converted to Windows Phone 8.1. However, before your app will be accepted into the Windows Phone store, there are several other steps you’ll need to take to get a few things in order.

3) Remove the Splash Screen

Unless you have a need for a splash screen (e.g. for a game that takes some time to load resources, etc.) you should simply remove the splash screen and all references to it.

1. Delete the file Assets\Splashscreen.png
2. Right-click on the Package.appxmanifest file and select View Code and delete the following line:

   <m3:splashscreen image=”Assets\Splashscreen.png”>

4) Update the Publisher

Also within the Package.appxmanifest file, you must update the Publisher attribute (within the Identity element) to match the Windows publisher name as it appears within the Windows Phone dashboard for your application. The Windows publisher name will look something like this: “CN=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX”.

To get the Windows publisher name:

1. Sign in to the Windows Phone dashboard
2. Select Apps and then select the app you’re currently migrating to Windows Phone 8.1
3. Click on the Details tab and look for Windows publisher name
4. If the Windows publisher name is currently set to “None” you need to:
1. Select the appropriate option to update your app
2. Click on App Info
3. Enter the desired name of your app and click on the Reserve app name button
4. Take note of the Windows publisher name (along with the Package identity name which will be used in the next step)

Once you have the Windows publisher name:

1. Right-click on the Package.appxmanifest file and select View Code
2. Locate the Identity element and update the Publisher attribute to match the Windows publisher name noted above

5) Update the Package Name

You will need to update the (Identity) Name within the Package.appxmanifest file. To do this:

1. Right-click on the Package.appxmanifest file and select
   View Code
2. Locate the Identity element and update the Name
   attribute to match the Package identity name noted above. This will typically be in the format of company.appName.

6) Update the Publisher Name

You must also update the PublisherDisplayName within the Package.appxmanifest file. To do this:

1. Right-click on the Package.appxmanifest file and select View Code
2. Locate the Properties element and update the PublisherDisplayName attribute to match the Publisher name as it is listed in the Account summary section of your Account settings (within the Windows Phone Dashboard). This is typically your company name.

7) Update Images

A collection of new images are added to the Assets folder in your project when you retarget to Windows Phone 8.1. The new images are named as follows:

• BadgeLogo,png
• Logo.png
• SquareTile71x71.png
• SquareTile150x150.png
• StoreLogo.png
• WideLogo.png

If you make use of the above images, you need to modify them so they are specific to your app’s needs. If you leave them as the default images, your application will not pass the certification steps when publishing. In my case, I simply deleted the first and last images as listed above then modified each of the images listed in bold to match my app.

You can read more about the app image files here.

8) Publish to the Store

Once you complete the above steps and everything is compiling, deploying, and testing OK then it’s time to publish the updated app to the Windows Phone store. This process isn’t really any different than when you’ve published the prior versions of your apps. However, the first time you submit an app for Windows Phone 8.1, you will get the following prompt:

Essentially it’s just letting you know that once you publish an 8.1 app you will need to ensure you keep an 8.1 package with future submissions.

Troubleshooting

You might encounter some error messages along the way. If you do then you’ve likely missed one of the steps listed above. A few of the more common messages are listed below, along with the resolution.

Error Message: Package could not be registered

Although your solution builds just fine, you might get this message when deploying to a device or emulator. To resolve this issue, refer to the section “Remove the Splash Screen” above and follow the steps.

Error Message: The publisher in the uploaded package does not match the expected publisher. The expected publisher for this app is: “CN=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX”

You need to update the Publisher for your package. Refer to the section ‘Update the Publisher’ above and follow the steps.

Error Message: The package identity associated with this update doesn’t match what’s in the uploaded package: “XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX”

You need to update the Name for your package. Refer to the section ‘Update the Package Name’ above and follow the steps.

Error Message: Failed Publishing to Store:

    Error Found: The branding validation test encountered the following errors:
     Image file StoreLogo.png is a default image.
     Image file Logo.png is a default image.
     Image file SquareTile71x71.png is a default image.
     Image file SquareTile150x150.png is a default image.

You need to update the newly added images in your app’s Assets folder. Refer to the section ‘Update Images’ above and follow the steps.

Summary

Although the above scenarios seem to cover the various issues I’ve ran into while upgrading from Windows Phone 8.0 to 8.1, you might run into others not listed here. If you do, please let me know in the comments below and I’ll get them added. Otherwise, I hope you find this list useful :-)