Retarget your Windows Store app to Windows 8.1

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

To port your Windows Store app to Windows 8.1, you must retarget your projects and update your code. For the smoothest transition, we recommend that you perform the following steps.

  • Step 1: Copy your solution.
  • Step 2: Retarget your projects.
  • Step 3: Fix errors that relate to file paths and extension SDKs.
  • Step 4: Update your code to target new APIs and features.
  • Step 5: Service the Windows 8 version of your app.

Note  To retarget your project, you must be running Windows 8.1. After you retarget your project, you won't be able to open that project on a computer that runs Windows 8.

 

Step 1: Copy your solution

If you want to continue to update the Windows 8 version of your app, we recommend that you copy your solution before you retarget it.

If you’re managing your solution in version control, we recommend that you create a branch for the Windows 8 version of your app. Then, you can retarget the solution in the main branch.

If you’re not using version control, we recommend that you copy your solution to another folder and then retarget that copy of the solution.

To create a branch in Team Foundation Service (for solutions in version control)

  1. In Source Control Explorer, open the shortcut menu for the branch or folder that contains the solution files of the app that you want to retarget, and then choose Branch.

    The Branch dialog box appears.

  2. In the Target box, specify the path of the new branch.

  3. (Optional) In the Branch from version section, specify whether to branch from the most recent version, a version from a specific date, or a specific changeset.

  4. Choose the Branch button.

    See Branch Folders and Files.

To create a folder (for solutions that aren't in version control)

  1. Copy your solution folder to a place on your computer that makes sense to you.

  2. Rename the original folder with a name that makes sense (for example, SolutionName_8.1).

  3. If your solution references projects that are outside of your solution folder, copy them to a location that makes sense (for example, next to the SolutionName_8.1 folder).

Step 2: Retarget your projects

Change the target of each project in your solution from Windows 8 to Windows 8.1.

  1. If you're managing your files in version control, make sure to check out the entire solution.

  2. Open your solution in Microsoft Visual Studio 2013.

    • If you're opening your solution in Microsoft Visual Studio Express 2013 for Windows, your solution won't load. In the next step, you'll retarget the projects in your solution.
    • If you're opening your solution in Microsoft Visual Studio Professional 2013, Microsoft Visual Studio Premium 2013 Preview, or Microsoft Visual Studio Ultimate 2013, your solution loads but still targets Windows 8.
  3. In Solution Explorer, open the shortcut menu for the solution, and then choose Retarget Windows Store projects to Windows 8.1.

  4. In the Project and Solution Changes dialog box that appears, select each project that you want to retarget, and then choose the OK button.

    The selected projects now target Windows 8.1.

    Note  You can also retarget projects individually by opening the shortcut menu of a project, and then choosing Retarget to Windows 8.1.

     

Step 3: Fix errors that relate to file paths and extension SDKs

Fix errors that relate to file paths

If your solution contains absolute paths to files in other projects, you might have to fix those paths so that they reference files in the versions that you created in Step 1: Create a copy of your solution.

When you build a project, errors and warnings might appear in the Error List and the Output Window if your project refers to files by using paths that are no longer valid (e.g. APPX1639: File 'Windows.props' not found) and you can identify and fix file paths by using these errors and warnings. We recommend that you use relative paths whenever possible.

Fix errors that relate to extension SDKs

Errors might appear if your project references extension SDKs that were authored in C++ and created for Windows 8 . That's because those SDKs depend on the Microsoft Visual C++ Runtime Package v11.0, and that package might not be installed on your computer.

To resolve these errors, install the Tools for Maintaining Store apps for Windows 8. Those tools install the Microsoft Visual C++ Runtime Package v11.0 on your computer. For more information, see To add the Tools for Maintaining Store apps for Windows 8.

If you still receive errors after you have installed the tools, remove your project’s reference to the extension SDK. Then, open the Reference Manager dialog box and add the reference that SDK back to the project.

In some cases, you can obtain an updated version of an extension SDK that is compatible with Windows 8.1. If a compatible version of an SDK isn't yet available for download, and errors still appear when you build your project, refer to the Visual Studio readme file for guidance about how you can temporarily resolve the issue so that you can compile and run your app on your development computer.

Step 4: Update your code to target new APIs and features

Many APIs and features that were previously available in Windows 8 have been changed. In some cases, they've been replaced by new APIs and features. As you compile and test your app, you might encounter warnings that you’ll have to fix. For a complete list of changed API and features, see the following topics:

Project templates for Windows Store apps have changed because Windows 8.1 offers new ways to accomplish certain scenarios. Visual Studio doesn't modify the structure or contents of your solution, so your solution might contain files that wouldn't be present in a new project that targets Windows 8.1. Your solution might continue to run successfully, but we recommend that you investigate how to optimize your app for Windows 8.1 and apply new best practices. For more information, see Windows 8 to Windows 8.1 for XAML developers.

For general information about the structure of project templates that you can use to build Windows Store apps in Visual Studio 2013, see the following topics:

Step 5: Service the Windows 8 version of your app

If you're managing your solution in version control, we recommend that you service the Windows 8 version of your app by updating files in the branch that you created in Step 1: Create a copy of your solution.

If you aren't using version control, we recommend that you service the Windows 8 version of your app by updating files in the original folder (not the copy).

You can service the Windows 8 version of your app by using any of the following versions of Visual Studio if you also install the Tools for Maintaining Store apps for Windows 8.

Version of Visual Studio Required Operating System
Visual Studio Professional 2013 Windows 8.1
Microsoft Visual Studio Premium 2013 Windows 8.1
Visual Studio Ultimate 2013 Windows 8.1
Microsoft Visual Studio 2012 Windows 8.1 or Windows 8

 

Note  You can't use Visual Studio 2013 on a computer running Windows 8 to maintain the Windows 8 version of your app even if you install the Tools for Maintaining Store apps for Windows 8.

 

When you install any of these editions of Visual Studio, make sure that the Tools for Maintaining Store apps for Windows 8 check box is selected. If you don't, an error will appear when you open the project for the Windows 8 version of your app, and you'll have to add the tools.

To add the Tools for Maintaining Store apps for Windows 8

  1. In Control Panel, open Programs and Features, choose the item that represents your installation of Visual Studio, and then choose the Change button.

  2. In the setup wizard for Visual Studio, choose the Continue button, and then choose the Modify button.

  3. In the Optional features to install list, select the Tools for Maintaining Store apps for Windows 8 check box, and then choose the Update button.

You can't service the Windows 8 version of your app by using Visual Studio Express 2013 for Windows. That version of the app won’t load in that version of Visual Studio until you retarget the solution to Windows 8.1.