Share via


Binding Markup Extension

Microsoft Silverlight will reach end of support after October 2021. Learn more.

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 the Silverlight binding engine to determine the property value at run time

XAML Attribute Usage

<object property="{Binding}" .../>

-or-

<object property="{Binding propertyPath}" .../>

-or-

<object property="{Binding oneOrMoreBindingProperties}" .../>

-or-

<object property="{Binding propertyPath, oneOrMoreBindingProperties}" .../>

XAML Values

propertyPath

A string that specifies the property path for the binding. For more information, see the "Property Paths" section.

oneOrMoreBindingProperties

bindingPropertyName=value[, bindingPropertyName=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 indicators that more than one name/value pair is possible.

Each name/value pair should be separated from other name/value pairs. The separator can be either a comma (,) or a space ( ).

bindingPropertyName

The string name of the Binding property to set. Some properties can be set only by using further nested markup extensions. For more information, see "Binding Properties That Can Be Set with the Binding Markup Extension" section.

value

The value to set the property to. The handling of the attribute value is ultimately specific to the type and logic of the bindingPropertyName being set.

Property Paths

The Path of a 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=).

  • In the Binding(String) constructor in code.

  • By setting Binding.Path in code. In this case, you must create or reference an intermediate PropertyPath object.

The Path for a 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 CLR 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 subproperty of that object. After it is evaluated (either from XAML or the Binding(String) constructor), property path information 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 subproperties until the desired property value is reached.

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 properties of the 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, (Validation.Errors).

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

NoteNote:

If you are familiar with WPF data binding, you know that WPF supports property path techniques for retrieving indexed items in a collection and for retrieving attached property values. Silverlight 5 supports these techniques, but with limitations. For more information, see Property Path Syntax.

Binding Properties That Can Be Set with the Binding Markup Extension

The Binding markup extension uses the bindingPropertyName=value syntax because there are multiple read/write properties of a Binding that can be set. The properties can be set in any order and are separated by commas.

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.

Property

Description

Path

Specifies the path to the binding source property. As noted in the preceding "Property Paths" section, you can establish the Path through the string immediately after the initial part of the Binding markup extension (for example, {Binding Employee.FirstName}), or you can also specify the path explicitly just like the other named Binding properties (for example, {Binding Path=Employee.FirstName}).

BindsDirectlyToSource

Specifies whether the binding ignores any ICollectionView settings on the data source.

Converter

Specifies the converter object that is called by the binding engine. The converter can be set in XAML, but only if you are referring to a converter that is defined in such a way that it can be instantiated and placed in a ResourceDictionary in XAML. The XAML reference then requires a StaticResource reference to that object in the resource dictionary.

ConverterCulture

Specifies the culture to be used by the converter. The culture converter can be set as a standards-based identifier. For more information, see the ConverterCulture property.

ConverterParameter

Specifies the converter parameter that can be used in converter logic. Most converters use simple logic that can accept a string ConverterParameter value. You can write a converter that uses non-strings and then pass objects to ConverterParameter in XAML. However, this is an uncommon scenario, and requires the use of the property element syntax instead of the binding markup extension.

ElementName

Specifies a data source by referencing another element that has a Name property or x:Name Attribute (the ElementName attribute value specifies that name). The named element must exist in the same XAML namescope as does the object where the binding is applied.

FallbackValue

Specifies a value to display when the source path cannot be resolved.

Mode

Specifies the binding mode, as one of the following strings: OneTime, OneWay, or TwoWay.

NotifyOnValidationError

Enables a validation/notification mode on the binding. Can be true or false (default is false).

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. Whether set in attribute form or as a binding property in a markup extension, setting the RelativeSource property in XAML requires using 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.

StringFormat

Specifies the String format to use for display. For more information, see Formatting Types.

TargetNullValue

Specifies a value to display when the source value is null.

UpdateSourceTrigger

Specifies the timing of binding source updates. If unspecified, the default is Default.

ValidatesOnDataErrors

Enables a validation/notification mode on the binding. Can be true or false (default is false). This property is ignored for a binding if the ValidatesOnExceptions property is true and that binding throws an exception.

ValidatesOnExceptions

Enables a validation/notification mode on the binding. Can be true or false (default is false).

ValidatesOnNotifyDataErrors

Enables a validation/notification mode on the binding. Can be true or false (default is true).

Remarks

Important noteImportant Note:

In terms of dependency property precedence, a Binding markup extension is equivalent to its position in the precedence. 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.

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.

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.

TipTip:

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 (').

Some aspects of the Binding markup extension in Silverlight are subsets of the Binding markup extension in WPF. Notably, WPF supports the XPath, NotifyOnTargetUpdated, and NotifyOnSourceUpdated properties, which are reflected in the WPF Binding class. Silverlight 5 does not support these properties in its Binding class. Also, WPF has more possible values for the UpdateSourceTrigger and Mode properties. 

See Also

Reference

Concepts