The XAML syntax terminology defined here is also defined or referenced within the XAML language specification. XAML is a language based on XML and follows XML structural rules. Some of the terminology is shared from or is based on the terminology commonly used when describing the XML language or the XML Document Object Model (DOM).

Object element syntax is the XAML markup syntax that instantiates a common language runtime (CLR) class or structure by declaring an XML element. This syntax resembles the element syntax of other markup languages such as HTML. Object element syntax begins with a left angle bracket (<), followed immediately by the type name of the class or structure being instantiated. Zero or more spaces can follow the type name, and zero or more attributes may also be declared on the object element, with one or more spaces separating each attribute name="value" pair. Finally, one of the following must be true:

• The element and tag must be closed by a forward slash (/) followed immediately by a right angle bracket (>).

• The opening tag must be completed by a right angle bracket (>). Other object elements, property elements, or inner text, can follow the opening tag. Exactly what content may be contained here is typically constrained by the object model of the element; see "Content Syntax" section in this topic. The equivalent closing tag for the object element must also exist, in proper nesting and balance with other opening and closing tag pairs.

For example, the following example is object element syntax that instantiates a new instance of the Button class, and also specifies a Name attribute and a value for that attribute:

<Button Name="CheckoutButton"/>

The following example is object element syntax that also includes Extensible Application Markup Language (XAML) content property syntax. The inner text contained within will be used to set the TextBox Extensible Application Markup Language (XAML) content property, Text.

<TextBox>This is a Text Box</TextBox>

Attribute syntax is the XAML markup syntax that sets a value for a property, or names an event handler for an event, by declaring an attribute on an element. The element is always declared through object element syntax. The attribute name must match the CLR member name of either a property or an event. The attribute name is followed by an assignment operator (=). The attribute value must be a string enclosed within two quotation marks (").

In order to be set through attribute syntax, a property must be public, must be read-write, and must have a property value type that can be instantiated or referenced by a XAML processor. For events, the event must be public and have a public delegate. The property or event must be a member of the class or structure that is instantiated by the containing object element.

The attribute value is filled by one of the following, using this processing order:

1. If the XAML processor encounters a curly brace, or an object element that derives from MarkupExtension, then the referenced markup extension is evaluated first rather than processing as a string, and the object returned by the markup extension is used. In many cases the object returned by a markup extension will be a reference to an existing object, or an expression that defers evaluation until run time, and is not a new object.

2. If the property is declared with a designated TypeConverter, or the value type of that property is declared with an attributed TypeConverter, the string value of the attribute is submitted to the type converter as a conversion input, and the converter will return a new object instance.

3. If there is no TypeConverter, a direct conversion to the property type is attempted. This final level is a direct conversion between primitive types, or a check for names in an enumeration (which return the matching values).

For example, using the same markup as previously shown, the following example is the attribute syntax used to assign a string value for the Name property:

<Button Name="CheckoutButton"/>

The Name property is a member of the members table for the Button class. Button is a derived class of FrameworkElement class that defines Name.

Processing of Attribute Values

<!--This will not compile, because Visibility is not a flagwise enumeration.-->
...
<Trigger Property="Visibility" Value="Collapsed,Hidden">
  <Setter ... />
</Trigger>
...

Property and Event Member Name References

Property element syntax is a syntax that diverges somewhat from the basic XML syntax. In XML, the value of an attribute is a de facto string, with the only possible variation being which string encoding format is being used. In XAML, you can assign other object elements to be the value of a property. This capability is enabled by the property element syntax. Instead of the property being specified as an attribute within the element tag, the property is specified using an opening element tag in elementTypeName.propertyName form, the value of the property is specified, and then the property element is closed.

Specifically, the syntax begins with a left angle bracket (<), followed immediately by the type name of the class or structure that the property element syntax is contained within. This is followed immediately by a single dot (.), then by the name of a property that must exist within the members table of the specified type, then by a right angle bracket (>). The value to be assigned to the property is contained within the property element. Typically, the value is given as one or more object elements, because specifying objects as values is the scenario that property element syntax is intended to address. Finally, an equivalent closing tag specifying the same elementTypeName.propertyName combination must be provided, in proper nesting and balance with other element tags. For example, the following is property element syntax for the ContextMenu property of a Button.

<Button>
  <Button.ContextMenu>
    <ContextMenu>
      <MenuItem Header="1">First item</MenuItem>
      <MenuItem Header="2">Second item</MenuItem>
    </ContextMenu>
  </Button.ContextMenu>
  Right-click me!</Button>

The value within a property element can also be given as inner text, in cases where the property type being specified is a primitive value type, such as String, or enumeration where a name is specified. These two usages are uncommon, because each of these cases also supports attribute syntax. One scenario for filling a property element with a string is for properties that are not the XAML content property but still are used for representation of UI text, and particular whitespace elements such as linefeeds are required to appear in that UI text. Attribute syntax cannot preserve linefeeds, but property element syntax can, so long as significant whitespace preservation is active (for details, see Whitespace Processing in XAML).

A property element is not represented in the logical tree. A property element is just a particular syntax for setting a property, and is not an element that has an instance or object backing it.

Property Element Syntax for Collection Types

The XAML specification requires XAML processor implementations to be able to identify properties where the value type is a collection. The WPF implementation is based on managed code, and its XAML processor identifies collection types through one of the following:

• Implements IList.

• Implements IDictionary.

• Derives from Array (for more information about arrays in XAML, see x:Array Markup Extension.)

If the type of a property is a collection, then the inferred collection type does not need to be specified in the markup. Instead, the elements that are intended to become the items in the collection are specified as one or more child elements of the collection type property element. Each such item is evaluated to an object during loading and added to the collection by calling the Add method of the implicit collection. For example, the Triggers property of Style takes the specialized collection type TriggerCollection. But it is not necessary to instantiate a TriggerCollection in the markup. Instead, you specify one or more Trigger items as elements within the Style.Triggers property element, where Trigger (or a derived class) is the type expected as the item type for the strongly typed and implicit TriggerCollection.

C#

<Style x:Key="SpecialButton" TargetType="{x:Type Button}">
  <Style.Triggers>
    <Trigger Property="Button.IsMouseOver" Value="true">
      <Setter Property = "Background" Value="Red"/>
    </Trigger>
    <Trigger Property="Button.IsPressed" Value="true">
      <Setter Property = "Foreground" Value="Green"/>
    </Trigger>
  </Style.Triggers>
</Style>

A property may be both a collection type and the XAML content property for that type and derived types.

An implicit collection element creates a member in the logical tree, even though it does not appear in the markup as an element. Usually the constructor of the owning type performs the instantiation for the collection that is one of its properties, which adds the collection to the tree.

Note:
The generic list and dictionary interfaces ( IList<(Of <(T>)>) and IDictionary<(Of <(TKey, TValue>)>)) are not supported for collection detection by the WPF XAML processor. However, you can use the List<(Of <(T>)>) class as a base class, because it implements IList directly, or Dictionary<(Of <(TKey, TValue>)>) as a base class, because it implements IDictionary directly.

XAML content syntax is a syntax that is only enabled on classes that specify the ContentPropertyAttribute as part of their class declaration. The ContentPropertyAttribute requires a parameter that specifies the property by name that is defined to be the content property for that type of element (including derived classes). The property thus designated is the XAML content property of an element. When processed by a XAML processor, any child elements or inner text that are found between the opening and closing tags of the element will be assigned to be the value of that XAML content property. You are permitted to specify property elements for the content property if you wish and make its markup explicit. This technique has occasional value for markup clarity or as a matter of markup style, but usually the intent of a content property is to streamline the markup so that elements that are intuitively related as parent-child can be nested directly. Property element tags for other properties on an element are not assigned as "content"; they are processed previously in the parser workflow and are not considered to be "content".

As with any other property, the XAML content property of an object will be of a specific type. That type can be the Object type. The type of that content property helps define the content model of an object. For instance, a type of Object is loose in the sense that any object may become the content, but even this loose typing entails that the content must be a single object. The single object might be a collection object, but even so there can be only one such collection object assigned to be the content.

In the WPF documentation, content models for particular types are described on the class pages for that type, or are written as separate conceptual topics for families of types and are linked to from each relevant type reference.

Content Syntax for Collection Types

<Page
  xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
  >
  <StackPanel>
    <Button>Button 1</Button>
    <Button>Button 2</Button>
    <Button>Button 3</Button>
  </StackPanel>
</Page>

Mixing Property Elements and Object Elements in an Object with a Content Property

Attached properties are a programming concept introduced in XAML whereby properties can be owned and defined by a type, but set on any element. The primary scenario that attached properties are intended for is to enable child elements in an element tree to report information to a parent element without requiring an extensively shared object model across all elements. Conversely, attached properties can be used by parent elements to report information to child elements. For more information on the purpose of attached properties and how to create your own attached properties, see Attached Properties Overview.

Attached properties use a syntax that superficially resembles property element syntax, in that you also specify a typeName.propertyName combination. There are two important differences:

• You can use the typeName.propertyName combination even when setting an attached property through attribute syntax. Attached properties are the only case where qualifying the property name is a requirement in an attribute syntax.

• You can also use property element syntax for attached properties. However, for typical property element syntax, the typeName you specify is the object element that contains the property element. If you are referring to an attached property, then the typeName is the class that defines the attached property, not the containing object element.

Attached events are another programming concept introduced in XAML where events can be defined by a type, but handlers may be attached on any object. Often the type that defines an attached event is a static type that defines a service, and sometimes those attached events are exposed by a routed event alias in types that expose the service. Handlers for attached events are specified through attribute syntax. As with attached events, the attribute syntax is expanded for attached events to allow a typeName.eventName usage, where typeName is the class that provides Add and Remove event handler accessors for the attached event infrastructure, and eventName is the event name.

None of the preceding syntax examples specified a namespace other than the default namespace. In typical WPF applications the default namespace is specified to be the WPF namespace. You can specify namespaces other than the default namespace and still use essentially the same kinds of syntax, but anywhere where a class is named that is not accessible within the default namespace, that class name must be preceded with the prefix of the XML namespace that was used to map the corresponding CLR namespace. For instance, <custom:MyElement/> is object element syntax to instantiate an instance of the MyElement class, where the CLR namespace containing that class (and possibly the external assembly that contains that namespace) was previously mapped to the custom prefix.

For more information about XML namespaces and XAML, see XAML Namespaces and Namespace Mapping.

XAML defines a markup extension programming entity that enables an escape from the normal XAML processor handling of attributes or object elements, and defers the processing to a backing class. The WPF implementation of a XAML processor uses the MarkupExtension abstract class as the basis for all of the markup extensions supported by WPF. The character that identifies a markup extension to a XAML processor when using attribute syntax is the opening curly brace ({), followed by any character other than a closing curly brace (}). The first string following the opening curly brace must reference the class that provides the particular extension behavior, where the reference may omit the substring "Extension" if that substring is part of the true class name. Thereafter, a single space may appear, and then each succeeding character is used as input by the extension implementation, up until the closing curly brace is encountered. The markup extensions in WPF are intended primarily to provide a means to reference other already-existing objects, or deferred references to objects that will be evaluated at run time, while using attribute syntax. For instance, a simple data binding is accomplished by specifying the {Binding} markup extension in place of the value type that a given property would ordinarily take. Many of the markup extensions enable an attribute syntax for properties where an attribute syntax would not otherwise be possible. For instance, a Style object is a relatively complex reference type that contains several other properties, each of which also takes byref objects and not primitives. But styles are typically created as a resource, and then referenced through one of the two markup extensions that request a resource. The extension defers the evaluation of the property value to a resource lookup and enables providing the value of the Style property, taking type Style, in attribute syntax as follows:

<Button Style="{StaticResource MyStyle}">My button</Button>

Here, StaticResource identifies the StaticResourceExtension class providing the markup extension implementation. The next string MyStyle is used as the input for the non-default StaticResourceExtension constructor, where the parameter as taken from the extension string declares the requested ResourceKey. MyStyle is expected to be the x:Key Attribute value of a Style defined as a resource. The StaticResource Markup Extension usage requests that the resource be used to provide the Style property value through static resource lookup logic at load time.

For more information about markup extensions, see Markup Extensions and XAML. For a reference of markup extensions and other XAML programming features, see XAML Namespace (x:) Language Features and WPF Namespace XAML Extensions.

Optional Property Element Usages

Full typeName.memberName Qualified Attributes

<Button Background="Blue">Background</Button>
<Button Button.Background="Blue">Button.Background</Button>
<Button Control.Background="Blue">Control.Background</Button>

<!--<Button Label.Background="Blue">Does not work</Button> -->

baseTypeName.memberName Property Elements

<Button>Control.Background PE
  <Control.Background>
    <LinearGradientBrush StartPoint="0,0" EndPoint="1,1">
      <GradientStop Color="Yellow" Offset="0.0" />
      <GradientStop Color="LimeGreen" Offset="1.0" />
    </LinearGradientBrush>
    </Control.Background>
</Button>

Concepts

Other Resources