DependencyProperty Class

Definition

public ref class DependencyProperty sealed

/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.WinUIContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class DependencyProperty final

[Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.UI.Xaml.WinUIContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class DependencyProperty

Public NotInheritable Class DependencyProperty

Inheritance

Object Platform::Object IInspectable DependencyProperty

Attributes

ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

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

A Visual C++ component extensions (C++/CX) example isn't shown here because it must be factored completely differently than the Microsoft .NET examples, and involves several different code files. See examples in Custom dependency properties.

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.

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"/>

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:

• DependencyObject.ClearValue
• DependencyObject.GetAnimationBaseValue
• DependencyObject.GetValue
• DependencyObject.ReadLocalValue
• DependencyObject.SetValue
• DependencyPropertyChangedEventArgs.Property
• Setter(DependencyProperty,Object) constructor

Properties

Methods

Applies to

See also

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