Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

DependencyProperty Class

Represents a dependency property that is registered with the Windows Presentation Foundation (WPF) property system. Dependency properties provide support for value expressions, property invalidation and dependent-value coercion, default values, inheritance, data binding, animation, property change notification, and styling.

Namespace: System.Windows
Assembly: WindowsBase (in windowsbase.dll)
XML Namespace:  http://schemas.microsoft.com/winfx/2006/xaml/presentation

[TypeConverterAttribute("System.Windows.Markup.DependencyPropertyConverter, PresentationFramework, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35, Custom=null")] 
public sealed class DependencyProperty
/** @attribute TypeConverterAttribute("System.Windows.Markup.DependencyPropertyConverter, PresentationFramework, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35, Custom=null") */ 
public final class DependencyProperty
TypeConverterAttribute("System.Windows.Markup.DependencyPropertyConverter, PresentationFramework, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35, Custom=null") 
public final class DependencyProperty
<object property="dependencyPropertyName"/>
- or -
<object property="ownerType.dependencyPropertyName"/>
- or -
<object property="attachedPropertyOwnerType.attachedPropertyName"/>
 dependencyPropertyName  A string that specifies the DependencyProperty.Name of the desired dependency property. This can be preceded by a prefix if the property is not in the default xmlns namespace (for details, see XAML Namespaces and Namespace Mapping.)  ownerType.dependencyPropertyName A string that specifies an owner type of a dependency property, a dot (.), then the DependencyProperty.Name. ownerType can also be preceded by a 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. For more information, see Styling and Templating.  attachedPropertyOwnerType.attachedPropertyName  A string that specifies  the owner of an attached property, a dot (.), then the attached property name. attachedPropertyOwnerType can also be preceded by a prefix. 

If you want properties on your custom types to support value expressions, property invalidation, per-type default values, inheritance, data binding, animation, or styling, you should back these CLR properties with a dependency property following these guidelines and procedures:

  1. Register a dependency property using the Register method; this method returns a DependencyProperty, which 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, and this convention is followed by all dependency properties implemented in WPF. For example, the Control.Background dependency property is identified by the Control.BackgroundProperty field.

  2. During registration, you can provide PropertyMetadata for the property to further define the property's behaviors, including its default value and callbacks that can be used to modify the property value in accordance to changes in related property values.

  3. Provide common language runtime (CLR) accessors for the property.

If you want to create a property that can be used on all DependencyObject types regardless of whether they are within the derived class list of the class that defines the property, then you should create an attached property. An example of an attached property is the DockPanel.Dock property. For details, see Attached Properties Overview.

Dependency properties in general are described in more detail in the Dependency Properties Overview. Creating custom dependency properties is described in more detail in Custom Dependency Properties.

You can also create a DependencyProperty and use the property system to get and set the value without exposing common language runtime (CLR) accessors, but this is not a typical class design practice.

DependencyProperty supports a XAML attribute syntax for filling property values, which is used when a Setter, Trigger, or Condition in a Style specifies its Property value. For details, see Styling and Templating.

Attached properties are available from any DependencyObject, and use a distinct ownerType.propertyName syntax form in XAML. For details, see Attached Properties Overview..

This example shows how to back a common language runtime (CLR) property with a DependencyProperty field, thus defining a dependency property. When you define your own properties and want them to support many aspects of Windows Presentation Foundation (WPF) functionality, including styles, data binding, inheritance, animation, and default values, you should implement them as a dependency property.

The following example first registers a dependency property by calling the Register method. The name of the identifier field that you use to store the name and characteristics of the dependency property must be the Name you chose for the dependency property as part of the Register call, appended by the literal string Property. For instance, if you register a dependency property with a Name of Location, then the identifier field that you define for the dependency property must be named LocationProperty.

In this example, the name of the dependency property and its CLR accessor is State; the identifier field is StateProperty; the type of the property is Boolean; and the type that registers the dependency property is MyStateControl.

If you fail to follow this naming pattern, designers might not report your property correctly, and certain aspects of property system style application might not behave as expected.

You can also specify default metadata for a dependency property. This example registers the default value of the State dependency property to be false.

public class MyStateControl : ButtonBase
{
  public MyStateControl() : base() { }
  public Boolean State
  {
    get { return (Boolean)this.GetValue(StateProperty); }
    set { this.SetValue(StateProperty, value); } 
  }
  public static readonly DependencyProperty StateProperty = DependencyProperty.Register(
    "State", typeof(Boolean), typeof(MyStateControl),new PropertyMetadata(false));
}

For the complete sample, see Custom Classes with Dependency Properties Sample.

For more information about how and why to implement a dependency property, as opposed to just backing a CLR property with a private field, see Dependency Properties Overview.

System.Object
  System.Windows.DependencyProperty

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

Windows 98, Windows Server 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile for Pocket PC, Windows Mobile for Smartphone, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The Microsoft .NET Framework 3.0 is supported on Windows Vista, Microsoft Windows XP SP2, and Windows Server 2003 SP1.

.NET Framework

Supported in: 3.0

Community Additions

Show:
© 2014 Microsoft