Binding markup extension

[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]

{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 general info about how to use data binding in your app, 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

If you don't name a Binding property in your Binding markup extension, Path acts like its default property. You can use several equivalent syntaxes for Path:

• Provide the path immediately after the initial part of the Binding markup extension; this takes advantage of the default property behavior: {Binding ...}.
• Use an explicit Path property name in the Binding markup extension: {Binding Path=...}.
• Set 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 evaluates as a search for a particular property of an object, so that the binding engine can return the value of that property. The property path can be used to traverse into the object model of a custom object or a DependencyObject.

The delimiter between steps in a property path is a dot (.). You can include multiple delimiters to traverse successive sub-properties until the final desired property value is reached. Use the dot delimiter even if the source object is a C++ data source, XAML doesn't recognize the "::" delimiter that C++ code definitions use.

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 are 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 a property path can specify items in the collection by their position or index. For example, "Teams[0].Players", where the literal "[]" encloses the "0" that requests the first item in a zero-indexed collection.

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 property path, put parentheses around the owner-qualified attached property name; for example, (AutomationProperties.Name).

A property path intermediate object is stored as a PropertyPath object in a run-time representation, but most scenarios won't need to interact with a PropertyPath object in code. You can usually specify the binding info you need using XAML and the Binding markup extension.

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

Binding properties that can be set with the Binding markup extension

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

Here are the binding properties that can be set with the binding markup extension. Several of the property values require object types that don't have a type conversion, these require markup within the Binding markup extension that invokes another markup extension that can do a type conversion or lookup.

Windows 8: FallbackValue, TargetNullValue, and UpdateSourceTrigger aren't enabled for Windows 8, they were introduced in Windows 8.1.

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 like an element in page1.xaml is a local value, whereas TemplateBinding in a template used for a control in that page is a style value.

Important  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 or through code) throws an exception when the binding is applied to a property.

Tip  If you need to specify a single curly brace for a value, such as in Path or ConverterParameter, precede it with a backslash: \{. Alternatively, enclose the entire string that contains the braces that need escaping in a secondary quotation set, for example ConverterParameter='{Mix}'.

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.

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.

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.

Migration notes

• Windows Presentation Foundation (WPF) and Microsoft Silverlight supported the ability to use a Binding expression to supply the Value for a Setter in a Style. The Windows Runtime doesn't support a Binding usage for Setter.Value (the Binding won't evaluate and the Setter has no effect, you won't get errors, but you won't get the desired result either). When you convert XAML styles from WPF or Silverlight XAML, replace any Binding expression usages with strings or objects that set values, or refactor the values as shared StaticResource values rather than Binding-obtained values.
• The Binding markup extension for Windows Runtime XAML doesn't support BindsDirectlyToSource; NotifyOnValidationError; StringFormat; ValidatesOnDataErrors; ValidatesOnExceptions.

Design-time tools support for the {Binding} markup extension

Microsoft Visual Studio 2013 can include data-context sourced values in the Microsoft IntelliSense dropdowns when you use the {Binding} markup extension in a XAML page. For example, as soon as you type "{Binding", any of the property values from the data context that can possibly be the Path value are displayed in the IntelliSense dropdowns, along with the other named Binding properties described previously. For this to work, you must either have the data context already set on the view, or be using a design-time data context that Visual Studio 2013 promote your data through. Visual Studio 2013 can also resolve data contexts from data templates.

Visual Studio 2013 has a Go To Definition (F12) feature that you're probably familiar with for pure code scenarios. But there's also support for Go To Definition for several of the XAML markup extensions, including getting to the code-defined data context from a {Binding} usage.

Related topics

Binding

TemplateBinding markup extension

Property-path syntax

Data binding overview

XAML data binding sample