The App Manifest in UWP

Analogy categoryAnalogies

Package.appxmanifest is the single XML file that tells Windows, and the Microsoft Store, everything it needs to know about a UWP app before running or installing it: its unique identity, its display name and logos, which device families it supports, what sandbox capabilities it needs, and what system integration points (background tasks, protocol handlers, file associations) it registers for. Visual Studio shows it through a friendly tabbed designer by default, but selecting View Code reveals the underlying XML, and experienced developers often hand-edit it directly for capabilities or extensions the designer doesn't expose a UI for.

🏏

Cricket analogy: Like a player's official ICC registration listing their nationality, team, and eligibility before they're allowed onto the field, Package.appxmanifest declares an app's identity, publisher, and device-family eligibility before Windows will let it run.

Identity, Properties, and Visual Elements

The Identity element carries the app's package-unique Name (a reverse-DNS-style string), Publisher (must exactly match the certificate used to sign the package), and Version (a four-part number like 1.0.0.0) — changing Publisher after the first Store submission effectively creates a different app as far as Windows and the Store are concerned. VisualElements, nested under Applications/Application, wires up the DisplayName, Square150x150Logo (the default Start tile), Square44x44Logo (taskbar and small tile), BackgroundColor, and a SplashScreen image shown while the app cold-starts before MainPage is ready to render.

🏏

Cricket analogy: Like a player's registered jersey number staying fixed with their team for their whole career, an app's Identity Name and Publisher stay fixed for the app's whole lifetime, and changing Publisher effectively creates a new player registration.

Capabilities: Declaring What the Sandbox Allows

The Capabilities section is where the manifest declares exactly which sandboxed resources the app needs: general capabilities like internetClient or microphone go in the default namespace, device capabilities like webcam or location use the DeviceCapability element, and restricted capabilities like broadFileSystemAccess or documentsLibrary (which grant much broader file system reach than the default per-app storage folder) require the rescap XML namespace and must be specifically justified during Store certification. Declaring more capabilities than an app actually uses isn't just bad practice, it also raises flags during Store review and unnecessarily worries users when they see the capability listed on the app's Store page before installing.

🏏

Cricket analogy: Like a bowler declaring their exact variation, say a doosra, to the umpire before delivering it in a suspect-action review, an app must declare each specific capability, like microphone, in the manifest before the sandbox will grant it at runtime.

xml

<Package
  xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
  xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10"
  xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"
  IgnorableNamespaces="uap rescap">

  <Identity Name="Contoso.WeatherApp" Publisher="CN=Contoso Inc" Version="1.2.0.0" />

  <Properties>
    <DisplayName>Contoso Weather</DisplayName>
    <PublisherDisplayName>Contoso Inc</PublisherDisplayName>
    <Logo>Assets\StoreLogo.png</Logo>
  </Properties>

  <Dependencies>
    <TargetDeviceFamily Name="Windows.Universal" MinVersion="10.0.17763.0" MaxVersionTested="10.0.19041.0" />
  </Dependencies>

  <Applications>
    <Application Id="App" Executable="$targetnametoken$.exe" EntryPoint="ContosoWeather.App">
      <uap:VisualElements
        DisplayName="Contoso Weather"
        Square150x150Logo="Assets\Square150x150Logo.png"
        Square44x44Logo="Assets\Square44x44Logo.png"
        BackgroundColor="transparent">
        <uap:SplashScreen Image="Assets\SplashScreen.png" />
      </uap:VisualElements>
    </Application>
  </Applications>

  <Capabilities>
    <Capability Name="internetClient" />
    <DeviceCapability Name="location" />
    <rescap:Capability Name="broadFileSystemAccess" />
  </Capabilities>
</Package>

Extensions: Background Tasks, Protocols, and File Associations

Extensions, declared under Applications/Application/Extensions, are how a UWP app registers itself for system-level integration beyond just being launched by tapping its tile: a windows.backgroundTasks extension registers a background task class that can run on a timer or system trigger even when the app isn't in the foreground, a windows.protocol extension lets the app claim a custom URI scheme (like contoso: links opening directly into the app), and windows.fileTypeAssociation lets the app appear in the Open with list for a specific file extension such as .contoso. Each extension type has its own required child elements, and background task extensions in particular must also declare a corresponding runFullTrust or lockscreen capability depending on what trigger types they use.

🏏

Cricket analogy: Like a franchise registering a specific player as an impact substitute allowed to enter mid-innings under a defined rule rather than the normal XI, a windows.backgroundTasks extension registers a specific class allowed to run under a defined system trigger even when the app isn't in the foreground.

Restricted capabilities (declared with the rescap: namespace, like broadFileSystemAccess, documentsLibrary, or enterpriseDataPolicy) are not granted automatically just by declaring them in the manifest — Microsoft Store certification specifically reviews the justification for each one, and apps requesting restricted capabilities without a clear, legitimate use case can be rejected during submission.

Package.appxmanifest declares an app's Identity (Name, Publisher, Version), Properties, device family targeting, capabilities, and extensions.
Publisher must match the signing certificate exactly; changing it after first submission effectively creates a different app identity.
VisualElements wires up DisplayName, tile logos at multiple sizes, BackgroundColor, and the SplashScreen image.
Capabilities are declared explicitly (internetClient, DeviceCapability like webcam, or rescap: restricted capabilities like broadFileSystemAccess).
Restricted capabilities need the rescap namespace and extra justification during Store certification.
Extensions (windows.backgroundTasks, windows.protocol, windows.fileTypeAssociation) register system-level integrations beyond simple tile launch.