Migrate your Windows Phone 8.0 DirectX Project to Windows Phone 8.1
For Windows Phone 8.1 development, Visual Studio 2013 Update 2 doesn’t provide automated migration of projects that use the C++ Direct3D App template for Windows Phone 8.0. This document helps you through the process of migrating these kinds of projects manually.
There are three main steps to migrating your project manually.
1. Modify your original .vcxproj file.
2. Modify your original .sln file.
3. Migrate from Xap (Windows Phone Store) packaging to AppX (Windows Store) packaging
Replace WMAppmanifest.xml with Package.appxmanifest.
Satisfy AppX manifest requirements.
After you complete these steps, you can use Visual Studio 2013 to build and deploy your project as a Windows Phone 8.1 app.
Let’s get started.
Important: If you have a Windows Store version of your app that supports Windows 8.1, another possibility for migrating the app to Windows Phone 8.1 is to start with the Windows Store version and then use the Add Windows Phone 8.1 command on your project's shortcut menu in Visual Studio 2013 Update 2 to create a "universal app".
This approach automatically gives you a code base that your Windows Store and Windows Phone versions can share, but you have to do some work to tune it for Windows Phone. In particular, you have to modify your user interface and you might have to make Phone-specific optimizations to the code or resources. If you also have a version of your app that supports Windows Phone 8.0 and already contains the modified code and resources, you can integrate them into the Phone project in your universal-app solution.
This document describes another approach and doesn't cover this one in more detail. Prerequisites To get the most value from this guidance, you need:
A version of Visual Studio 2013 that supports Windows Phone 8.1 development.
The Windows Phone 8.1 Platform SDK.
An existing Windows Phone 8.0 Direct3D app.
The guidance in this document was developed by migrating the MarbleMaze sample for Windows Phone 8.0 to Windows Phone 8.1. Because the guidance is general, it may not completely map to your app’s unique configuration. If migrating your project proves difficult, you might download the MarbleMaze sample for Windows Phone 8.0 and follow this guide to migrate it before you try yours again. Before you begin The easiest way to get the files you need for the migration is to create a project in Visual Studio 2013 that you can copy the files from. Create the project that you will copy files from In Visual Studio 2013, create a DirectX App (Windows Phone) project. This project template is located under Visual C++, Store Apps, Windows Phone Apps. Use the default project name.
Now you can copy the files you need into your own project. Before you do that, it’s a good idea to make a backup of your original project if you don’t already have one. This way, if something goes wrong, you won’t leave your project in an unusable state. Copy files from the new project to your own project In File Explorer, navigate to the directory of the project you just created and copy the following files into the directory of the project that you want to migrate. The exact location where you want to paste these files depends on the directory structure of your project; for the Marble Maze sample for Windows Phone 8.0, the location is the same as the MarbleMaze project file.
1. Package.appxmanifest
2. Assets\
1. Logo.scale-240.png
2. SmallLogo.scale-240.png
3. SplashScreen.scale-240.png
4. Square71x71Logo.scale-240.png
5. StoreLogo.scale-240.png
6. WideLogo.scale-240.png Note: You may not need the Assets directory and its contents for the app you are migrating, but these files can be useful if your project does not already contain suitable icons. It’s probably best to copy but not overwrite if there is a filename collision. You can delete the files later if you don’t need them.
After you copy the files into your original project, you can delete the donor project.
Modify your project file Visual Studio project (.vcxproj) files for Windows Phone 8.0 apps are different than those for Windows Phone 8.1. Most of the differences are related to the change from Xap packages to AppX packages, but a few other differences are related to changes in the Windows Phone SDK. You also have to specify the new platform toolset so that your project will be built for Windows Phone 8.1.
Your Visual Studio solution might contain more than one project. Repeat the following steps for each project.
Note: The example project used in this document is MarbleMaze for Windows Phone 8.0, which was created in Visual Studio 2012. Some changes to the project file are specific to moving from Visual Studio 2012 to Visual Studio 2013. If you used Visual Studio 2013 to create the Windows Phone 8.0 app you want to migrate to Windows Phone 8.1, those steps don't apply.
Modify the project file 1. Open the project (.vcxproj) file for editing with the text-editor of your choice.
2. In the file, locate the root element
3. Under the root
a. Delete the
b. In the
c. Delete these elements:
e. Create an
f. Create an
4. Under
In each such
5. Under
In each such
6. Under
Set the inner-text of its
Remove ole32.lib from the semicolon-delimited list in the inner-text of its
7. Under the root
8. Under
a. Delete the
b. In the
In the
9. Under
10. Under
11. Save the project (.vcxproj) file. Modify your solution file Only minor changes are necessary for the solution file. Modify the solution file 1. Open the solution (.sln) file for editing with the text-editor of your choice.
2. Locate the line that begins with # Visual Studio… and replace it with # Visual Studio 2013. (On the same line, you can include a note that this file was modified manually.)
3. Immediately following the line you just modified, add these lines:
VisualStudioVersion = 12.0.30314.2.0
MinimumVisualStudioVersion = 10.0.40219.1
4. Save the solution (.sln) file.
Now you are ready to load the solution in Visual Studio.
Load your solution file and add new files Now that you’ve made the necessary changes to your solution and project files, you can load the solution in Visual Studio 2013. If any of the projects in the solution fail to load, it’s likely for one or more of these reasons:
The changes to the project file are incomplete or incorrect.
There's a mismatch between the opening and closing tags of added or deleted elements.
An element name, property name, or value is misspelled. The opening and closing tags of an element must be spelled the same; otherwise, the XML parser reads them as different—and therefore mismatched—element tags.
If everything loads successfully, the next step is to add the files that you copied from the donor project to the solution.
In Solution Explorer, open the shortcut menu for your Windows Phone 8.1 project and choose Add, Existing Item. Add these files to the solution:
Package.appxmanifest
Assets\
3. Logo.scale-240.png
4. SmallLogo.scale-240.png
5. SplashScreen.scale-240.png
6. Square71x71Logo.scale-240.png 7. StoreLogo.scale-240.png
8. WideLogo.scale-240.png
Compile and link your app for Windows Phone 8.1 At this point, you can build your app even though it's not yet ready to be packed or deployed. You don't have to build now, but it's a good time to make sure that your project and the projects it depends on will compile and link successfully. Some minor differences in the platform libraries might affect your project, and changes to your project files might cause the build to break. We recommend that you resolve any build issues now, before you start to migrate to the new packaging format.
Note: The important thing to confirm now is that the projects compile and link successfully. You can ignore errors about packaging, which is addressed in the next section.
This document doesn't address build errors that might occur for reasons that are particular to your project—for example, it might use APIs or libraries that have been renamed or replaced in the Windows Phone 8.1 SDK.
Migrate from Xap packaging to AppX packaging The content and configuration of your project’s manifest is unique to your project. When you configure your project’s AppX manifest, you can compare it against the Xap manifest from the Windows Phone 8.0 version of your project. (Because Visual Studio supports Windows Phone 8.0 and Windows Phone 8.1 development side-by-side, you can open your Windows Phone 8.0 solution in another instance of Visual Studio.)
The name of the executable payload is an important part of a configuration. It's set when a project is created, but it's not exposed in the manifest designer and must be changed in the Package.appxmanifest file itself. For this migration, you're using the .appxmanifest file from the donor project you created, and so you have to change its payload name to the name of your project. Change the name of the executable payload in your manifest 1. Open the .appxmanifest file for editing with the text-editor of your choice.
2. Under the root element
3. In the
Change the Executable property to $targetnametoken$.exe. Change the EntryPoint property to the entry point of your app; by default, this is ProjectName.App.
4. Save the .appxmanifest file and close it.
To change other parts of your .appxmanifest—for example, your app's title, description, splash-screen, and tiles—open it in Visual Studio.
Note: If you have a version of your app for the Windows Store—that is, for Windows 8.1 or Windows RT 8.1—its .appxmanifest file might specify resources that could be used in your Windows Phone 8.1 manifest. It’s likely that many of the settings and referenced resources can be shared among the manifests for Windows 8.1, Windows RT 8.1, and Windows Phone 8.1.
At a minimum, your manifest has to specify resources for the app's splash screen and at least one icon, which you should make the default, before you can deploy your app. These settings are located on the Visual Assets tab in the manifest designer.
For more information about manifests, see App package manifest on the Windows Dev Center website.
Deploy and run your app The final test of a successful migration is whether you can package, deploy and run your app, either on the Windows Phone emulator that's included in Visual Studio, or on a real device. To deploy and debug your app, select the configuration you want to deploy and specify where you want to deploy the app, and then choose Start Debugging.
If your app doesn't deploy, the Output window might provide information that helps you diagnose the problem.
Additional notes from migrating MarbleMaze We encountered the following issues when we migrated the MarbleMaze sample for Windows Phone 8.0 to Windows Phone 8.1. These issues are specific to the MarbleMaze sample. Although your project might not share these issues, they might suggest ways that you can work around issues you encounter in your migration. However, even if you encounter the same issues, these solutions might not be best for your project.
The MarbleMaze sample for Windows Phone 8.0 is configured to create and consume information for the Windows runtime (.winmd files). This is unnecessary and was removed during the migration. However, the project could no longer be linked to the DirectXTK library by using "Add Reference" in Solution Explorer. To build MarbleMaze after this change, we had to configure the project dependencies by adding DirectXTK.lib to the list of linker targets, and adding its location to the list of additional library locations for each project configuration. The MarbleMaze sample for Windows Phone 8.0 includes a then-current version of DirectXTK as one of the projects in its solution. DirectXTK was updated to the latest version during migration. DirectXTK builds different configurations for each supported platform by using different project files for each one. As part of the migration, we added a DirectXTK project for Windows Phone 8.1 by using the same techniques described in this document. Because packaging is not an issue for static libraries, the process is significantly simpler than for the MarbleMaze app. An updated version of DXTK that supports Windows Phone 8.1 will be available at https://directxtk.codeplex.com.
In the current version of DirectXTK—and since the MarbleMaze sample for Windows Phone 8.0 was created—some APIs have been moved to different namespaces. We had to more fully qualify some API calls in the MarbleMaze source code because the compiler couldn't resolve them otherwise.
The MarbleMaze source code used the platform API, Windows::Phone::System::Memory::MemoryManager::ProcessCommittedBytes, but in Windows Phone 8.1 it is replaced by Windows::System::MemoryManager::AppMemoryUsage. We changed the source code accordingly.
The MarbleMaze source code used certain Media Framework APIs that were found in MFMediaEngine.lib in the Windows Phone 8.0 SDK. In the Windows Phone 8.1 SDK, these APIs are located in MFCore.lib. We adjusted the list of linker targets to match the new location.
The MarbleMaze solution for Windows Phone 8.0 had three hanging references to graphics resources that didn’t actually exist in the solution. This didn’t cause a problem for packaging the app for Windows Phone 8.0, but it generated errors for Windows Phone 8.1. The AppX packaging process is less forgiving of such errors, so be prepared to fix them if necessary.