App manifest file for Windows Phone 8

Article
05/20/2016

[ 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

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.

Warning

Your app could become unstable or unusable whenever the app manifest file is modified.

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.

Warning

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.

<?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>

Note

The Capabilities list in the preceding example may not match the list in the manifest file of your app. For more info, see the "Capabilities element" section later in this topic.

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.

Attribute	Type	Definition
xmlns	String	The XML namespace. The default value is https://schemas.microsoft.com/windowsphone/2012/deployment for Windows Phone 8 and https://schemas.microsoft.com/windowsphone/2009/deployment for Windows Phone OS 7.1.
AppPlatformVersion	String	The version of the Windows Phone SDK or the runtime binaries of the platform. The default value is 8.0 for Windows Phone 8 and 7.1 for Windows Phone OS 7.1.

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:

Attribute	Type	Definition
xmlns	String	The XML namespace. The default value is https://schemas.microsoft.com/windowsphone/2012/deployment for Windows Phone 8 and https://schemas.microsoft.com/windowsphone/2009/deployment for Windows Phone OS 7.1.
code	String	The code for the specified language. For example, en for English, or sk-SK for Slovak (Slovakia).

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.

Attribute	Type	Definition
xmlns	String	Blank.
AppPlatformVersion	String	Always 8.0.

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.

Attribute	Type	Definition
Author	String	The app author’s name.
BitsPerPixel	Integer	16 or 32 bits per pixel.
Description	String	The description of the app.
Genre	String	The default value is either Apps.Normal or Apps.Games depending on the project type. Apps that use Apps.Normal appear in the app list on the phone. Apps that use Apps.Games appear in the Games Hub on the phone.
HasSettings	Boolean	Indicates whether the app supports settings.
HubType	Integer	Enables your app to appear in the Extras section of the Music + Videos Hub. It is used for testing before app submission, and must be manually entered in the manifest file. A value of 1 enables this functionality.
IsBeta	Boolean	Indicates whether the app is a beta app. This has consequences for the app license.
ProductID	GUID	The default value is the GUID for the project (128 bit). During the app submission process, a new product ID is inserted into the manifest file.
Publisher	String	The publisher of the app. This default value is the name of the project. This attribute is required for certain types of apps, such as push-enabled apps.
RuntimeType	String	The default value is Silverlight or Modern Native for Windows Phone 8 apps, and Silverlight or XNA for Windows Phone OS 7.1 apps, depending on the project type.
SingleInstanceHost	Boolean	Indicates whether the app has a single instance host.
Title	String	The title of the app that appears in the app list or Games Hub. The default value is the name of the project.
Version	Version String	The default value is 1.0.0.0.
xmlns	String	You can leave this value blank.

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.

Attribute	Type	Description
Name	String	The name of the task. The default value is _default.
NavigationPage	String	The page in the app that a task navigates to when it starts.
ImagePath	String ending in an .exe suffix	The name of the app’s executable file. Optional. [ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]
ImageParams	String	Image parameters. Optional. [ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]
BackgroundExecution	String	The only valid value is Location Tracking. [ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]

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.

Attribute	Type	Description
Name	String	The name of the task.
NavigationPage	String	The page in the app that a task navigates to when it starts.

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.

Attribute	Type	Description
Name	String	The name of the assembly.
Source	String	The assembly source file.
Specifier	String	AudioPlayerAgent, AudioStreamingAgent, or ScheduledTaskAgent.
Type	String	The full class name of the entry point in the assembly.

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.

Element	Type	Description
BackgroundImageURI	String	The name of the local or remote resource that contains the background image of the Tile.
Count	Integer	A Tile can contain a counter that displays a value between 0 and 99. If the value is 0, the counter does not appear on the Tile.
Title	String	The title that appears on the Tile. The default value is the name of the project.

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.

Element	Type	Description
SmallImageURI	String	The name and path for the local or remote resource that contains the background image of the Tile.
Count	Integer	A value between 0 and 99, which is displayed on the Tile. If the value is 0, the counter does not appear on the Tile.
BackgroundImageURI	String	The name and path for the local or remote resource that contains the background image for the Tile.
Title	String	The title that appears on the Tile. The default value is the name of the project.
BackContent	String	The text displayed on the back of the Tile, above the title.
BackBackgroundImageURI	String	The name and path for the local or remote resource that contains the background image for the back of the Tile.
BackTitle	String	The title that appears on the back of the Tile.
LargeBackgroundImageURI	String	The name and path for the local or remote resource that contains the background image for a large Tile.
LargeBackContent	String	The text displayed on the back of a large Tile, above the title.
LargeBackBackgroundImageURI	String	The name and path for the local or remote resource that contains the background image for the back of a large Tile.
DeviceLockImageURI	String	The name and path for the local or remote resource that contains the lock image for the app.
HasLarge	True or False.	A value that indicates whether the app supports large Tiles. No value indicates large Tiles are not supported.

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.

Attribute	Type	Description
ConsumerID	GUID	Restricts access to the extension to the consumer with the specified ProductID. All search extensions require the same value, 5B04B775-356B-4AA0-AAF8-6491FFEA5661.
ExtensionName	String	Identifier for the type of extension support.
ExtraFile	String	Specifies the location of the Extras.xml file. The file must reside in a folder named Extensions and be named Extras.xml.
TaskID	String	Routes the invocation to the specified TaskID. If this attribute is not specified, invocation is routed to the default task.

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.

Attribute	Type	Description
Name	String	A friendly name for the file association.
NavUriFragment	String	Always set to fileToken=%s.
TaskID	String	Always set to _default.

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.

Attribute	Type	Description
Name	String	The prefix in your custom URI scheme. A string between 2 and 39 characters in length that contains numbers, lowercase letters, periods ('.'), or hyphens ('-'). Do not include the colon (':') or anything else that will follow the prefix in the URI.
NavUriFragment	String	Always set to encodedLaunchUri=%s.
TaskID	String	Always set to _default.

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.

Attribute	Type	Description
Name	String	The screen resolutions supported by the Windows Phone 8 app. These include ID_RESOLUTION_WVGA, ID_RESOLUTION_WXGA, and ID_RESOLUTION_HD720P.

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.

App manifest file for Windows Phone 8

Editing the app manifest file

Example app manifest file

Deployment element

DefaultLanguage and Languages elements

AppExtra element

Extra element

App element

IconPath element

Capabilities element

Capability element

Tasks element

DefaultTask element

ExtendedTasks element

BackgroundServiceAgent element

Tokens element

PrimaryToken element

TemplateType5 element

TemplateFlip element

Extensions element

Extension element

FileTypeAssociation element

Protocol element

ScreenResolutions element

ScreenResolution element

Requirements element

Requirement element

FunctionalRequirements element

FunctionalRequirement element

See Also

Other Resources

Additional resources