.XAML File Format

Introduction

XAML (Extensible Application Markup Language, said “zammel”) is an XML language for describing a tree of .NET objects. Each element names a type and makes an instance of it, each attribute sets a property or connects an event to a method, and an element inside another element is a value of a property of its parent or an item of its collection. Most XAML describes a user interface: WPF (Windows Presentation Foundation), UWP, WinUI, Silverlight, Windows Phone, Xamarin.Forms, .NET MAUI, the Uno Platform and Avalonia all read it, and so do Windows Workflow Foundation (which describes programs as activities) and tools that save objects as markup. The language itself, the part that decides what an element and an attribute mean, is the same in all of them; what differs is the vocabulary, the types of each framework.

A file is an XML document. Its root element names the kind of thing described (Window, Page, UserControl, Application, ResourceDictionary, ContentPage, Activity) and declares the XML namespaces that say where the types come from: one namespace for the framework as the default, one for the XAML language itself (usually written x:), and others that map a prefix to a .NET namespace in the application. The attribute x:Class on the root joins the markup to a class written in C#, Visual Basic or F# (the code-behind).

<Window x:Class="Demo.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:local="clr-namespace:Demo"
        Title="{Binding Title}" Width="320" Height="200">
  <Window.Resources>
    <SolidColorBrush x:Key="Accent" Color="#FF2D6CDF"/>
  </Window.Resources>
  <StackPanel Margin="12">
    <TextBlock Text="Hello" Foreground="{StaticResource Accent}"/>
    <Button x:Name="Go" Click="Go_Click" Content="Go"/>
  </StackPanel>
</Window>

A XAML reader works in three steps. It reads the XML, turning each element and attribute into a name in a namespace. It resolves each name to a type or member: Button in the presentation namespace is System.Windows.Controls.Button, local:Thing is Demo.Thing, Grid.Row is an attached property. Then it builds the objects, converting each attribute string to the type of its property by a type converter or a markup extension (the text in curly braces). A build tool can instead compile the file ahead of time: WPF turns it into a compact binary form (BAML) and a generated class, and UWP, WinUI, MAUI and Avalonia generate code or a binary form as well. See compilation, code-behind and BAML.

Nothing is drawn by the file. A XAML file says what objects exist and how they are connected; layout, drawing, data binding and animation are done by the framework that loads it.

The kinds of file

How the viewer reads each file

A file is read as XAML when its root element declares a XAML namespace: the presentation namespace of WPF, UWP, WinUI and Silverlight, those of Avalonia, .NET MAUI, Xamarin.Forms and Workflow Foundation, or the XAML language namespace. A .xaml, .axaml or .xamlx file that declares none of them is shown as plain XML, as any XML file is. Nothing is rendered and nothing is evaluated: the viewer has the file, not the assemblies that define its types, so a type or a property it does not know is shown, never judged.

The XAML problems are: a namespace prefix that is not declared (on an element, an attribute, a markup extension, a TargetType, an x:Type, an x:Static or mc:Ignorable); a malformed or unclosed markup extension, an unmatched brace, a quote that is not closed, text after the closing brace, an empty argument, a positional argument after a named one, an argument given twice; a known extension with the wrong number of arguments or, for the WPF and UWP Binding, a property it does not have; a duplicate x:Name in a name scope or x:Key in a dictionary (implied keys included); a resource with no key; x:Class off the root or not a class name; an x:Name that is not a XAML name; a property element inside another property element, with attributes, set twice or also set as an attribute; a bad clr-namespace or using: mapping. A file larger than 24 MiB is read by the XML viewer, which works in windows.

The pages

• File structure and conventions – the document, the root elements, file names, encodings and white space
• Object elements, properties and events – object, attribute and property element syntax, content properties, collections, type converters, attached properties and events
• Namespaces and mapping – xmlns, clr-namespace, using:, assembly attributes and the well-known URIs
• The XAML language namespace – every x: directive and type
• Markup extensions – the syntax of {…} and every extension of each framework
• Resources, styles and templates – dictionaries, keys, lookup, merging, styles, templates, triggers, visual states and name scopes
• Data binding – Binding, x:Bind, relative sources, converters, modes and validation
• Elements: controls, panels and layout – the root types and the core elements of WPF with their main properties and events
• Brushes, shapes, transforms and animation – colours, brushes, shapes, geometry strings, transforms, effects, storyboards and key frames
• Frameworks and versions – WPF, Silverlight, UWP, WinUI, MAUI, Xamarin.Forms, Avalonia and Workflow Foundation, and what differs between them
• Compilation, code-behind and BAML – build actions, generated classes, InitializeComponent and the binary form
• Tooling – the XAML services of .NET, designers, previewers and the other tools

Not described

Known, not yet covered

• Reference: the vocabulary of each framework is its type library, far larger than any page. The pages give the language in full and, for the elements, the root types and the core controls, panels, brushes, shapes, transforms, animations, binding and resource types of WPF with their main properties; WinUI, MAUI and Avalonia are covered by what differs from WPF, not type by type.
• Reference: the binary BAML format is named and its place in the build is described, but its record layout is not. The format is documented by the source of WPF and by decompilers, and was not read in full here.
• Reference: Windows Workflow Foundation XAML is described by its document shape and namespaces, not activity by activity.
• Viewer: event handlers are found by the attribute’s name against a list of the event names of WPF, UWP, WinUI, MAUI and Avalonia. Without the assemblies the viewer cannot see the real events of a type, so an event that is not on the list is shown as an ordinary attribute, and a property whose name is on the list but whose value is a name is shown as a handler.
• Viewer: property and type names are not checked against the framework, because the types are not in the file. The unknown-property check applies only to the properties of Binding, x:Bind, RelativeSource and ComponentResourceKey.
• Viewer: a .baml file is not read, and the user interface is not drawn.
• Viewer: a file over 24 MiB gets the XML viewer, without the XAML tabs.

Unknown

• Reference: no .NET SDK, WPF runtime or Avalonia build is installed on this Mac, so no example here was loaded by a real XAML reader; the examples follow the documentation and the language specification (MS-XAML), and the checks of the viewer were run against the files found on this Mac.

Links