.XAML File Format – Namespaces and mapping

The declaration and its scope

• xmlns="URI" sets the namespace of every element with no prefix, in the element that holds the declaration and everything inside it.
• xmlns:name="URI" declares the prefix name; name:Element is then an element of that namespace.
• A declaration holds for the element and its descendants, and an inner one hides an outer one. Declare namespaces on the root unless a file merges parts written elsewhere.
• The default namespace does not apply to attributes. An attribute with no prefix is in no namespace and names a property or event of the element’s type; an attribute with a prefix (x:Name, local:Tools.Tag, mc:Ignorable) is in that namespace.
• A prefix that is used and not declared is an error (the XML reader reports it as an unbound prefix). A declaration that is never used is legal.
• Prefix names are free; the ones in the table below are the conventions the project templates write. The xml and xmlns prefixes are reserved.

How a namespace becomes types

The URI is a name, not an address, and nothing is fetched. A framework that reads XAML keeps a table from namespace URIs to .NET namespaces in assemblies. There are two ways a URI gets into the table.

Assembly attributes: XmlnsDefinition and XmlnsPrefix

An assembly can state that a URI stands for one or more of its CLR namespaces with [assembly: XmlnsDefinition("http://schemas.microsoft.com/winfx/2006/xaml/presentation", "System.Windows.Controls")]. Several attributes, in several assemblies, may name the same URI, and then the URI covers all of those CLR namespaces: this is how one URI, the presentation namespace, covers System.Windows, System.Windows.Controls, System.Windows.Media, System.Windows.Shapes, System.Windows.Documents and the rest of WPF. A third party library does the same to give its controls one URI (the table lists a few). XmlnsPrefix suggests the prefix a tool should write for it. XmlnsCompatibleWith says that a URI is an older name of another. In Avalonia, .NET MAUI and WinUI the attributes have the same names or close ones.

CLR namespace mappings

The other way is to write the CLR namespace in the declaration, so that no attribute is needed.

Only the forms above are mapping syntax. A namespace URI that starts with clr-namespace but has a stray part (clr-namespace:A;B), no namespace name, or an empty assembly= is a mistake, and the viewer reports it. A generic type is not written in the mapping but in the element: <local:Box x:TypeArguments="sys:Int32"/> (language namespace).

<UserControl xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             xmlns:sys="clr-namespace:System;assembly=mscorlib"
             xmlns:models="clr-namespace:Demo.Models;assembly=Demo"
             xmlns:vm="clr-namespace:Demo.ViewModels">
  <UserControl.Resources>
    <sys:String x:Key="Caption">Customers</sys:String>
    <DataTemplate DataType="{x:Type models:Customer}">…</DataTemplate>
  </UserControl.Resources>
</UserControl>

Markup compatibility and design-time namespaces

The Markup Compatibility namespace http://schemas.openxmlformats.org/markup-compatibility/2006 (prefix mc) comes from Open Packaging and Office Open XML, and XAML readers apply it before they read anything else. Its attributes and elements:

• mc:Ignorable="prefix1 prefix2" on an element lists namespace prefixes whose elements and attributes a reader that does not understand them must skip. A prefix named here must be declared (the viewer reports one that is not).
• mc:ProcessContent="Element1 Element2" says that the content of an ignored element is still read.
• mc:MustUnderstand="prefix" says that a reader that does not understand the namespace must fail.
• mc:AlternateContent with mc:Choice Requires="prefix" and mc:Fallback picks the first choice whose required namespaces the reader understands; WPF uses it to write markup for newer versions that older ones can skip.

The design-time namespace http://schemas.microsoft.com/expression/blend/2008 (prefix d), listed in mc:Ignorable="d", holds attributes that only designers read: d:DesignWidth, d:DesignHeight, d:DataContext="{d:DesignInstance Type=vm:Main, IsDesignTimeCreatable=True}", d:DesignData, d:Source, d:Background, d:IsHidden, d:LayoutOverrides and d:IsDataSource. A running application skips them. MAUI and Xamarin.Forms have design-time namespaces of their own (http://schemas.microsoft.com/dotnet/2021/maui/design and http://xamarin.com/schemas/2014/forms/design) that are used the same way. Avalonia’s designer reads the d: namespace of Blend.

The well-known namespaces

The viewer’s Namespaces tab labels these when it finds them and shows any other URI as “not a mapping this viewer knows”, which is not a problem: the namespace of any library is a name its authors chose.

Not described

Known, not yet covered

• Reference: the list of third-party URIs is a sample of the common ones, not a register; there is no complete list.
• Reference: how each framework resolves the using: and clr-namespace: forms (which assemblies it searches) was not tested; the page states the forms and what the templates write.
• Reference: XmlnsDefinition and its relatives are described from the WPF documentation; the equivalents of MAUI and Avalonia were not read in their source.

Unknown

• Reference: whether MAUI accepts using: in every version.