Windows 8.1 Universal Apps (Part 3: Visual Studio and the App Manifest)

Support in Visual Studio

So, we have Universal Apps, we can share code, using the WINDOWS_PHONE_APP constant if we need to.

This is all great, but at least for now, Windows 8.1 and Windows Phone 8.1 still have quite a few differences. Windows 8.1 apps can snap and have large square tiles, they can be upside down (while phone only has one portrait orientation), and phone apps can have requirements, so that you can ensure the device has what your app needs (e.g. front camera or GPS).

As such, there are still unique differences between the two types, and we need to configure them. Of course, Microsoft provided a way for us to do this. We’ll look closely now at some of the files that come in the Universal App projects.

So, we have our three projects, populated with various files. Let’s list what we have:

  • .Windows
    • Assets\
    • MainPage.xaml
    • MainPage.xaml.cs
    • Package.appxmanifest
  • .WindowsPhone
    • Assets\
    • MainPage.xaml
    • MainPage.xaml.cs
    • Package.appxmanifest
  • .Shared
    • App.xaml
    • App.xaml.cs

You can probably already see that the Windows and Windows Phone projects look very similar, and they are. I won’t describe the two projects separately, but just a general description and then mention any differences.

The Assets folder contains some default assets for your application. It contains a few logos of various sizes, and the Phone project has a few more as it requires a few more to be a valid project. I recommend you use the Assets folder for application assets (icons, splash screen images, etc.), but keep other application files (such as images you use in-app) separate, just because it’s easier to maintain. It’s entirely up to you, though.

The MainPage.xaml and MainPage.xaml.cs files are the first app page that is launched. The next part of this series covers XAML, including these files, in more detail, as well as App.xaml and App.xaml.cs in the Shared project.

The most interesting file is Package.appxmanifest. This file lets us configure each project independently of the other project and choose platform-specific options. The file itself is an XML file, but if you open it via Visual Studio you are presented with a friendly UI to configure it without having to fiddle with XML directly.

There are 6 tabs of options for Windows apps, and 7 tabs on Windows Phone (the additional one is for Requirements).

Application:

Application Tab

Here you configure the core details of the Application: the name, description and default language, the entry point (what file should first be executed when your app opens, which by default is yourapp.App, which corresponds to App.xaml), and a few capabilities about things like orientation and toast (notification) support.

This tab is fairly simple to deal with, as most things are fairly clear or just involve entering text about your app.

Visual Assets:

Visual Assets

This is where you define the visual assets for the app, by which we mean the icons, splash screen and tile colour. There are varying sizes of tile, and for your app to be able to use that tile size, you must provide at least one of these. You may also notice that there are multiple scaled assets for each tile icon (three on Windows Phone 8.1, four on Windows 8.1). This is how different DPI screens are managed, and I strongly recommend that you provide images for each scale.

A few of these must be provided. These are the ones that already have an icon provided by Visual Studio. While I’m mentioning these default icons, a tip: replace these. Your app will not be approved to be on the store if you use the default icons!

Requirements:

Requirements As previously mentioned, this tab only appears for the manifest file in the Phone project.

Here you can choose which hardware requirements your app has, if any. There are only five valid requirements: Gyroscope (to detect motion), magnetometer (compass support), NFC (Near Field Communication) and the front and back cameras.

If a phone doesn’t have all of the hardware you request, they will not be able to locate it in the store or install it in any other way.

Capabilities:

Capabilities

This tab lets you pick what capabilities your app will have. In this context, capabilities means what additional OS features you need access to that are not available by default. These capabilities will all show up on the store page for your app so that the user knows you require these. Choosing these options, particularly things like access to the user’s library or other personal detail without it being clear exactly why you need these is a quick way to have users suspect your app of malware-like behaviour and people will avoid it.

Only ask for a capability if you actually need it.

Declarations:

Declarations

Declarations are how you declare that your app performs additional functionality that default apps do not. The difference between capabilities and declarations are that capabilities are requesting access to additional things (such as the internet, the user’s pictures or camera), while declarations are saying you perform additional tasks, such as being able to read a certain filetype, being able to handle a certain protocol, or supporting background tasks.

All declarations require, at minimum, the entry point into your application. That’s because every single declaration is informing the OS of a different way your application can be launched and accessed. Some of them require additional detail, such as Background Task support. I’ll cover this in more detail in the next part of this series, where I cover background tasks.

Content URIs:

Content URIs

This tab lets you declare which external URIs are allowed to call windows.external.notify to communicate with your app directly.

You need to be aware that any URIs declared in here are able to message your app which can cause things to happen. This is most useful if your app is essentially a web wrapper with some additional functionality, but you should be careful to not declare a site you don’t have direct control over!

I’ve never used this feature, and honestly I don’t know how many apps actually do, but I’d imagine it’s quite low.

Packaging:

Packaging

This final tab is mostly useless and you don’t need to interact with it. The Package name, Package display name, Publisher display name and Package family name are automatically replaced when your app is uploaded to the store.

The version number field is set by you, and should follow the pattern Major.Minor.Build.Revision. Microsoft used to recommend that Major should be at least 2 (so that the entire 1.x.x.x range is available for Windows 8.0 apps) but that isn’t necessary now. Lastly, the generate app bundle should just be left on If needed.