How to upgrade an app project to Windows Phone 8

  • Article

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

You can easily upgrade an existing Windows Phone app project that targets Windows Phone OS 7.1 to target Windows Phone 8.

This topic contains the following sections.

 

Before upgrading

Create a backup copy of the project before you upgrade it, especially if you want to target both Windows Phone 8 and Windows Phone OS 7.1 with your app. The upgrade process does not make a copy of your project; it upgrades the project in place. After you upgrade a project, you cannot later convert it back to Windows Phone OS 7.1.

Ensure that the project file and the app manifest file (WMAppManifest.xml) are not marked as read-only. The upgrade process requires write access to these files.

Upgrading a project from Windows Phone OS 7.1 to Windows Phone OS 8.0 

You can upgrade an existing Windows Phone project in Visual Studio in one of the following ways:

  • In Solution Explorer, use the Upgrade to Windows Phone 8.0 command on the project’s context menu.

  • In Project Designer, change the Target Windows Phone OS Version property value to Windows Phone OS 8.0.

You cannot upgrade XNA Game Studio 4.0 projects to Windows Phone 8. For more info, see XNA Framework and app development for Windows Phone 8.

To upgrade a Windows Phone OS 7.1 project by using the Upgrade to Windows Phone 8.0 command in Solution Explorer

  1. In Visual Studio, open the Windows Phone OS 7.1 app project that you want to upgrade.

  2. In Solution Explorer, right-click the project, and in the context menu, select Upgrade to Windows Phone 8.0. The project is upgraded to target Windows Phone 8.

    The following illustration shows the Upgrade to Windows Phone 8.0 command on the project’s context menu in Solution Explorer.

To upgrade a Windows Phone OS 7.1 project by changing the target version in Project Designer

  1. In Visual Studio, on the Project menu, click Properties to open Project Designer.

  2. In Project Designer, on the Application page, in the Target Windows Phone OS Version drop-down list, select Windows Phone OS 7.1.

  3. Save your changes. The project is upgraded to target Windows Phone 8.

    The following illustration shows the target version drop-down list on the Application page in Project Designer.

After upgrading

If you upgrade a project that’s referenced by other projects that target Windows Phone OS 7.1, you also have to upgrade the other projects. Otherwise you have Windows Phone OS 7.1 projects that reference a Windows Phone 8 project. This scenario is not supported.

If you add features that are available only in Windows Phone 8 to a project after you upgrade it, then you may also need to make the following changes.

  • If you use APIs that are new in Windows Phone 8, you may need to add references to your project for the assemblies that contain the new APIs, and import the namespaces into your code files.

  • If you add new Windows Phone 8 features to the app, you may need to edit the capabilities and hardware requirements in the app manifest file.

    However the upgrade process automatically removes the deprecated ID_CAP_MEDIALIB capability and replaces it with the new ID_CAP_MEDIALIB_AUDIO, ID_CAP_MEDIALIB_PLAYBACK, or ID_CAP_MEDIALIB_PHOTO capability as appropriate.

For info about compatibility issues between apps that target Windows Phone OS 7.1 and apps that target Windows Phone 8, see App platform compatibility for Windows Phone 8. These compatibility issues may affect the behavior of your app after you upgrade it.

For info about reusing code while maintaining an app that targets both Windows Phone 8 and Windows Phone OS 7.1, see How to target multiple versions with your app for Windows Phone 8.

Changes in the upgraded app manifest file

When you upgrade an existing project that targets Windows Phone OS 7.1 to target Windows Phone 8, the upgrade process makes the following changes in the app manifest file.

For more info about the Windows Phone 8 app manifest file, see App manifest file for Windows Phone 8.

Note

In the following XML samples, line breaks have been added to improve readability. If you modify the app manifest file manually, don’t add line breaks or additional whitespace.

Feature

OS version

Change

Namespace

7.1

https://schemas.microsoft.com/windowsphone/2009/deployment

8.0

https://schemas.microsoft.com/windowsphone/2012/deployment

Version number

7.1

AppPlatformVersion=7.1

8.0

AppPlatformVersion=8.0

Default language

7.1

None

8.0

 
<DefaultLanguage  code="en-US"/>

PublisherID

7.1

None

8.0

 
<App … PublisherID="{new random GUID}" … >

Capability

7.1

ID_HW_FRONTCAMERA

8.0

Replaced with ID_REQ_FRONTCAMERA hardware requirement

Capability

7.1

ID_MEDIALIB

8.0

Replaced with one or more of the following:

  • ID_CAP_MEDIALIB_AUDIO

  • ID_CAP_MEDIALIB_PLAYBACK

  • ID_CAP_MEDIALIB_PHOTO

Tile support

7.1

 
<Tokens>
  <PrimaryToken
      TokenID="EmptyNewWP71ProjectToken"
      TaskName="_default">
    <TemplateType5>
      <BackgroundImageURI IsRelative="true" IsResource="false">
        Background.png
      </BackgroundImageURI>
      <Count>0</Count>
      <Title>EmptyNewWP71Project</Title>
    </TemplateType5>
  </PrimaryToken>
</Tokens>

8.0

 
<Tokens>
  <PrimaryToken
      TokenID="EmptyNewWP80ProjectToken"
      TaskName="_default">
    <TemplateFlip>
      <SmallImageURI IsRelative="true" IsResource="false">
        Assets\Tiles\FlipCycleTileSmall.png
      </SmallImageURI>
      <Count>0</Count>
      <BackgroundImageURI IsRelative="true" IsResource="false">
        Assets\Tiles\FlipCycleTileMedium.png
      </BackgroundImageURI>
      <Title>EmptyNewWP80Project</Title>
      <BackContent></BackContent>
      <BackBackgroundImageURI></BackBackgroundImageURI>
      <BackTitle></BackTitle>
      <DeviceLockImageURI></DeviceLockImageURI>
      <HasLarge></HasLarge>
    </TemplateFlip>
  </PrimaryToken>
</Tokens>

Screen resolution

7.1

None

8.0

 
<ScreenResolutions>
  <ScreenResolution Name="ID_RESOLUTION_WVGA"/>
  <ScreenResolution Name="ID_RESOLUTION_WXGA"/>
  <ScreenResolution Name="ID_RESOLUTION_HD720P"/>
</ScreenResolutions>

Upgrading a project from Windows Phone OS 7.0 

If you open a project that targets Windows Phone OS 7.0 in the Windows Phone SDK 8.0 tools, Visual Studio prompts you to upgrade the project to target Windows Phone OS 7.1. After you upgrade the project to target Windows Phone OS 7.1, you can upgrade the project to target Windows Phone 8.

To upgrade a project from Windows Phone OS 7.0 

  1. In Visual Studio, open the project that targets Windows Phone OS 7.0. The following dialog box prompts you to upgrade the project.

  2. Click OK. The project is upgraded to target Windows Phone OS 7.1. Optionally, you can now upgrade the project to target Windows Phone 8.

Known upgrade issues

This section describes some scenarios in which upgrade may fail, and helps you to understand and resolve the cause of the failure.

After upgrade, building your app project fails with an error about unresolved references

Issue. An existing project references an SDK assembly. You uninstall Windows Phone SDK 7.1 and install Windows Phone SDK 8.0. Windows Phone SDK 8.0 installs a newer version of the same SDK assembly in the same path. The older assembly referenced by the project is no longer present on the computer. As a result, you can’t build the project successfully with Windows Phone SDK 8.0 either before or after upgrading the project.

Example. Windows Phone SDK 7.1 installs version 5.2 of the Microsoft Advertising SDK assembly. Windows Phone SDK 8.0 installs version 6.1 of the same assembly in the same path for apps that target Windows Phone OS 7.1. If you remove Windows Phone SDK 7.1, the older assembly referenced by the project is no longer present on the computer.

Symptoms. You may see a warning or error similar to one of the following.

The type or namespace name 'Advertising' does not exist in the namespace 'Microsoft' (are you missing an assembly reference?)

Could not resolve this reference. Could not locate the assembly "Microsoft.Advertising.Mobile, Version=5.2.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35, processorArchitecture=MSIL". Check to make sure the assembly exists on disk. If this reference is required by your code, you may get compilation errors.

The referenced component 'Microsoft.Advertising.Mobile' could not be found.

Resolution. Manually remove the reference to the older version and add a reference to the newer version of the SDK assembly.

After upgrade, building your app project fails with an error about duplicate types or ambiguous types

Issue. An existing project uses an API from an assembly in a Microsoft SDK such as the Windows Phone Toolkit. In Windows Phone 8, the API has been moved into a different namespace in the Windows Phone 8 reference assemblies. As a result, the compiler can’t choose between the definition in the SDK assembly and the definition in the reference assembly.

Example. The System.Tuple type was defined in the Windows Phone Toolkit for Windows Phone OS 7.1. In Windows Phone OS 8.0, the System.Tuple class has been moved to mscorlib.dll. If your upgraded project still has a reference to the Windows Phone Toolkit for Windows Phone OS 7.1, along with the default reference to mscorlib.dll, you may see an error about duplicate or ambiguous types.

Symptoms. You may see a warning similar to the following.

The predefined type 'System.Tuple' is defined in multiple assemblies in the global alias; using definition from 'c:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\WindowsPhone\v8.0\mscorlib.dll'

Resolution. Manually update your code to point to the correct namespace for the type in the Windows Phone 8 reference assembly. Or, if the type definition has been moved to a newer version of the same SDK assembly, manually remove the reference to the older version and add a reference to the newer version of the SDK assembly.

Upgrade fails with an error about project imports

Symptoms. Clicking Upgrade to Windows Phone 8.0 fails with an error indicating that a project import was not found.

Resolution. Ensure that you haven’t changed the existing import declarations in the project file to create custom conditional imports. After removing any customizations, retry the upgrade.

More information. For a successful upgrade, you have to leave intact the import declarations that are created in the project file. Removing or editing default import declarations can prevent a successful upgrade of the project to Windows Phone 8. If you have customized the import declarations, you may have to undo the customization done before upgrading.

Upgrade fails because the reference to System.Core.dll or mscorlib.dll is missing

Symptoms. Clicking Upgrade to Windows Phone 8.0 fails with the following error.

Resolution. Check whether some of the default references are missing from the project. In particular, ensure that System.Core.dll and mscorlib.dll are referenced. If these references are missing, then restore the references to the Windows Phone OS 7.1 versions of these assemblies from the following path:

Program Files (x86)\Reference Assemblies\Microsoft\Framework\Silverlight\v4.0\Profile\WindowsPhone71\

After restoring the missing references, retry the upgrade.

More information. Explicit references to System.Core.dll and mscorlib.dll are required in projects that target Windows Phone OS 7.1. These references have to be present before you can upgrade the project to Windows Phone 8.

See Also

Other Resources

How to target multiple versions with your app for Windows Phone 8