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}" .../>
| Term | Description |
|---|---|
propertyPath |
A string that specifies the property path for the binding. For more info, see the "Property path" section. |
bindingProperties |
propName=value[, propName=value]* One or more binding properties that are specified using a name/value pair syntax. The square brackets ([]) and asterisk (*) in the syntax are not literals. They are a convention to indicate that more than one name/value pair is possible. Each name/value pair in the bindingProperties string should be separated from other name/value pairs. The separator can be either a comma or a space. |
propName |
The string name of the Binding property to set. For example, "Converter". |
value |
The value to set the property to. The handling of the argument value varies depending on the property of Binding that is being set. Some properties can be set only by using further nested markup extensions. Here's an example of a propName=value usage where the value is another markup extension usage: |
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.
| Property | Description |
|---|---|
| Path | Specifies the path to the binding source property. As noted in the preceding "Property path" section, you can establish the Path through the string immediately after the initial part of the Binding markup extension (for example, |
| Converter | Specifies the converter object that is called by the binding engine. The converter can be set in XAML, but only if you refer to an object instance that you've assigned in a ResourceDictionary in XAML. You use a StaticResource reference to that object in the resource dictionary. |
| ConverterLanguage | Specifies the culture to be used by the converter. (If you're setting ConverterLanguage you should also be setting Converter.) The culture is set as a standards-based identifier. For more info, see ConverterLanguage. |
| ConverterParameter | Specifies the converter parameter that can be used in converter logic. (If you're setting ConverterParameter you should also be setting Converter.) Most converters use simple logic that get all the info they need from the passed value to convert, and don't need a ConverterParameter value. The ConverterParameter parameter is for moderately advanced converter implementations that have more than one logic that keys off what's passed in ConverterParameter. You can write a converter that uses values other than strings but this is uncommon, see Remarks in ConverterParameter for more info. |
| ElementName | Specifies a data source by referencing another element in the same XAML construct that has a Name property or x:Name attribute. This is often use to share related values or use sub-properties of one UI element to provide a specific value for another element, for example in a XAML control template. |
| FallbackValue | Specifies a value to display when the source or path cannot be resolved. |
| Mode | Specifies the binding mode, as one of these strings: "OneTime", "OneWay", or "TwoWay". These correspond to the constant names of the BindingMode enumeration. |
| RelativeSource | Specifies a data source by describing the position of the binding source relative to the position of the binding target. This is expressed in terms of the run-time object graph, for example specifying the object's parent. Setting the RelativeSource property in XAML within a Binding markup extension usage requires nesting the RelativeSource markup extension. |
| Source | Specifies the object data source. Within the Binding markup extension, the Source property requires an object reference, such as a StaticResource reference. If this property is not specified, the acting data context specifies the source. It's more typical to not specify a Source value in individual bindings, and instead to rely on the shared DataContext for multiple bindings. For more info see DataContext or Data binding overview. |
| TargetNullValue | Specifies a value to display when the source value resolves but is explicitly null. |
| UpdateSourceTrigger | Specifies the timing of binding source updates. If unspecified, the default is Default. |
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.