Part 8 - Working with the package.appxmanifest

Download this episode

Download Video


Download the source code for this lesson at

The Package.appxmanifest contains meta-data about your application.  In other words, it describes your app to the operating system including the friendly name of the app, icons and images that will be used on the Start page, what the phone’s hardware must support in order for your app to work properly, and much more.

admittedly, this will lack the context of when you might need to employ some of these settingst demonstrate the specifics of how to implement a given feature.

First, the Package.appxmanifest is used during compilation of your source code into a install package.  The install package will have the file extension appx.  A manifest introduces your app to the phone telling it which assemblies are contained in the appx, which asset files should be used for the start and apps screen of the phone, as well as the app’s name, and the features of the phone that the app uses, and so on.  This is why it is sometimes referred to as the metadata about your app.

Second, when you open it in the main area, you see this tabbed designer:


However, the file is actually just an XML file and this property designer simply modifies its values.  Just for fun, I’ll right-click the Package.appxmanifest in the Solution Explorer and select Open With … in the context menu.  The Open With dialog appears. 


(1 ) Select XML (Text) Editor

(2 ) Click OK

You’ll see the file in it’s “naked” form.  I would recommend you do not change anything about this file, at least not unless you have a very specific reason to do so.  Close the tab to ensure you do not corrupt it.

We’ll re-open the Package.appxmanifest property designer and briefly review the purpose of each of the settings.  Frankly, most of the settings are self-explanatory and yet the nuanced reasons why you may choose to change these settings could require more time than I have in this lesson.  My goal here is to just do a quick review and call to your attention the fact that they exist so that if you’re following some other tutorial in the future, you’ll have some idea of where to look for a given settings.

There are seven tabs:

Visual Assets
Content URIs

We’ll start with the Application tab.  I would classify this as a catch-all for properties that don’t fit nicely in other tabs.  Many of the settings are utilized by the operating system, such as the Display Name, the Default Language, and the Supported Rotations and whether or not you would want to prevent installation of the app to SD cards to prevent users from sharing your app.

The Notifications settings allow you to tell the operating system whether you intend to use Toasts and Lock Screen Notifications in your app. 

A toast displays at the top of the screen to notify users of an event, such as a news or weather alert.


A toast notification displays for about 10 seconds unless the user dismisses it with a flick to the right. If the user taps the toast, by default, your app's start screen launches. Or, you can choose to specify which screen of your app will launch.

Lock screen notifications allow you to update the lock screen with text messages or numbers usually indicating that there’s a number of updated items he user should be aware of.


Your users can choose to customize this area with any eligible third-party apps they choose. As a developer you can design your app to be an app that the phone user can choose to customize the lock screen notifications area.

The lock screen's app icon, count, and text are pulled directly from the app's default Tile.  Info appears on the lock screen only if the default Tile contains this info. For example, a count will appear on the lock screen only if the Tile displays it.

The next tab is for setting the app’s Visual Assets:


We’ll use this later as we build a real app to change the tiles, the splash screen, and more.  Notice that there are different sizes required.  These are required for different states of the tile on the Start or Apps page on the Phone.  On the Start page, the user can decide whether the app should be small, medium or large so you need to provide assets for each of these scenarios.

The next tab is for hardware requirements.  For example, if you were building an app that needed the NFC capability, it wouldn’t make sense for a user to install it on a phone without that feature.  


The next tab is for Capabilities.  A capability is a request for permission.  Suppose your app needs (or wants) to access a given feature of the phone or the data on the given phone.  You can’t just grab it.  The app has to ask for the user’s permission to use that capability because it is usually handling some potentially private information that the user may not want to share with just any app.


The next tab is Declarations.

Think of declarations as other ways that the phone’s operating system can execute or enable certain features of your application.  For example, we may want to allow our application to execute a piece of code every half-hour or so (you don’t get to decide the exact time) so that it can change the phone’s lock screen image.  In that scenario we would add the Background Task declaration and configure the Timer, Executable and Entry Point attributes (perhaps others) to launch that part of your app that changes the image on the lock screen.

Or, in the case of the File Open Picker, you can allow other apps to use your app to choose a given file managed by your app.

The next tab is the Script Notify. 


The idea behind this is pretty cool.  In a few lessons we’ll learn about the Web View control.  It can open up and display web pages.  We’ll be using it to display web pages that are hosted locally in the app’s project.  However, you can also open up external websites as well.  Now, if that external website happens to be running JavaScript that executes a command window.external.notify, it could pass data into your app.  The trick is, you have to indicate which URI’s you want to allow to pass information into your app on this page, and it has to be one with an SSL certificate.  On your side, you handle the WebView_ScriptNotify event, retrieve the data that is being sent.

Finally, the Packaging tab:


As the instructions on the tab explain, they deal with information about the packaging of the app for deployment.  The Package Name is a globally unique identifier, or GUID, that differentiates it from all other apps ever created for the Phone, while the display name, Version and Publisher display name are more human readable and descriptive of the app inside the package.  The last setting, Generate app bundle, allows you to split up your app into multiple parts so that it takes up less space and requires less time to download for the end user.  You might choose to do this is you target multiple languages and have image assets that target different screen sizes and split up your app appropriately into a series of packages that segment those resources.  In these cases, the end user would only download the packages that apply to their language and their screen size.


At the outset, I said that the value of this lesson is in calling to your attention that fact that these settings exist and how you would go about changing them if you needed a given feature.  Furthermore, it helps you see what is possible — the features you may want to employ in your app, even if we don’t demonstrate them in this series of lessons.



Available formats for this video:

Actual format may change based on video formats available and browser capability.

    The Discussion

    • User profile image
      really me

      A small corretion:

      Part 8 - Working with the package.appxmanifest, 05:40: apps and their data on SD cards are encrypted with both an app and a device key. So it is impossible to run apps or access their data from an SD card on a device they were not installed on.

    Comments closed

    Comments have been closed since this content was published more than 30 days ago, but if you'd like to send us feedback you can Contact Us.