App manifest file for Windows Phone 8

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

The primary purpose of the manifest file is the following:

• When you submit your apps to the Windows Phone Store, info from the manifest file is used in the certification process, to filter your app correctly in the Store, and to deploy and run your app on the device.

• The info from the manifest file is stored as metadata in the app database.

This topic contains the following sections.

• Editing the app manifest file
• Example app manifest file
• Deployment element
• DefaultLanguage and Languages elements
• AppExtra element
• App element
• IconPath element
• Capabilities element
• Tasks element
• Tokens element
• Extensions element
• ScreenResolutions element
• Requirements element
• FunctionalRequirements element
• Related Topics

Editing the app manifest file

The app manifest file is generated in Visual Studio, and in general you should not edit the file manually. For most scenarios, the manifest file should be modified by using the manifest editor tool. For more info about the manifest editor, see How to modify the app manifest file for Windows Phone 8.

One scenario in which you should use the manifest editor to modify the manifest is when you determine the capabilities used by your app. You should mark the correct capability values in the manifest file. For more info, see How to determine app capabilities for Windows Phone 8.

There are some elements, such as the Extensions section, which require you to edit the manifest file directly. For more info about how to do this, see How to modify the app manifest file for Windows Phone 8.

Some of the values in the manifest file are automatically updated after you submit your app to the Store. Examples include the Author, Publisher, and the ProductID attributes.

Example app manifest file

The following is an example of the default manifest file for a Windows Phone 8 app.

The highlighted items are elements and attributes that are new or changed in Windows Phone 8. For more info about the changes that are made to the app manifest file when you upgrade an app, see How to upgrade an app project to Windows Phone 8.

<?xml version="1.0" encoding="utf-8"?>

<Deployment
   xmlns="https://schemas.microsoft.com/windowsphone/2012/deployment"
   AppPlatformVersion="8.0">
  <DefaultLanguage
     
     code="en-US"/>
  <App
     
     ProductID="{31a2f61a-4083-4250-9c0a-2d68740285b3}"
     Title="NewPhoneAppWP8"
     RuntimeType="Silverlight"
     Version="1.0.0.0"
     Genre="apps.normal"
     Author="NewPhoneAppWP8 author"
     Description="Sample description"
     Publisher="NewPhoneAppWP8"
     PublisherID="{73c86a8f-20c1-4e53-a01e-bfc5aee75273}">
    <IconPath
       IsRelative="true"
       IsResource="false">
         Assets\ApplicationIcon.png
    </IconPath>
    <Capabilities>
      <Capability Name="ID_CAP_NETWORKING"/>
      <Capability Name="ID_CAP_MEDIALIB_AUDIO"/>
      <Capability Name="ID_CAP_MEDIALIB_PLAYBACK"/>
      <Capability Name="ID_CAP_SENSORS"/>
      <Capability Name="ID_CAP_WEBBROWSERCOMPONENT"/>
    </Capabilities>
    <Tasks>
      <DefaultTask
         Name ="_default"
         NavigationPage="MainPage.xaml"/>
    </Tasks>
    <Tokens>
      <PrimaryToken
           TokenID="NewPhoneAppWP8Token"
           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>NewPhoneAppWP8</Title>
          <BackContent></BackContent>
          <BackBackgroundImageURI></BackBackgroundImageURI>
          <BackTitle></BackTitle>
          <DeviceLockImageURI></DeviceLockImageURI>
          <HasLarge></HasLarge>
        </TemplateFlip>
      </PrimaryToken>
    </Tokens>
    <ScreenResolutions>
      <ScreenResolution Name="ID_RESOLUTION_WVGA"/>
      <ScreenResolution Name="ID_RESOLUTION_WXGA"/>
      <ScreenResolution Name="ID_RESOLUTION_HD720P"/>
    </ScreenResolutions>
  </App>
</Deployment>

Deployment element

The Deployment element is the root element. This provides app and localization info in the manifest file when deploying a Windows Phone app.

DefaultLanguage and Languages elements

The DefaultLanguage and Languages elements identify the languages supported by the app. The languages that you specify in these elements are listed with your app in the Windows Phone Store.

The DefaultLanguage element is required. If you specify a language that is not supported in the Store, the app is rejected when it is submitted.

The DefaultLanguage element in the app manifest file corresponds to the Neutral Language setting that you specify in the Assembly Information dialog box on the Application page of Project Designer. Setting or changing the Neutral Language updates the value of DefaultLanguage when you close the Assembly Information dialog box. However this synchronization is only one-way, and is not enforced if you later change the value of DefaultLanguage manually.

If your app’s Neutral Language is not supported in the Store, specify another language that your app supports as the value of DefaultLanguage.

The Languages element is optional. On the Packaging page of Manifest Designer, this element is labeled Supported Languages. If you specify a language that is not currently supported in the Store, it is ignored when the app is submitted.

The Languages element in the app manifest file corresponds to the Supported Cultures list on the Application page of Project Designer.

• Adding items to the Supported Cultures list in project properties updates the Languages list in the app manifest file when you save the project properties. However, this synch is only one-way, and is not enforced if you later change the Languages list in the app manifest file directly. Make sure that both lists contain the same items before you publish your app.

• Removing items from the Supported Cultures list in project properties does not remove them from the Languages list in the app manifest file. Remove the same items manually from the Languages list in the app manifest file.

For more info, see Globalization and localization for Windows Phone 8.

Both the DefaultLanguage and the Languages elements have the following attributes:

AppExtra element

The AppExtra element is an optional child of the Deployment element for apps that target Windows Phone 7.8. The AppExtra element has the following syntax.

<AppExtra  AppPlatformVersion="8.0">
    <Extra Name="Tiles"/>
</AppExtra>

The following table defines the attributes of the App element.

Extra element

The Extra element is a child of the AppExtra element. The Extra element has one attribute, Name. The name specifies the extra feature that you want to enable for your app. The only value for Name is Tiles. For more info, see Adding Windows Phone 8 and Windows Phone 7.8 Tile functionality to Windows Phone OS 7.1 apps.

App element

The App element is a child of the Deployment element. It supplies info such as the product ID, version, and type of app. The following table defines the attributes of the App element.

IconPath element

The IconPath element is a child of the App element. It provides the location of the app icon that is visible in the app list. On devices with Windows Phone 8 Update 3, the app icon is also displayed in the task switcher. The attributes are for internal use only.

The default image for apps is ApplicationIcon.png. The default image for XNA Framework games is PhoneGameThumb.png.

Capabilities element

The Capabilities element is a child of the App element. Windows Phone provides a capabilities-driven security model where a user must opt-in to certain functionality within the app. Some examples include using network-based services where a user could incur additional roaming charges if the use of the services was not disclosed in the app, or the use of push notifications that can also produce roaming charges. The primary goals of this capability model are to:

• Ensure proper disclosure – Users must be notified if an app’s functionality poses security risks. They must opt-in to allow the functionality to be activated.

• Decrease the attack surface – Capabilities are used to create a security chamber in which the app executes. This chamber is created once at install time and used from then on for the app.

When you are developing your app, you can successfully deploy and run your app in Windows Phone Emulator without specifying the correct capabilities, but you must specify the correct capabilities when you deploy the app to a phone. If you do not use a capability when needed, the app throws a UnauthorizedAccessException exception. It displays an Access denied message when you attempt to use the functionality in the app, and exits unexpectedly if the exception is not handled. You can determine what capabilities your app uses by using the Windows Phone Store Test Kit, and mark the capabilities that your app uses by using the manifest editor. For more info see, How to determine app capabilities for Windows Phone 8 and How to modify the app manifest file for Windows Phone 8.

Capability element

The Capability element is a child of the Capabilities element. The Capability element has one attribute, name. The name specifies the capability you want to enable for your app. For more info about the capability values you can specify for the name property, see App capabilities and hardware requirements for Windows Phone 8.

Tasks element

The Tasks element is a child of the App element. This element is for internal use only.

DefaultTask element

The DefaultTask element is defined by Visual Studio during development.

ExtendedTasks element

The ExtendedTasks element is a child of the Tasks element and contains BackgroundServiceAgent elements. This element defines the use of multiple tasks by an app. Extended tasks are named by the developer. Currently, you can use the ExtendedTasks element only to define background tasks.

BackgroundServiceAgent element

The BackgroundServiceAgent element is a child of the ExtendedTasks element and contains the details of a background service agent used by the app.

Tokens element

The Tokens element is a child of the App element. Each app has a Tile that the user can pin to the Start screen. The following sections provide the names and describe the elements and attributes for Tiles in the manifest file. For more info, see Tiles for Windows Phone 8.

PrimaryToken element

The PrimaryToken element is a child of the Tokens element. It describes the Tile that is associated with an app.

Attribute	Type	Description
TokenID	String	The name of the Tile. The default value is the project name. Caution: If you change the TokenID of your primary token, it should not match the TokenID of any of your secondary Tiles. In that scenario, users may not be able to install updates to the app.
TaskName	String	The name of the task that the Tile invokes when the user taps it. The default value is _default.

TemplateType5 element

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

The TemplateType5 element is a child of the PrimaryToken element. It is the default template that controls app Tiles for Windows Phone OS 7.1. The following table describes the child elements of the TemplateType5 element.

TemplateFlip element

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

The TemplateFlip element is a child of the PrimaryToken element. It is the default template that controls app Tiles for Windows Phone 8. The following table describes the child elements of the TemplateFlip element. For more info about the Flip Tile, see Flip Tile template for Windows Phone 8.

Extensions element

The Extensions element is a child of the App element and immediately follows the Tokens element. This element is used to specify the extensions that your app supports. For more info, see Search extensibility for Windows Phone 8. For more info about editing this section, see How to modify the app manifest file for Windows Phone 8.

Important Note:
The order of elements in the Extensions element is important. All Extension elements should be listed first, followed by all FileTypeAssociation elements, followed by all Protocol elements.

Extension element

All Extension elements should be listed first under the Extensions element. Each Extension element describes an App Connect extension.

FileTypeAssociation element

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

The FileTypeAssociation element is a child of the Extensions element and should always follow the Extension element. The FileTypeAssociation element describes file associations between your app and certain file types. This entry enables you to associate your app with some types of files, and give the user the option of starting your app to view those file types. You can register a maximum of 20 file associations. For more info, see Auto-launching apps using file and URI associations for Windows Phone 8.

Protocol element

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

The Protocol element is a child of the Extensions element, and Protocol elements should always follow all FileTypeAssociation elements. The Protocol element describes URI scheme names that your app is registered for, enabling it to launch when another app launches a special URI. For more info, see Auto-launching apps using file and URI associations for Windows Phone 8.

ScreenResolutions element

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

The ScreenResolutions element is a child of the App element. This element is used to specify the resolutions that your app supports. For more info, see Multi-resolution apps for Windows Phone 8.

ScreenResolution element

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

The ScreenResolution element is a child of the ScreenResolutions element and specifies a resolution supported by the app.

Requirements element

The Requirements element is a child of the App element, and should immediately follow the ScreenResolutions element for Windows Phone 8, and the Capabilities element for Windows Phone OS 7.1. Beginning in Windows Phone SDK 7.1.1 Update, use this element to indicate if the app requires certain hardware. For example, if the app will not run on a lower-memory device, you should specify it in this section. The primary goal of this element is to block users from purchasing or installing apps that will not run on their phone. A Requirements element is not required in your manifest file if the app can run on all Windows Phones and it has no other special hardware requirements.

Requirement element

The Requirement element is a child of the Requirements element. The Requirement element has one attribute, name, which accepts a string value. You can mark the hardware requirements for your app using the manifest editor. For more info see, How to modify the app manifest file for Windows Phone 8. For more info about the values you can specify for the Requirement name value, see App capabilities and hardware requirements for Windows Phone 8.

FunctionalRequirements element

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

The FunctionalRequirements element is an optional child of the App element and should immediately follow the Requirements section in the manifest file. Use the FunctionalRequirements element to indicate if the app requires certain hardware functionality, such as the increased memory limit. For example, if the app will not run on a lower-memory device, you should specify it in this section.

FunctionalRequirement element

The FunctionalRequirement element is a child of the FunctionalRequirements element. The FunctionalRequirement element has one attribute, name, which accepts a string value. For more info about the values you can specify for the FunctionalRequirement name value, see App capabilities and hardware requirements for Windows Phone 8.

See Also

Other Resources

How to modify the app manifest file for Windows Phone 8

App certification requirements for Windows Phone