Dependency Properties Overview

Prerequisites

This topic assumes that you have some basic knowledge of the CLR and object-oriented programming. In order to follow the examples in this topic, you should also understand XAML and know how to write Silverlight-based applications.

Dependency Properties in Silverlight

In Silverlight, dependency properties are typically exposed as CLR properties also. At a basic level, you could interact with these properties directly and never know that they are implemented as a dependency property. However, you should become familiar with some or all of the features of the Silverlight property system, so that you can take advantage of the dependency property features.

The purpose of dependency properties is to provide a way to compute the value of a property based on the value of other inputs. These other inputs might include external properties such as user preference, just-in-time property determination mechanisms such as data binding and animations/storyboards, multiple-use templates such as resources and styles, or values known through parent-child relationships with other elements in the object tree. In addition, a dependency property can be implemented to provide callbacks that can propagate changes to other properties.

For Silverlight types that are a DependencyObject and are visible in the UI in some way, most of the settable properties on the object are dependency properties, and can therefore support animation. For FrameworkElement derived types, the dependency property also can support styling. For read-only properties, it is less likely that the property is a dependency property, although there are some read-only properties that are still implemented as dependency properties because of WPF compatibility. For the uncommon cases where a settable property on a DependencyObject is not a dependency property, that property will be unable to support animation, data binding, or FrameworkElement styling.

In the SDK reference, you can definitively identify if a given Silverlight property is implemented as a dependency property. In the Remarks section, if there is "Dependency Property Identifier Field" and a link to an API (a field) where the name ends with Property, the property is a dependency property. This same convention of exposing a field and naming it in a corresponding way should be followed by custom or third party dependency properties also. For example, if there is a property named Ticks defined by a type, and a field named TicksProperty exposed by the same type (and the field is of type DependencyProperty), then Ticks is a dependency property.

Dependency Properties Back CLR Properties

Dependency properties and the Silverlight property system extend CLR-defined property functionality by providing a property store that backs a property, as an alternative implementation to the standard pattern of backing the property with a private field. The name of the type that identifies each property in the store is DependencyProperty. The other important type that defines the Silverlight property system is DependencyObject. DependencyObject defines the base class that can register and own a dependency property, and it is DependencyObject that maintains its dependency property values in a store.

Following is a summation of the terminology that is used in this documentation when discussing dependency properties:

• Dependency property: A property that exists on a DependencyObject, is stored by the DependencyObject property store, and is identified by a DependencyProperty identifier on the owning DependencyObject.

• Dependency property identifier: A DependencyProperty instance. In the case of an existing dependency property in the Silverlight core API, this instance is usually exposed as a public static readonly field, as a member of the same DependencyObject type that holds the dependency property. In the case of a custom dependency property, this field is obtained as a return value when registering a dependency property. You should then store this field as a member of the class. The dependency property identifier field can also be used as a parameter in APIs such as GetValue and SetValue that expose the fundamentals of the Silverlight property system, as well as other APIs where dependency properties are specified by identifier (for instance, some signatures of the PropertyPath constructor, or Setter.Property).

• CLR wrapper: The actual get and set implementations for the property as it is visible to the CLR type system (which operates at a lower level architecturally). These implementations incorporate the dependency property identifier by using it in the GetValue and SetValue calls, thus providing the backing for the property using the Silverlight property system. GetValue / SetValue calls should be the entirety of the get and set implementations. The wrapper is not just convenience for callers, it also exposes the dependency property to any process or tool that uses reflection or the CLR type system as its basis, which is vital in many scenarios.

The following example defines a custom IsSpinning dependency property, and shows the relationship of the DependencyProperty identifier to the property that it backs.

Public Shared ReadOnly IsSpinningProperty As DependencyProperty = _
    DependencyProperty.Register("IsSpinning", _
    GetType(Boolean), _
    GetType(SilverlightExampleClass), _
    Nothing)
Public Property IsSpinning() As Boolean
    Get
        Return CBool(GetValue(IsSpinningProperty))
    End Get
    Set(ByVal value As Boolean)
        SetValue(IsSpinningProperty, value)
    End Set
End Property

public static readonly DependencyProperty IsSpinningProperty = 
    DependencyProperty.Register(
    "IsSpinning", typeof(Boolean),
    typeof(SilverlightExampleClass), null
    );
public bool IsSpinning
{
    get { return (bool)GetValue(IsSpinningProperty); }
    set { SetValue(IsSpinningProperty, value); }
}

Note:
The preceding example is not intended as the complete example for how to create a custom dependency property. It is intended to help illustrate dependency property concepts for anyone that learns a concept best by looking at representative code. For a more complete example of creating a custom dependency property, see Custom Dependency Objects and Dependency Properties.

Setting Property Values

As a broad generalization, you can set Silverlight properties either in code or in XAML. For purposes of code versus XAML distinctions, whether a property is backed by a dependency property generally does not matter. Either way, if a property is settable and you set it, a value is set to the object that holds the property in its property store, however that store is implemented. There are however properties that can only be set in code. In most cases this is because the type that the property accepts cannot be expressed in XAML. Also, certain property-related mechanisms exist that only work with dependency properties and not CLR properties in general because the mechanism uses DependencyProperty as a type; an example of this is Setter.Property, used in styles and templates.

Setting Property Values in XAML

Setting Properties in Code

scratchCanvas.Width = 200; //scratchCanvas is an existing Canvas instance

scratchCanvas.Width = 200 ' scratchCanvas is an existing Canvas instance

double whatWidth = scratchCanvas.Width;

Dim whatWidth As Double
whatWidth = scratchCanvas.Width

Property Functionality Provided by a Dependency Property

A dependency property provides functionality that extends the functionality of a property as opposed to a property that is backed by a field. Often, each such functionality represents or supports a specific feature of the overall Silverlight set of features:

• Data binding

• Styles

• Animations

• Property-changed behavior

• Default value and ClearValue

Data Binding

So long as the dependency property to set is on a DependencyObject subclass, a dependency property can have its value set through data binding. Data binding works through a specific markup extension syntax in XAML, or the Binding object in code. With data binding, the final property value determination is deferred until run time, at which time the value is obtained from a data source.

The following example sets the text for a text block, using a binding in XAML. The binding uses an inherited data context and an object data source (not shown).

    <Canvas>
      <TextBlock Text="{Binding Team.TeamName}"/>
    </Canvas> 

You can also establish bindings using code rather than XAML. See SetBinding.

Note:
Bindings are treated as a local value for purposes of dependency property value precedence, which means that if you set another local value, you will eliminate the binding.

Binding Sources, Binding Targets

In order to be the source of a binding, a property does not need to be a dependency property; you can use any CLR property as a binding source. However, in order to be the target of a binding, the property must be a dependency property.

If you are setting bindings in code, note that the SetBinding API is defined only for FrameworkElement. However, you can create a binding definition using BindingOperations instead, and thus reference any DependencyObject property.

For either code or XAML, remember that DataContext is a FrameworkElement property. By using a form of parent-child property inheritance, the binding system can resolve a DataContext that exists on a parent element, even if the child object (which has the target property) is not a FrameworkElement and therefore does not hold its own DataContext value. However, that parent element must be a FrameworkElement in order to set and hold the DataContext. Alternatively, you must define the binding such that it can function with a null DataContext.

Note:
Applications targeting Silverlight 3 can only bind to target properties of a FrameworkElement. Support for binding to any DependencyObject dependency property was added in Silverlight 4.

For a one-way or two-way binding to be effective, the source property must support change notifications that propagate to the binding system and thus the target. For custom CLR binding sources, this means that the property must support INotifyPropertyChanged. Collections should support INotifyCollectionChanged. Certain classes support one of these interfaces in their implementations so that they are useful as base classes for data binding scenarios; an example of such a class is ObservableCollection<T>.

For more information on data binding in Silverlight, and how data binding relates to the property system, see Data Binding.

Styles

Animations

Property-Changed Behavior

Default Value and ClearValue

Dependency Property Value Precedence

When you get the value of a dependency property, you are potentially obtaining a value that was set on that property through any one of the property-based inputs that participate in the Silverlight property system. Dependency property value precedence exists so that a variety of scenarios for how Silverlight properties obtain their values can interact in a predictable way.

For example, styles and templates are intended to be a shared starting point for establishing property values and thus appearances of a control. But on a particular control instance you might want to change some property-specific aspect of the control versus the common template, such as giving it a different background color or a different text string as content. The Silverlight property system uses local values at higher precedence than style and template provided values, thus enabling the scenario.

More information about the concept of dependency property precedence, and a listing of the order in which the precedence applies, is provided in the topic Dependency Property Value Precedence.

Learning More About Dependency Properties

• Attached Properties Overview: An attached property is a type of property that supports a specialized XAML syntax in Silverlight. An attached property often does not have a direct correspondence with a CLR property hierarchy. The typical purpose of attached properties is to allow child elements to report property values to a parent element, even if the parent element and child element do not both possess that property as a possible member in a generalized type system. One primary scenario for attached properties in Silverlight is to enable child elements to inform the parent how they should be presented in UI; for an example of this scenario, see Canvas.Left.

• Custom Dependency Objects and Dependency Properties: Component developers or application developers may wish to create their own dependency property, in order to enable capabilities such as data binding or style support, or for property-changed behavior.

See Also

Concepts