DependencyProperty Class

Represents a property that can be set through methods such as, styling, data binding, animation, and inheritance.

System.Object
  System.Windows.DependencyProperty

Namespace:  System.Windows
Assembly:  WindowsBase (in WindowsBase.dll)
XMLNS for XAML: http://schemas.microsoft.com/winfx/2006/xaml/presentation, http://schemas.microsoft.com/netfx/2007/xaml/presentation

[TypeConverterAttribute("System.Windows.Markup.DependencyPropertyConverter, PresentationFramework, Version=4.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35, Custom=null")]
public sealed class DependencyProperty
<object property="dependencyPropertyName"/>
- or -
<object property="ownerType.dependencyPropertyName"/>
- or -
<object property="attachedPropertyOwnerType.attachedPropertyName"/>

XAML Values

dependencyPropertyName

A string that specifies the DependencyProperty.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 XAML Namespaces and Namespace Mapping for WPF XAML.)

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 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. 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 an XML namespace prefix.

The DependencyProperty type exposes the following members.

  NameDescription
Public propertyDefaultMetadataGets the default metadata of the dependency property.
Public propertyGlobalIndexGets an internally generated value that uniquely identifies the dependency property.
Public propertyNameGets the name of the dependency property.
Public propertyOwnerTypeGets the type of the object that registered the dependency property with the property system, or added itself as owner of the property.
Public propertyPropertyTypeGets the type that the dependency property uses for its value.
Public propertyReadOnlyGets a value that indicates whether the dependency property identified by this DependencyProperty instance is a read-only dependency property.
Public propertyValidateValueCallbackGets the value validation callback for the dependency property.
Top

  NameDescription
Public methodAddOwner(Type)Adds another type as an owner of a dependency property that has already been registered.
Public methodAddOwner(Type, PropertyMetadata)Adds another type as an owner of a dependency property that has already been registered, providing dependency property metadata for the dependency property as it will exist on the provided owner type.
Public methodEquals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Public methodGetHashCodeReturns a hash code for this DependencyProperty. (Overrides Object.GetHashCode().)
Public methodGetMetadata(DependencyObject)Returns the metadata for this dependency property as it exists on the specified object instance.
Public methodGetMetadata(DependencyObjectType) Returns the metadata for this dependency property as it exists on a specified type.
Public methodGetMetadata(Type)Returns the metadata for this dependency property as it exists on a specified existing type.
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Public methodIsValidTypeDetermines whether a specified value is acceptable for this dependency property's type, as checked against the property type provided in the original dependency property registration.
Public methodIsValidValueDetermines whether the provided value is accepted for the type of property through basic type checking, and also potentially if it is within the allowed range of values for that type.
Public methodOverrideMetadata(Type, PropertyMetadata)Specifies alternate metadata for this dependency property when it is present on instances of a specified type, overriding the metadata that existed for the dependency property as it was inherited from base types.
Public methodOverrideMetadata(Type, PropertyMetadata, DependencyPropertyKey)Supplies alternate metadata for a read-only dependency property when it is present on instances of a specified type, overriding the metadata that was provided in the initial dependency property registration. You must pass the DependencyPropertyKey for the read-only dependency property to avoid raising an exception.
Public methodStatic memberRegister(String, Type, Type)Registers a dependency property with the specified property name, property type, and owner type.
Public methodStatic memberRegister(String, Type, Type, PropertyMetadata)Registers a dependency property with the specified property name, property type, owner type, and property metadata.
Public methodStatic memberRegister(String, Type, Type, PropertyMetadata, ValidateValueCallback)Registers a dependency property with the specified property name, property type, owner type, property metadata, and a value validation callback for the property.
Public methodStatic memberRegisterAttached(String, Type, Type)Registers an attached property with the specified property name, property type, and owner type.
Public methodStatic memberRegisterAttached(String, Type, Type, PropertyMetadata)Registers an attached property with the specified property name, property type, owner type, and property metadata.
Public methodStatic memberRegisterAttached(String, Type, Type, PropertyMetadata, ValidateValueCallback)Registers an attached property with the specified property type, owner type, property metadata, and value validation callback for the property.
Public methodStatic memberRegisterAttachedReadOnly(String, Type, Type, PropertyMetadata)Registers a read-only attached property, with the specified property type, owner type, and property metadata.
Public methodStatic memberRegisterAttachedReadOnly(String, Type, Type, PropertyMetadata, ValidateValueCallback)Registers a read-only attached property, with the specified property type, owner type, property metadata, and a validation callback.
Public methodStatic memberRegisterReadOnly(String, Type, Type, PropertyMetadata) Registers a read-only dependency property, with the specified property type, owner type, and property metadata.
Public methodStatic memberRegisterReadOnly(String, Type, Type, PropertyMetadata, ValidateValueCallback)Registers a read-only dependency property, with the specified property type, owner type, property metadata, and a validation callback.
Public methodToString Returns the string representation of the dependency property. (Overrides Object.ToString().)
Top

  NameDescription
Public fieldStatic memberUnsetValueSpecifies a static value that is used by the WPF property system rather than null to indicate that the property exists, but does not have its value set by the property system.
Top

A DependencyProperty supports the following capabilities in Windows Presentation Foundation (WPF):

  • The property can be set in a style. For more information, see Styling and Templating.

  • The property can be set through data binding. For more information about data binding dependency properties, see How to: Bind the Properties of Two Controls.

  • The property can be set with a dynamic resource reference. For more information, see XAML Resources.

  • The property can inherit its value automatically from a parent element in the element tree. For more information, see Property Value Inheritance.

  • The property can be animated. For more information, see Animation Overview.

  • The property can report when the previous value of the property has been changed and the property value can be coerced. For more information, see Dependency Property Callbacks and Validation.

  • The property reports information to WPF, such as whether changing a property value should require the layout system to recompose the visuals for an element.

  • The property receives support in the WPF Designer for Visual Studio. For example, the property can be edited in the Properties window.

To learn more about dependency properties, see Dependency Properties Overview. If you want properties on your custom types to support the capabilities in the preceding list, you should create a dependency property. To learn how to create custom dependency properties, see Custom Dependency Properties.

An attached property is a property that enables any object to report information to the type that defines the attached property. In WPF, any type that inherits from DependencyObject can use an attached property regardless of whether the type inherits from the type that defines the property. An attached property is a feature of the XAML language.  To set an attached property in XAML, use the ownerType.propertyName syntax. An example of an attached property is the DockPanel.Dock property. If you want to create a property that can be used on all DependencyObject types, then you should create an attached property. To learn more about attached properties, including how to create them, 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 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.

.NET Framework

Supported in: 4.5.2, 4.5.1, 4.5, 4, 3.5, 3.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft