Avalonia XAML

Avalonia UI uses XAML to define a user interface. XAML is an XML-based mark-up language that is used by many UI frameworks.

info

These pages will introduce you to how XAML is used specifically in Avalonia UI. For background information about how XAML is used elsewhere in Microsoft technologies, you can use these references:

• Microsoft XAML documentation for WPF, see here.
• Microsoft XAML documentation for UWP, see here.

AXAML File Extension

The file extension for XAML files used elsewhere is .xaml but due to technical issues integrating with Visual Studio, Avalonia UI uses its own .axaml extension - 'Avalonia XAML'.

info

From Avalonia UI version 0.9.11 all XAML files created in Visual Studio have the .axaml extension; and from version 0.10 all Avalonia UI templates create files using the .axaml extension.

File Format

A typical Avalonia XAML file looks like this:

<Window xmlns="https://github.com/avaloniaui"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        x:Class="AvaloniaApplication1.MainWindow">
</Window>

In common with all XML files, there is a root element. The root element tag <Window></Window> defines the type of the root. This will correspond to a type of Avalonia UI control, in the above example a window.

The sample above uses three interesting attributes:

• xmlns="https://github.com/avaloniaui" - this is the XAML namespace declaration for Avalonia UI itself. This is required, without it the file will not be recognised as an Avalonia XAML document.
• xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" - this is the declaration for the XAML language namespace.
• x:Class="AvaloniaApplication1.MainWindow" - this is an extension of the above declaration (for 'x') that tells the XAML compiler where to find the associated class for this file. The class is defined in a code-behind file, usually written in C#.

info

For information about the code-behind concept, see here.

Control Elements

You can compose a UI for your application by adding XML elements that represent one of the Avalonia UI controls. The element tag uses the same name as the control class name.

info

A UI can be composed of several different types of control. To learn more about the concept of UI composition, see here.

For example, this XAML adds a button to the content of a window:

<Window xmlns="https://github.com/avaloniaui"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <Button>Hello World!</Button>
</Window>

info

For a complete list of the Avalonia UI built-in controls, see the reference here.

Control Attributes

The XML elements that represent controls have attributes corresponding to control properties that can be set. You can set a control property by adding an attribute to an element.

For example, to specify a blue background for a button control, you add the Background attribute set the value to "Blue". Like this:

<Window xmlns="https://github.com/avaloniaui"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <Button Background="Blue">Hello World!</Button>
</Window>

Control Content

You might have noticed that the button in the above sample has its content (the 'Hello World' string) placed between its opening and closing tags. As an alternative, you can set the content attribute, as follows:

<Window xmlns="https://github.com/avaloniaui"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <Button Content="Hello World!"/>
</Window>

This behaviour is specific to the content of an Avalonia UI control.

Data Binding

You will often use the Avalonia UI binding system to link a control property to an underlying object. The link is declared using the {Binding} mark-up extension. For example:

<Window xmlns="https://github.com/avaloniaui"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <Button Content="{Binding Greeting}"/>
</Window>

info

For further information about the concept behind data binding, see here.

Code-behind Files

Many XAML files also have an associated code-behind file that is usually written in C#, and has the file extension .xaml.cs.

info

For guidance about programming using code-behind files, see here.

XML Namespaces

In common with any XML format, in Avalonia XAML files you can declare namespaces. This allows the XML processor to find the definitions of the elements in the file.

info

For background information, see the Microsoft XML namespaces documentation here.

You can add a namespace using the xmlns attribute. The format of a namespace declaration is as follows:

xmlns:alias="definition"

It is standard practice to define all the namespaces you are going to use in the root element.

Only one namespace in a file can be defined without using the alias part of the attribute name. The alias must always be unique with in a file.

The definition part of the namespace declaration can be either a URL or a code definition. Both of these are used to locate the definition of the elements in the file.

info

For detailed guidance on how namespace declarations work, see here.

There are two valid syntax options for the definition part of a XAML namespace attribute that references code:

CLR Namespace Prefix

There is a prefix clr-namespace: you can use to reference both code in the current assembly and code in a referenced assembly.

For example, when the code is present in the same assembly as the XAML, you can use this syntax:

<Window ...
    xmlns:myAlias1="clr-namespace:MyNamespace.AppNameSpace.UI" 
... >

And if the code is in another referenced assembly (for example in a library), you must extend the description to include the name of the referenced assembly:

<Window ...
    xmlns:myAlias2="clr-namespace:MyNameSpace.OtherAssembly;assembly=OtherAssembly"
 ... >

Using Prefix

There is an alternative prefix using: that you can use to reference code in the current assembly. For example:

xmlns:myAlias3="using:MyNamespace.AppNameSpace.UI"