Skip to content

Xaml app structure

Jump to bottom
Carlos González edited this page Jan 23, 2019 · 1 revision

A Universal Windows Platform XAML project is the one used for Default UWP app creation. It has a group of needed files to work specifically for XAML, that runs in a normal window and visual design.

Structure is the same for almost all programming languages. Objective-C differs from the XAML structure only because it doesn't have MainPage class, and Javascript and Typescript use the HTML structure (similar to XAML), but Java uses a more complex Non-XAML structure, which differs a lot.

Files in the project

These files and folders are inside a Default UWP app project:

  • References: This project folder includes dlls that are added to the project from local or internet sources, Nuget packages, app dependencies and UWP extensions.
  • Properties: This folder contains the AssemblyInfo.(file extension of the programming language, for example .cs from C#) file and Default.rd.xml file.
  • Assets: This folder has all the assets (media) of the app. By default, the manifest file references to this folder for the tile icons, app list icons, splash screen image and the app icon.
  • App.xaml: This file represents the application, creates the app windows from the App.xaml.(file extension of the programming language, for example .pas from Oxygene) file, declares the app default theme (light or dark) in the markup, and also defines the location of application resources files (for example AppStyles.xaml).
  • App.xaml.(x): Is the class that has the window and running properties, divided into OnLaunched, OnNavigationFailed and OnSuspending. Because it's a code behind file, it references libraries.
  • MainPage.xaml: This XAML file is the one that has the UI of the first (or the only one) page of the application in XAML controls. The code that the controls will run when used or clicked is specified in the MainPage.xaml.(file extension of the programming language, for example .cpp from C++) code behind file.
  • MainPage.xaml.(x): This class has all the instructions for the app XAML controls, the app logic and the event handlers. Because it's a code behind file, it references libraries.
  • Package.appxmanifest: Is the app manifest project file, which states the assets, app orientation, package name, app name, capabilities, app certificate, app version, and available tile images.
  • Project.json: This file has the dependencies list, used framework (default is uap10.0), and runtimes list.
  • Project.lock.json: Has the locked status, version number and targets of the app compiling.
  • AppStyles.xaml: This markup file is the one that freely customizes XAML controls styles. It has to be referenced in the App.xaml file.
  • (ProjectName)_TemporaryKey.pfx: This certificate file is the one which signs temporarily the app project. When a project doesn't have this file, it can be generated by the package.appxmanifest file project.
  • ProjectName.(x): Is the project file, which has the target properties, SDK versions, target compiling and other project properties. The file extension will change depending on the programming language project (e.g. a Visual Basic project will have .vbproj file extension).
  • ProjectName.sln: This is the Visual Studio solution file that references the projects included in the same solution and the main project for building/compiling.

References

The references project folder contains the Nuget packages, app dependencies, added DLL files and UWP extensions. Normally, a UWP project will have the Universal Windows Platform reference.

If it's an Oxygene or Swift project it will have Delphi.dll or Swift.dll files respectively, and the two will have Echoes.dll referenced too.

These are the types of references:

  • Nuget packages: These are packages added from the Nuget website, which has UWP-compatible packages with libraries and dlls from Microsoft and from a lot of other organizations and people. An example is the .NET Core package, which is commonly added automatically to new UWP projects.

  • App dependencies: These are the non-Nuget packages automatically added to new UWP projects, like the Universal Windows Platform dependency.

  • Added DLL libraries: These are external libraries in .dll format which are referenced from local storage. Example of a .dll reference is the Echoes.dll, which is needed for Swift and Oxygene projects.

  • UWP extensions: The UWP extensions are libraries/packages that have specific extensions for the UWP, like the Mobile Extensions for the UWP.

Properties

This folder contains AssemblyInfo.(x) and Default.rd.xml files.

  • AssemblyInfo.(x): This file has the basic assembly information of the UWP project, automatically written in the chosen programming language.

  • Default.rd.xml: This file has the directives of the project and the assembly name in a simple and little markup text.

AssemblyInfo.(x)

This class has the basic assembly information that will have the final generated .exe file when the project is built, applied at the assembly level.

It is coded in the selected programming language for the UWP application project, so if Swift programming language is selected for the project, it will be called AssemblyInfo.swift.

The file starts with the references. In the Swift variant of the file, references begin with the 'import' word.

import System.Reflection
import System.Runtime.CompilerServices
import System.Runtime.InteropServices

Then goes the assembly main information. The attributes can be information of the company, product, or even the languages it supports.

@assembly: AssemblyTitle("_ProjectName_")
@assembly: AssemblyDescription("")
@assembly: AssemblyConfiguration("")
@assembly: AssemblyCompany("")
@assembly: AssemblyProduct("_ProjectName_")
@assembly: AssemblyCopyright("Copyright ©  20xx")
@assembly: AssemblyTrademark("")
@assembly: AssemblyCulture("")

And then the assembly file version. The first number is major version, the second is minor version, the third is build number, and the fourth is revision.

@assembly: AssemblyVersion("1.0.0.0")
@assembly: AssemblyFileVersion("1.0.0.0")
@assembly: ComVisible(false)

Assets

This folder has by default all the assets of the app. The folder includes the tile icons, app list icons, splash screen image and the app icon. New projects have default assets classification:

  • LockScreenLogo: Assets with this name are the ones shown in the Windows 10 lock screen, because of the notifications.

  • SplashScreen: These assets are the ones shown when the app is opened. They're basically the splash screens of the app.

  • Square(??x??)Logo: These assets are the square tile images, shown in the app list, taskbar, desktop and start menu/screen.

  • Wide(??x??)Logo: These assets are the wide tile images, shown in the start menu/screen, when tile is turned into wide mode.

  • StoreLogo: This image is the one shown in the Store or when the APPX package is opened with Windows 10 App Installer.

App.xaml

This file represents the application itself. It creates the app windows from the App.xaml.(x) as an instance that it's there all the time the app is running.

The file can declare default theme (light or dark) written in a simple markup text, and can reference the location of other application resources files and dictionaries, for example the AppStyles.xaml (that has the customizable XAML controls styles written in markup text).

The default file has the class, references and requested default theme.

<Application
    x:Class="_ProjectName_.App"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:_ProjectName_"
    RequestedTheme="Light">

</Application>

If App.xaml had referenced AppStyles.xaml, this markup text would have been written before 'Application' markup closing in order to specify new XAML controls styles.

    <Application.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>
                <ResourceDictionary Source="/AppStyles.xaml"/>
            </ResourceDictionary.MergedDictionaries>
        </ResourceDictionary>
    </Application.Resources>

App.xaml.(x)

This class is a single instance that is present when the app is running. It specifies the startup, suspension, and launching of the app for creating the application windows.

It is coded in the selected programming language for the UWP application project, so if Oxygene programming language is selected for the project, it will be called App.xaml.pas.

The file starts with the references. In the Oxygene variant of the file, reference collection begins with the 'uses' word.

namespace _ProjectName_;

interface

uses
  System,
  System.Collections.Generic,
  System.IO,
  System.Linq,
  System.Runtime.InteropServices.WindowsRuntime,
  Windows.ApplicationModel,
  Windows.ApplicationModel.Activation,
  Windows.Foundation,
  Windows.Foundation.Collections,
  Windows.UI.Xaml,
  Windows.UI.Xaml.Controls,
  Windows.UI.Xaml.Controls.Primitives,
  Windows.UI.Xaml.Data,
  Windows.UI.Xaml.Input,
  Windows.UI.Xaml.Media,
  Windows.UI.Xaml.Navigation;

Then goes the definition of the methods that will be used in the class (OnNavigationFailed, OnSuspending and OnLaunched).

type
  App = partial class(Application)
  private
    method OnNavigationFailed(sender: Object; e: NavigationFailedEventArgs);
    method OnSuspending(sender: Object; e: SuspendingEventArgs);
  protected
    method OnLaunched(e: LaunchActivatedEventArgs); override;
  public
    constructor;
  end;

implementation

constructor App;
begin
  self.InitializeComponent();
  self.Suspending += OnSuspending;
end;

Then the OnLaunched method is written, which makes a UI control called a Frame, that puts it into the window, and it tells the Frame to navigate to the MainPage. It can also customize titlebar and statusbar colors (defining ApplicationViewTitleBar and its colors after Window.Activate) or extend them into MainPage content (using CoreApplicationViewTitleBar and setting the ExtendViewIntoTitleBar to true).

method App.OnLaunched(e: LaunchActivatedEventArgs);
begin
  {$ifdef DEBUG}
  if System.Diagnostics.Debugger.IsAttached then begin
    self.DebugSettings.EnableFrameRateCounter := true;
  end;
  {$endif}
  var rootFrame: Frame := Frame(Window.Current.Content);
  if rootFrame = nil then begin
    rootFrame := new Frame();
    rootFrame.NavigationFailed += OnNavigationFailed;
    if e.PreviousExecutionState = ApplicationExecutionState.Terminated then begin
    end;
    Window.Current.Content := rootFrame;
  end;
  if rootFrame.Content = nil then begin
    rootFrame.Navigate(typeOf(MainPage), e.Arguments);
  end;
  Window.Current.Activate();
end;

After OnLaunched, goes OnNavigationFailed method, which states exceptions for a possible page failed navigation situation.

method App.OnNavigationFailed(sender: Object; e: NavigationFailedEventArgs);
begin
  raise new Exception('Failed to load Page ' + e.SourcePageType.FullName);
end;

And the last one is the OnSuspending method, that defines what happens when the app is suspended.

method App.OnSuspending(sender: Object; e: SuspendingEventArgs);
begin
  var deferral := e.SuspendingOperation.GetDeferral();
  deferral.Complete();
end;

end.

MainPage.xaml

This is the file that defines the UI for your app. Using XAML, elements can be added easily. Its code behind file, MainPage.xaml.(x) helps MainPage.xaml by adding app logic and event handlers.

The markup file defines where is the class, references, grids and the XAML controls content.

<Page
    x:Class="_ProjectName_.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:_ProjectName_"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d">

    <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
    </Grid>
</Page>

MainPage.xaml.(x)

This class has all the app logic and event handlers of the MainPage.

It is coded in the selected programming language for the UWP application project, so if Visual Basic programming language is selected for the project, it will be called MainPage.xaml.vb.

The file starts with the references. In the Visual Basic variant of the file, references begin with the 'Imports' word.

Imports System
Imports System.Collections.Generic
Imports Windows.UI.Core
Imports Windows.UI.Xaml
Imports Windows.UI.Xaml.Controls
Imports Windows.UI.Xaml.Data
Imports Windows.UI.Xaml.Media
Imports Windows.UI.Xaml.Navigation

Namespace Global._ProjectName_

Then the class defines 'InitializeComponent()', with the same use than the one in App.xaml.(x). And the app logic and event handlers are written before 'End Class' (where class ends).

Partial Public NotInheritable Class MainPage
        Inherits Page

        Public Shared Current As MainPage

        Public Sub New()
            Me.InitializeComponent()
            Current = Me
            SampleTitle.Text = FEATURE_NAME
        End Sub

End Class
End Namespace

Package.appxmanifest

This is the app manifest project file, which defines location for the assets, supported app orientations, package name, app name, supported capabilities, app certificate, app version, and the available tile images.

The manifest file starts with the main properties, which are the app version, developer name or organization name and publicly displayed information.

<?xml version="1.0" encoding="utf-8"?>
<Package xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10" xmlns:mp="http://schemas.microsoft.com/appx/2014/phone/manifest" xmlns:desktop4="http://schemas.microsoft.com/appx/manifest/desktop/windows10/4" xmlns:iot2="http://schemas.microsoft.com/appx/manifest/iot/windows10/2" xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10" IgnorableNamespaces="uap mp desktop4 iot2">
  <Identity Name="_Developer_._ProjectName_" Publisher="CN=_Developer_" Version="1.0.0.0" />
  <mp:PhoneIdentity PhoneProductId="x" PhonePublisherId="x" />
  <Properties>
    <DisplayName>_ProjectName_</DisplayName>
    <PublisherDisplayName>_Developer_</PublisherDisplayName>
    <Logo>Assets\StoreLogo.png</Logo>
  </Properties>

Then goes the dependency part, which references Dependency packages and versions and Target device families (Universal, Core, Desktop, Xbox, IoT, Holographic, Mobile) build numbers (versions), and the language part, which defines languages (e.g. English - United States is written like en-us).

  <Dependencies>
    <TargetDeviceFamily Name="Windows.Universal" MinVersion="10.0.x.0" MaxVersionTested="10.0.x.0" />
    <TargetDeviceFamily Name="Windows.Core" MinVersion="10.0.x.0" MaxVersionTested="10.0.x.0" />

  </Dependencies>
  <Resources>
    <Resource Language="x-generate" />
  </Resources>

After that, the 'Applications' properties are set, with the name, visual assets location and app orientations.

  <Applications>
    <Application Id="App" Executable="$targetnametoken$.exe" EntryPoint="_ProjectName_.App" desktop4:SupportsMultipleInstances="true" iot2:SupportsMultipleInstances="true">
      <uap:VisualElements DisplayName="_ProjectName_" Square150x150Logo="Assets\Square150x150Logo.png" Square44x44Logo="Assets\Square44x44Logo.png" Description="_ProjectDescription_" BackgroundColor="lightGray">
        <uap:DefaultTile Wide310x150Logo="Assets\Wide310x150Logo.png">
        </uap:DefaultTile>
        <uap:SplashScreen Image="Assets\SplashScreen.png" BackgroundColor="lightGray" />
        <uap:InitialRotationPreference>
          <uap:Rotation Preference="portrait" />
          <uap:Rotation Preference="landscape" />
          <uap:Rotation Preference="portraitFlipped" />
          <uap:Rotation Preference="landscapeFlipped" />
        </uap:InitialRotationPreference>
      </uap:VisualElements>
    </Application>
  </Applications>

To enable the extensions for windows.protocol category which configures the launching URIs of the app, this markup code needs to be added before 'Application' closing. Manifest also supports file extension association thanks to windows.fileTypeAssociation category.

          <Extensions>
                <uap:Extension Category="windows.protocol">
                  <uap:Protocol Name="prtcl">
                    <uap:Logo>Assets\StoreLogo.png</uap:Logo>
                    <uap:DisplayName>_ProtocolSample_</uap:DisplayName>
                  </uap:Protocol>
                </uap:Extension>
                <uap:Extension Category="windows.fileTypeAssociation">
          <uap:FileTypeAssociation Name="flxts">
            <uap:Logo>Assets\StoreLogo.png</uap:Logo>
            <uap:SupportedFileTypes>
              <uap:FileType>.flxts</uap:FileType>
            </uap:SupportedFileTypes>
          </uap:FileTypeAssociation>
                </uap:Extension>
          </Extensions>

And the last one is the Capabilities category, which declares used OS capabilities like internetClient, Music or Webcam.

  <Capabilities>
    <Capability Name="internetClient" />
  </Capabilities>
</Package>

Project.json

This file has the dependencies list, the app used framework and the runtimes list.

The file begins with the dependencies list. Universal Windows Platform is the default dependency.

{
"dependencies": {
"Microsoft.NETCore.UniversalWindowsPlatform": "5.1.0"
},

Then there's the used framework of the project.

"frameworks": {
"uap10.0": {}
},

And finally the runtimes list of the project.

"runtimes": {
"win10-arm": {},
"win10-arm-aot": {},
"win10-x86": {},
"win10-x86-aot": {},
"win10-x64": {},
"win10-x64-aot": {}
}
}

Project.lock.json

This file has the locked status, version number and targets of the app compiling.

The file is basically this, but the project includes, where the 'content' placeholder is, the complete information of the UAP.

{
"locked": false,
"version": 2,
"targets": {
"UAP,Version=v10.0": {
_content_
}
}
}

AppStyles.xaml

This markup file is the one that freely customizes XAML controls styles. When it's referenced from the App.xaml file, it just works as it should for all the controls defined in the XAML pages.

The file begins with the ResourceDictionary category, which is the one that has the styles.

<ResourceDictionary
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:_ProjectName_">

And then the styles are created.

    <Style x:Key="_ControlSample_" TargetType="_TargetSample_">
        <Setter Property="Background" Value="Transparent"/>
    </Style>

</ResourceDictionary>

(ProjectName)_TemporaryKey.pfx

This certificate file is the one which signs temporarily the app project. When a project doesn't have this file, it can be generated by the package.appxmanifest file project. It defines the Organization or Developer name of the app and the package name for trust certification when the app is installed.

ProjectName.(x)

Is the project file, which has the target properties, SDK versions, target compiling, references and other project properties.

The file extension changes depending on the programming language project. For example, a C# project will have .csproj file extension.

ProjectName.sln

This file is the Visual Studio solution file that references the projects included in the same solution and the main project for building/compiling.

All the UWP projects are defined inside a solution (.sln) file, so in Visual Studio the project is shown like a subfolder inside the solution folder.

Clone this wiki locally