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

Applies to Windows and Windows Phone

Represents a dependency property that is registered with the dependency property system. Dependency properties provide support for value expressions, data binding, animation, and property change notification. For more info on how DependencyProperty values serve as identifiers for dependency properties, see Dependency properties overview.

Inheritance

Object
  DependencyProperty

Syntax


public sealed class DependencyProperty


See Remarks

Attributes

[MarshalingBehavior(Agile)]
[Threading(Both)]
[Version(0x06020000)]
[WebHostHidden()]

Members

The DependencyProperty class has these types of members:

Methods

The DependencyProperty class has these methods. It also inherits methods from the Object class.

MethodDescription
GetMetadata Retrieves the property metadata value for the dependency property as registered to a type. You specify the type you want info from as a type reference.
Register Registers a dependency property with the specified property name, property type, owner type, and property metadata for the property. Use this method when defining or initializing a DependencyObject derived class that will own the registered dependency property.
RegisterAttached Registers an attached dependency property with the specified property name, property type, owner type, and property metadata for the property.

 

Properties

The DependencyProperty class has these properties.

PropertyAccess typeDescription

UnsetValue

Read-onlySpecifies a static value that is used by the property system rather than null to indicate that the property exists, but does not have its value set by the property system or by any app code.

 

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. The identifiers provide 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, which is a static member of the owner class.

The owner DependencyObject provides the property store for the dependency property. 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; this concept is explained in 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.

Note  A related syntax that can also be used to specify a property by name and is required by certain data and animation APIs is the property path syntax. A property path can be used to reference the structure of a class that has properties and the value of that property. For more info, see Property-path syntax.

The Windows Runtime implements the XAML attached property language feature with DependencyProperty identifiers and property storage on a DependencyObject. For more info, 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 the properties with a dependency property following these guidelines:

  • Register a dependency property using the Register method, which returns a DependencyProperty. This is your dependency property identifier. You should expose this object as an accessible static read-only property 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 get and set accessors for the property: these are the property wrappers, and will simplify access to your property for all callers.

XAML references to a dependency property name

Some properties that are typically set in XAML markup use DependencyProperty as their value. For example, you set Setter.Property in XAML. To set such a property in XAML, you specify the name of the dependency property as the attribute value.

For Setter.Property the type from which you are referencing a dependency property name is already scoped by the TargetType of the Style where the Setter exists. For a dependency property on the TargetType object, you can specify a Setter.Property value using the simple name of the dependency property. For example, if you have a Style that targets a Slider, and you want to style the Orientation property, the Property attribute value can be just "Orientation". Simple names also work so long as the dependency property came from a class in the deeper inheritance of the target type. For example, to style the Visibility property in the Style for a Slider, a Property attribute value of "Visibility" will work. In that case Visibility was defined by UIElement, but inherits to Slider.

You can also use Setter.Property to reference an attached property name. For the attribute value, use the form AttachedPropertyOwner.AttachedPropertyName, just like you'd use to set that attached property as an attribute in XAML. For example, here is a Setter that sets the attached property AutomationProperties.ItemType in a Style: <Setter Property="AutomationProperties.ItemType" Value="Navigation Button"/>

Note  The name of a dependency property is not the name of the DependencyProperty static property identifier. It's the name string that the property is registered with, and the name that's the typical usage name for that property in Windows Runtime programming when exposed by Microsoft IntelliSense and the reference documentation. In other words, you don't want the string you specify for Setter.Property in XAML to end with "Property" (except for a few rare cases where the dependency property actually does contain the suffix "Property").

Using a DependencyProperty (dependency property identifier) in code

There are several methods that are utility methods for the Windows Runtime property system that use a DependencyProperty value as an input parameter. These include:

Examples

This 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 as a member of the class. For more examples, see Custom dependency properties.


public class Fish : Control
{
    public static readonly DependencyProperty SpeciesProperty =
    DependencyProperty.Register(
    "Species",
    typeof(String),
    typeof(Fish), null
    );
    public string Species
    {
        get { return (string)GetValue(SpeciesProperty); }
        set { SetValue(SpeciesProperty, (string)value); }
    }
}


Requirements

Minimum supported client

Windows 8 [Windows Store apps only]

Minimum supported server

Windows Server 2012 [Windows Store apps only]

Minimum supported phone

Windows Phone 8.1 [Windows Runtime apps only]

Namespace

Windows.UI.Xaml
Windows::UI::Xaml [C++]

Metadata

Windows.winmd

See also

Custom dependency properties
Dependency properties overview
Custom attached properties
XAML user and custom controls sample

 

 

Show:
© 2014 Microsoft