As the Windows 10 OS has matured over the last year, businesses are looking to finally bring their applications over from Windows 8.1 to the new Universal Windows Platform and while the process is rather quick, there are a few gotchas that developers will need to look out for in the porting process. These have come from my own experience porting Windows 8.1 apps and things that have cropped up each time.

Getting started with the migration

Before I get into the gotchas though, you need to know how to port an application and the most in-depth tutorial for this is in the MSDN docs here, Migrate apps to the Universal Windows Platform (UWP). Before you start though, read on a little further, I’ve got some more to tell you before you get started.

You need to really read the steps carefully in the migration process, step-by-step, otherwise you’ll miss something and having to go back and retrace your steps which could end up having you in a heap of pain. I’ll repeat, read them carefully!

Before you start though, if you’ve created a Windows 8.1 universal application, now is the time to pick which project you want to run with. If you made the Windows 8.1 app truly universal, you should just need to take one of the main app projects and run with it, otherwise you may want to put some thought into either merging your code into one or just scraping one all together. Do this step before starting the migration though. Anything that is in your Shared library, move it into the main app project because you won’t need that library anymore.

So I’ve found that the easiest way to do the migration on the main app project but then lift and shift the code from any PCLs into a Windows 10 specific library unless of course, your library is shared across projects, for example, an Azure service. One thing to consider when you’re doing this however is that if you’re working with JSON, saving out the object types in your JSON file, you may need to write some JSON migration logic if you’re going to be changing project names and namespaces. I highly recommend you don’t change any project names or namespaces where possible if you’re doing this, unless you have a really strong case for doing so, as you’ll end up in another heap of pain.

The gotchas

So this post wasn’t going to be a tutorial on how you migrate your code. I’m here to tell you about things you should know about before you even start so you’re all set for the migration. Here comes the list…

Use of core Windows text styles

Once you’ve got yourself up and running after the migration, the first thing you’ll see is your app running on Windows 10. Huzzah! I can’t promise it will look pretty…

If you’ve been using the default resourced styles provided by Microsoft for your Windows 8.1 app, be prepared for some style clean up as things will have changed slightly. This is mainly around font sizes and weights. You may notice that in some areas where your app used a heading, it might be a little smaller than before or where your app used a caption, it looks a little bigger. As long as you’ve used the same resource, you should have this cleaned up in no time. For future reference though, I recommend always applying your own style on top of the default. This way, you’ll have minimal pain if any changes happen in the future to the core styles.

Overwriting generic control styles

It’s common in designing applications to take a copy of a generic Windows control style and instead of creating a new resource from it, just overriding it in your own resource dictionary. Now this is fine, but if you’re wanting that nice Windows 10 UI look and feel, you’re going to have to go back and rip those out or change what you already have. A common example is if you modified the generic style for buttons, especially the AppBarButton styling which has changed from circular to rectangular in shape.

Charms Bar Settings

If you’re taking your Windows 8.1 project and have implemented the settings flyout, you’ll need to find a new home for your app settings as they are no longer supported in Windows 10. If you’re implementing a SplitView control for your migrated app, I recommend adding a settings page which will hold all of your flyout settings. You’ll find a lot of your code will lift and shift from the control and view-model, if you’ve implemented MVVM.

Bing Maps

I’ve ported a few apps now that used the old Bing Maps control which came as an installed extension to Visual Studio for Windows 8.1 apps. It hasn’t been updated for UWP, mainly because there is a new map control which is built in for you to use which is much more friendly to work with, especially if you’ve implemented an MVVM design pattern.

Drawing controls

This may well be isolated to some of the applications I’ve ported but it’s worth a mention. If you implemented the Canvas and InkManager as a way of capturing ink in your application, you may notice a few irregularities with the rendering of the drawing. One of which is once you’ve drawn, the line you’ve drawn gets translated and scaled down to the top left corner of the canvas and will draw lines between the points you drew and the transformed line it’s rendered for you.

My suggestion here is to move to the new InkCanvas control in UWP. It has much better support for inking, especially when it comes to using a stylus like the Surface Pen.

Handling phone back navigation

If you’ve run with your Windows 8.1 app, you will have no doubt implemented navigation through on screen back buttons, most likely in the top left corner of the screen. When you’ve migrated your app, these work just fine on all platforms. However, if you go to hit that back button on your phone, it will close the app. This is due to there not being any handling in your app for it which you would have implemented specifically in your Windows Phone 8.1 app.

If you decide to go for the quick fix and bring your Windows Phone 8.1 back button handling across, remember to add a reference to the Mobile extensions for the version of Windows 10 you’re targeting.


You’ll also need to check that the specific type is present so that when your app is running on a tablet or desktop device which don’t support the phone back button, your app doesn’t crash. You’ll do that like this (if you’ve not got JavaScript enabled, click here):

I’d recommend moving towards letting the SystemNavigationManager do the work for you. Essentially, this takes advantage of the phone’s back button but also the back button that appears when your desktop or tablet device is in tablet mode, and can also provide you with a back button in the top left corner of your app window along the top bar which means you won’t have to implement one in XAML. You will however need to rip out the old one if you’re not wanting to keep it. You can achieve this functionality like this (again, click here if you don’t have JavaScript enabled):

Wrap up

So these are only a few of the things that have hit me in the past migrating apps to Windows 10 but I’m sure there are other areas that have been changed that will affect your application that you’ll come across in the migration. Once you’ve migrated though, you can start the best part which is making your app responsive and start using new Windows 10 APIs!

If you’ve got any gotchas you’d like to add from your own experiences, post them in the comments and I’ll add them to the list!

Let’s make it as painless as possible to bring your awesome Windows 8.1 apps over to the new Universal Windows Platform!

Author James Croft

James is a senior software developer for Black Marble and Microsoft MVP in Windows Development with over 6 years of experience developing applications for the Windows platform. James’s passion for learning new technologies gives him the opportunities to expose them to the wider community through tutorials, lessons learned and best practices through his online blog site, personal YouTube channel, and local communities through talks at events, schools and universities.

More posts by James Croft

Join the discussion 2 Comments

Leave a comment