DependencyProperty Class

Definition

Namespace:

Windows.UI.Xaml

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.

public ref class DependencyProperty sealed

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 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(Windows.Foundation.UniversalApiContract), 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

See Remarks

Inheritance

Object Platform::Object IInspectable DependencyProperty

Attributes

ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Windows requirements

Device family	Windows 10 (introduced in 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (introduced in v1.0)

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

Public Class Fish
    Inherits Control

    Public Shared ReadOnly SpeciesProperty As DependencyProperty = _
    DependencyProperty.Register(
    "Species", _
    GetType(String), _
    GetType(Fish), _
    Nothing)
    Public Property Species As String
        Get
            Species = CType(GetValue(SpeciesProperty), String)
        End Get
        Set(value As String)
            SetValue(SpeciesProperty, value)
        End Set
    End Property
End Class

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.

Note

A related syntax that can also be used to specify a property by name and is required by certain data and animation API 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.

Tip

If you are programming using a Microsoft .NET language (C# or Microsoft Visual Basic), the TypeName type projects as System.Type. When programming using C#, it is common to use the typeof operator to get references to the System.Type of a type. In Microsoft Visual Basic, use GetType. If you're using Visual C++ component extensions (C++/CX)), where you'll need to create a TypeName helper struct, you can use the typeid component extension.

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:

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

Properties

UnsetValue

Specifies 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.

Methods

GetMetadata(TypeName)	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(String, TypeName, TypeName, PropertyMetadata)	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(String, TypeName, TypeName, PropertyMetadata)	Registers an attached dependency property with the specified property name, property type, owner type, and property metadata for the property.

See also

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