DependencyProperty Class (System.Windows)

Switch View

Collapse All

Language Filter

This page is specific to

Microsoft Silverlight 3

Other versions are also available for the following:

.NET Framework Class Library for Silverlight

DependencyProperty Class

Represents a dependency property that is registered with the Silverlight dependency property system. Dependency properties provide support for value expressions, data binding, animation, and property change notification.

Namespace: System.Windows
Assembly: System.Windows (in System.Windows.dll)

Syntax

Visual Basic (Declaration)

Public Class DependencyProperty

Visual Basic (Usage)

Dim instance As DependencyProperty

public class DependencyProperty

XAML Attribute Usage

<object property="dependencyPropertyName"/>
- or -
<object property="ownerTypeName.dependencyPropertyName"/>
- or -
<object property="attachedPropertyOwnerTypeName.attachedPropertyName"/>

XAML Values

dependencyPropertyName: A string that specifies the registered name of the desired dependency property. This can be preceded by an XML namespace prefix if the property is not in the default XML namespace (for details, see Silverlight XAML Namespaces, and Mapping XAML Namespaces as Prefixes.)
ownerTypeName.dependencyPropertyName: A string that specifies an owner type of a dependency property, a dot (.), then the property name. ownerType can also be preceded by an XML namespace prefix. This usage is particular to late-bound styles and templates, where the owner of the dependency property must be specified for parsing context because the TargetType is not yet known.
attachedPropertyOwnerTypeName.attachedPropertyName: A string that specifies the owner of an attached property, a dot (.), then the attached property name. attachedPropertyOwnerTypeName can also be preceded by an XML namespace prefix.

A shorthand for remembering the above syntax, so long as XML namespace mapping is not required, is to use the name of the dependency property identifier field, but subtracting the suffix Property.

Remarks

Dependency property concepts are covered in detail in the topic Dependency Properties Overview.

Instances of DependencyProperty are often referenced in the documentation as dependency property identifiers. Their function is to serve as a way to refer to a dependency property that was registered to a particular DependencyObject owner type. When the owner type registers the property, the owner type exposes the DependencyProperty instance as the identifier. The owner DependencyObject provides the property store for the dependency property as it participates in the Silverlight property system.

When working with a dependency property in code, you might use a DependencyProperty identifiers as input for calls to property system methods such as SetValue. However, in most cases, getting or setting a dependency property is simpler by getting or setting the "wrapper" CLR property that generally exposes the dependency property to XAML usage and to the CLR type system. For details, see "Dependency Properties Back CLR Properties" section of Dependency Properties Overview.

DependencyProperty supports a native conversion for XAML attribute syntax for filling values, which is used when a Setter specifies its Property value. This conversion uses an ownerTypeName.propertyName form for the input string.

A related type that can also be used to specify a property by name and is required by certain data and animation APIs is PropertyPath. A PropertyPath can be used to reference any CLR property (that property can also be a dependency property, but does not have to be). A PropertyPath can be specified in XAML, and can be used to specify a property within an object hierarchy. For more information, see Property Path Syntax.

The Silverlight property system supports its implementation of the XAML attached property language feature with DependencyProperty identifiers and property storage on a DependencyObject. For details, see Attached Properties Overview.

Custom Dependency Properties

If you want properties on your custom types to support value expressions, data binding, or animation, you should back these CLR properties with a dependency property following these guidelines:

Register a dependency property using the Register method, which returns a DependencyProperty. You should store as an accessible static read-only field in your class. By convention, the name of this DependencyProperty identifier field should end with Property.
During registration, you can provide PropertyMetadata for the property to further define the property's behaviors.
Provide CLR get and set accessors for the property.
For more information on custom dependency properties for custom DependencyObject classes, including examples and procedures, see Custom Dependency Objects and Dependency Properties.

Examples

The following example shows a basic usage where a DependencyProperty is established as a public static member of a class. This is done by calling Register and storing the return value.

Visual Basic

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); }
}

You can find a similar example that provides more information about creating a custom dependency property in the topic Custom Dependency Objects and Dependency Properties.

Inheritance Hierarchy

System..::.Object
System.Windows..::.DependencyProperty

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.

Reference

DependencyProperty Members

System.Windows Namespace

DependencyObject

Other Resources

Dependency Properties Overview

Dependency Property Value Precedence

Custom Dependency Objects and Dependency Properties