A XAML file is one XML 1.0 document with one root element. Everything XML allows is allowed (comments, CDATA sections, processing instructions, character references), and XAML adds meaning to the names, to the attributes and to the white space. This page covers the file as a whole; the elements and attributes are on the syntax page.
The document
- Declaration.
<?xml version="1.0" encoding="utf-8"?>is allowed and usually left out by tools that write XAML; without it the encoding is UTF-8 or UTF-16 by the byte order mark, as in any XML file. - Root element. exactly one. It is an object element (never a property element), it declares the namespaces the document uses, and it may carry
x:Class,x:ClassModifier,x:Subclassandx:TypeArguments, which only the root may have. - Comments.
<!-- … -->as in XML. A comment may not contain--. Comments inside a start tag are not allowed. - Document type. a document type declaration is legal XML, but XAML defines no use for one; the viewer shows it as XML.
- Case. names are case sensitive:
Button,buttonandBUTTONare different names, and only the first is a WPF type. - Line endings. any of CR LF, LF or CR; the XML reader normalises them to LF.
Root elements
The root names the kind of thing the file defines. What follows is a list of the roots the frameworks themselves use; any type with a parameterless constructor, in any assembly the namespaces reach, can be a root of a loose file.
| Framework | Roots | Role |
|---|---|---|
| WPF | Window, NavigationWindow | a top-level window; NavigationWindow hosts pages with a navigation bar |
| WPF | Page, PageFunction | a page shown in a frame, a navigation window or a browser; PageFunction<T> (written with x:TypeArguments) is a page that returns a value |
| WPF | UserControl | a reusable composite control |
| WPF | Application | the application definition, normally App.xaml: start-up, application resources, StartupUri |
| WPF | ResourceDictionary | a file of resources, merged by Source |
| WPF | FlowDocument, FixedDocument, FixedPage | documents |
| WPF | any element (Grid, Canvas, Style, ControlTemplate, Storyboard) | a loose file that XamlReader.Load reads; a root that is not a page or window cannot have x:Class unless markup-compiled |
| UWP, WinUI | Page, UserControl, Application, ResourceDictionary, ContentDialog, Window (WinUI 3) | as in WPF |
| Silverlight | UserControl, Application, navigation:Page, ResourceDictionary | as in WPF; the root of a 1.0 file is Canvas |
| .NET MAUI, Xamarin.Forms | ContentPage, ContentView, Shell, FlyoutPage, TabbedPage, NavigationPage, CarouselPage, Application, ResourceDictionary | pages, views, the app and its resources |
| Avalonia | Window, UserControl, Application, Styles, ResourceDictionary, ControlTheme | as in WPF; Styles is a file of styles |
| Workflow Foundation | Activity, Sequence, Flowchart, StateMachine, WorkflowService | a workflow (a program), see Frameworks and versions |
File names, build actions and the generated files
| File | Meaning |
|---|---|
App.xaml | the application definition; its build action is ApplicationDefinition (Page in UWP and MAUI projects), and its root is Application |
MainWindow.xaml, Page1.xaml, MyControl.xaml | a window, page or control; the build action is Page, which compiles it with its code-behind |
X.xaml.cs, X.xaml.vb, X.xaml.fs | the code-behind of X.xaml: a partial class named by x:Class with a call to InitializeComponent() and the event handlers; Avalonia uses X.axaml.cs |
X.g.cs, X.g.i.cs (and .g.vb) | the generated half of the class, in the project’s obj folder: InitializeComponent, the field of each x:Name element and the wiring of the events; the .g.i.cs file is the version the designer builds |
X.baml | the compiled markup of X.xaml, embedded in the program’s resources as x.baml (WPF only) |
Themes/Generic.xaml | the default styles of the custom controls of an assembly (a build action of Page, found by the theme lookup); Themes/Aero2.NormalColor.xaml, Aero.NormalColor.xaml, Luna.NormalColor.xaml, Luna.Homestead.xaml, Luna.Metallic.xaml, Royale.NormalColor.xaml and Classic.xaml are the per-theme ones (WPF) |
| a resource dictionary file | any name; merged by <ResourceDictionary Source="Styles/Buttons.xaml"/> or by a pack:// address, see Resources |
.xaml as content | a file whose build action is Content or None, loaded by XamlReader.Load at run time (loose XAML); it has no code-behind and cannot name event handlers |
.xbap | a XAML browser application manifest (WPF browser applications); the markup is in pages inside the package |
The markup compiler reads x:Class to name the class and the root element to name its base class, so the generated half is the equivalent of partial class MainWindow : Window. It reads every x:Name and makes a field for it (private unless x:FieldModifier says otherwise, see the language namespace page) and every event attribute to make a connection to the method of that name in the code-behind. The method named by an event attribute must exist in the code-behind class with the signature of the event.
Encoding
UTF-8 is the usual encoding, written with or without a byte order mark; Visual Studio writes a byte order mark for files it creates. UTF-16 with a byte order mark and any encoding named in the XML declaration that the platform’s XML reader supports can be read. A character the encoding cannot hold is written as a character reference (€). The five predefined entities (< > & " ') and numeric character references are the entities a XAML file uses; any other entity name would need a document type declaration, and XAML defines no use for one.
White space
White space characters are space, line feed and tab. The rules apply to the text inside elements, not to the gaps between attributes and not to the white space between elements that hold only elements.
- Line feeds between East Asian characters (the ranges U+20000 to U+2FFFD and U+30000 to U+3FFFD) are removed.
- Every white space character becomes a space.
- Runs of spaces become one space.
- A space right after a start tag, and one right before an end tag, is removed.
These rules are the default, the state of xml:space="default". Where the text is kept as it is, xml:space="preserve" on the element switches the normalisation off for that element and what is inside it. Even then, a content model that does not treat white space as significant (a ListBox, a Grid) ignores it; only collections marked as white space significant keep it, in WPF the inline collection of a TextBlock or Paragraph. A line break element (LineBreak) does not add a leading space to the text after it.   is a non-breaking space and is never normalised.
How the inner text then becomes a value depends on the property: a property of a type with a type converter gets the converter’s result; a property of type Object gets a string; a collection that takes strings gets the text as a string item, with elements and text alternating as separate items. A { at the start of the text of a property element starts a markup extension; {} at the start escapes it.
Other XAML file forms
- AXAML. Avalonia’s files use
.axamlso that an IDE can offer the Avalonia vocabulary instead of WPF’s; the content is XAML withxmlns="https://github.com/avaloniaui". Avalonia also loads.xaml. - XAMLX. a Windows Workflow Foundation service for WCF: a
WorkflowServiceroot withReceiveandSendReplyactivities. - XOML. the workflow markup of Windows Workflow Foundation 3 (
.xoml); this site’s viewer does not register the extension, but a file with that namespace opened by name as XAML is read like any other. - Rule files. the property page definitions of MSBuild SDKs (
Rules/*.xamlwith aRuleroot in the namespacehttp://schemas.microsoft.com/build/2009/properties) are XAML read by Visual Studio’s project system. - Composite fonts. a
.xamlfile in the namespacehttp://schemas.microsoft.com/winfx/2006/xaml/composite-fontdescribes a font made of several (WPF).
Not described
Known, not yet covered
- Reference: the exact build actions and generated file names differ between WPF, UWP, WinUI, MAUI and Avalonia and between SDK versions; only the WPF and generic names above were checked against Microsoft’s documentation.
- Reference: the XAML browser application (
.xbap) package and the XAML Islands hosting are named, not described.
Unknown
- Reference: which encodings every framework’s XML reader accepts for a file with a declaration was not tested; none of the frameworks is installed on this Mac.