Binding markup extension (Windows Store apps using C#/VB/C++ and XAML)

{Binding} provides a data-bound property value such that the value is deferred until run time. A binding markup extension is converted into an intermediate expression object at XAML load time. The expression and the data context are used by a data binding engine to determine the property value at run time

Important  This topic is intended to explain how to use the {Binding} markup extension as a syntax component in XAML. If you're looking for a more general topic about data binding and XAML, see Data binding overview.

XAML attribute usage

<object property="{Binding}" .../>
-or-
<object property="{Binding propertyPath}" .../>
-or-
<object property="{Binding bindingProperties}" .../>
-or-
<object property="{Binding propertyPath, bindingProperties}" .../>

Property path

The Path of a data binding is conceptually similar to its default property in the Binding markup extension. You can establish the Path in one of the following ways:

• In the string immediately after the initial part of the Binding markup extension ({Binding ...} ).
• In a named argument in the Binding markup extension (Path=...).
• By setting Binding.Path in code. In this case, you must create or reference an intermediate PropertyPath object.

The Path for a data binding is a property path. A property path is a string that is initially evaluated as instructions to search an object for a property of that name and return the value. The property path can be used to traverse into the object model of a custom object or a DependencyObject in cases where the value of the initially named property is an object, and the value you want is from a sub-property of that object. After it is evaluated, property path data is stored as a PropertyPath object in a run-time representation.

The delimiter between steps in a property path is a dot (.). You can include multiple delimiters to reference successive sub-properties until the desired property value is reached. Use the dot delimiter even if the object is a C++ data source where the defining C++ code might use ::; the property path syntax is intentionally oriented towards XAML, where a dot is the typical separator.

For example, you might bind to a business object that represents an employee. If you wanted to bind UI to the string for the employee's first name, your data binding path might be "Employee.FirstName". Or, if you were binding an items control to a collection property that lists the employee's dependents, your data binding path might be "Employee.Dependents", and a data template applied to the items control would take care of displaying individual "Dependents" items.

If the data source is a collection, then the property path specifies properties to be found on a collection item object.

When using an ElementName binding to an existing DependencyObject, you can use attached properties as part of the property path. To disambiguate an attached property so that the intermediate dot in the attached property name is not considered a step into a path, put parentheses around the owner-qualified attached property name; for example, (AutomationProperties.Name).

For more info about the string syntax for a property path, property paths in animation feature areas, and constructing a PropertyPath object, see PropertyPath syntax.

Binding properties that can be set with the Binding markup extension

The Binding markup extension is explained through the bindingPropertyName=value placeholder syntax because there are multiple read/write properties of a Binding that can be set. The properties can be set in any order and the name=value pairs are separated by commas, or by spaces.

The following table lists the binding properties that can be set with the binding markup extension. Several of the property values require object types that do not support a native type conversion, and thus require markup within the Binding markup extension.

Remarks

Important  In terms of dependency property precedence, a Binding markup extension is equivalent to the binding's position in the precedence. For example, a data binding in UI definition XAML is a local value, whereas TemplateBinding in a template for a control is a style value. If you set a local value for a property that previously had a Binding markup extension to provide a local value, the Binding is completely removed.

Three of the binding properties in the Binding markup extension syntax (Source, RelativeSource, and ElementName ) specify a binding source. These properties are mutually exclusive in a binding. If you have set one of these properties, then setting either of the other two in a binding (through XAML in a markup extension or through code) causes an exception when the binding is applied to a property.

Tip  If you need to specify an opening or closing curly brace ("{""}") for a value, such as in Path or ConverterParameter, enclose the value in a secondary quotation set. For example, if the Binding uses double quotation marks ("), enclose the string that contains the curly brace in single quotation marks (').

Binding is a markup extension. Markup extensions are typically implemented when there is a requirement for attribute values to be something other than literal values or handler names. Also, the requirement is more global than just putting type converters on certain types or properties. All markup extensions in XAML use curly braces ("{ }") in their attribute syntax, which is the convention by which a XAML processor recognizes that a markup extension must process the attribute. For more info about markup extensions, see XAML overview.

Converter, ConverterLanguage and ConverterLanguage are all related to the scenario of converting a value or type from the binding source into a type or value that is compatible with the binding target property. For more info and examples, see the "Data conversions" section of Data binding overview.

The property that is the target of a data binding must be a dependency property. For more info, see Dependency properties overview.

An example {Binding} usage

This example XAML is taken from the XAML data binding sample.

<StackPanel Margin="5">
    <!-- Add converter as a resource to reference it from a Binding. --> 
    <StackPanel.Resources>
        <local:S2Formatter x:Key="GradeConverter"/>
    </StackPanel.Resources>
    <TextBlock Style="{StaticResource BasicTextStyle}" Text="Percent grade:" Margin="5" />
    <Slider x:Name="sliderValueConverter" Minimum="1" Maximum="100" Value="70" Margin="5"/>
    <TextBlock Style="{StaticResource BasicTextStyle}" Text="Letter grade:" Margin="5"/>
    <TextBox x:Name="tbValueConverterDataBound"
      Text="{Binding ElementName=sliderValueConverter, Path=Value, Mode=OneWay,  
        Converter={StaticResource GradeConverter}}" Margin="5" Width="150"/> 
</StackPanel> 

This particular example sets four different Binding properties: ElementName, Path, Mode and Converter. Path in this case is shown explicitly named as a Binding property. The Path is evaluated to a data binding source that is another object in the same run-time object tree, a Slider named sliderValueConverter.

Note how the Converter property value uses another markup extension, StaticResource, so there's two nested markup extension usages here. The inner one is evaluated first, so that once the resource is obtained there's a practical IValueConverter (a custom class that's instantiated by the local:S2Formatter element in resources) that the binding can use.

Related topics

Binding

TemplateBinding markup extension

PropertyPath syntax

Data binding overview

XAML data binding sample

Build date: 11/28/2012