Custom Dependency Objects and Dependency Properties

Prerequisites

This topic assumes that you understand dependency properties from the perspective of a consumer of existing dependency properties on Silverlight classes, and have read Dependency Properties Overview. In order to follow the examples in this topic, you should also understand XAML and know how to write basic applications for Silverlight.

What Is a Dependency Property?

Dependency properties are properties that are registered with the Silverlight property system by calling the DependencyProperty.Register method, and that are identified by a DependencyProperty identifier field. You can enable what would otherwise be a CLR property to support styling, data binding, animations, and default values by implementing it as a dependency property. Dependency properties can be used only by DependencyObject types, but DependencyObject is quite high in the Silverlight class hierarchy, so the majority of classes available in Silverlight that are intended for UI and presentation can support dependency properties. For more information about dependency properties and some of the terminology and conventions used for describing them in this documentation, see Dependency Properties Overview.

Differences Between the Silverlight and WPF Property Systems

Windows Presentation Foundation (WPF) is the technology that first defined the dependency property concept. Silverlight is in many ways a subset of WPF. This subset principle also applies to the respective property systems. The following is a list of property system capabilities that exist in WPF but do not exist in Silverlight 5:

• Coerce-value callbacks and DependencyObject.CoerceValue. However, you can typically implement most of your needs in this area by using property-changed callbacks, which are supported in Silverlight.

• Custom read-only dependency properties. Silverlight does not implement DependencyPropertyKey or a SetValue pattern that uses the key. Without this key technique, there is no API available that can prevent external code from setting the dependency property through SetValue and violating your read-only intention for the property.

• Per-type property metadata, as established with OverrideMetadata. The property metadata used for a dependency property in Silverlight is always the metadata as it is initially registered for its owner type. This consideration applies to default values and to property-changed callbacks, which are the two supported information sets in Silverlight property metadata.

• Property metadata subclasses that are defined by the framework, such as UIPropertyMetadata or FrameworkPropertyMetadata. Only PropertyMetadata exists in Silverlight, although conceivably you could derive from it. The WPF FrameworkPropertyMetadata provides a "flags" mechanism for information passing conventions, but Silverlight 5 does not support this.

• The AddOwner mechanism whereby an existing dependency property can be reregistered to a different owner type.

• The full set of settable properties on PropertyMetadata. Silverlight supports a GetMetadata method and a readable DefaultValue from PropertyMetadata as of Silverlight 3, but does not permit changing the metadata or retrieving the PropertyChangedCallback from metadata. Also absent in Silverlight are retrieval and analysis APIs for the property system such as the DependencyObjectType class. 

• The DependencyPropertyHelper utility and DependencyObject.GetLocalValueEnumerator.

• The Freezable and FreezableCollection classes. These are not strictly dependency property considerations, but these concepts/classes participate in the overall WPF property system and apply to certain scenarios such as custom animation types.

The Implementation Pattern of a Dependency Property

Examples of Silverlight dependency properties are: Control.Background, FrameworkElement.Width, and TextBox.Text, among many others. Each dependency property exposed by a class has a corresponding public static readonly field of type DependencyProperty exposed on that same class. That field is the identifier for the dependency property. The identifier field is named using a convention: the name of the dependency property with the string Property appended to it. For example, the corresponding DependencyProperty identifier field for the Control.Background property is Control.BackgroundProperty. The identifier stores the information about the dependency property as it was registered, and the identifier can then be used later for other operations involving the dependency property, such as calling SetValue.

As mentioned in Dependency Properties Overview, all dependency properties in Silverlight (except most attached properties) are also CLR properties because of the wrapper implementation. Therefore, from code, you can get or set dependency properties by calling the CLR accessors that serve as the wrappers in the same manner that you would use other CLR properties. As a consumer of established dependency properties, you do not typically use the DependencyObject methods GetValue and SetValue, which are the connection point to the underlying property system. Rather, the existing implementation of the Silverlight dependency properties will have already called GetValue and SetValue within the get and set accessors of the property, using the identifier field appropriately. If you implement a custom dependency property yourself, then you define the accessors for the CLR type system in a similar way.

In addition to providing ease of access to callers, the property wrappers are also useful for reporting the basic information about dependency properties to reflection or to static analysis. The property definition of the property wrapper is also where you place XAML-related CLR attributes such as ContentPropertyAttribute or TypeConverterAttribute; this is where that attribution is expected to be when custom dependency properties are consumed by the Silverlight XAML parser.

When Should You Implement a Dependency Property?

When you implement a read/write property on a class, so long as your class derives from DependencyObject, you have the option to back your property with a DependencyProperty identifier and thus to make it a dependency property. Making your Silverlight property a dependency property is not always necessary or appropriate and will depend on your needs. Sometimes, the typical technique of backing your property with a private CLR field is adequate. However, you should implement your property as a dependency property whenever you want the property to support one or more of the following Silverlight property system capabilities:

• You want the property to be settable in a style. For more information, see Customizing the Appearance of an Existing Control by Using a ControlTemplate.

• You want the property to be a property target that supports data binding. For more information about data binding dependency properties, see Data Binding.

• You want the property to support an animated value, using the Silverlight animation system. For more information, see Animation Overview.

• You want the Silverlight property system to report when the previous value of the property has been changed by actions taken by the property system itself, the environment, or the user, or by reading and using styles. Your property can specify a callback method that will be invoked each time the property system determines that your property value was definitively changed.

Checklist for Defining a Dependency Property

Defining a dependency property consists of four distinct concepts. These concepts are not necessarily strict procedural steps, because some of these are combined as single lines of code in the implementation:

• (Optional) Create property metadata for the dependency property. You need property metadata only if you want property-changed behavior or a metadata-based default value that can be restored by calling ClearValue.

• Register the property name with the property system, specifying an owner type and the type of the property value. Also specify the property metadata, if used, or null if you do not require property metadata.

• Define a DependencyProperty identifier as a public static readonly field on the owner type.

• Define a CLR wrapper property whose name matches the name of the dependency property field, minus the Property suffix, and also matches the name parameter from the Register(String, Type, Type, PropertyMetadata) call. Implement the CLR get and set accessors to connect the wrapper that provides the CLR exposure with the dependency property that backs it. (If you are defining an attached property, you generally omit the wrapper and instead write a different style of accessor that a XAML processor can use. For more information, see Attached Properties Overview.)

• (Optional) Place any XAML-related CLR attributes such as ContentPropertyAttribute or TypeConverterAttribute on the property definition (the outer definition, not the get-set implementations).

Registering the Property with the Property System

Public Shared ReadOnly AquariumGraphicProperty As DependencyProperty = DependencyProperty.Register("AquariumGraphic", GetType(Uri), GetType(AquariumObject), New PropertyMetadata(Nothing, New PropertyChangedCallback(AddressOf OnUriChanged)))

public static readonly DependencyProperty AquariumGraphicProperty = DependencyProperty.Register(
  "AquariumGraphic",
  typeof(Uri),
  typeof(AquariumObject),
  new PropertyMetadata(null,
      new PropertyChangedCallback(OnUriChanged)
  )
);

Dependency Property Name Conventions

There are established naming conventions regarding dependency properties that you should follow in all but exceptional circumstances.

The dependency property itself has a basic name (AquariumGraphic in the preceding example) that is given as the first parameter of DependencyProperty.Register. The name must be unique within each registering type, and the uniqueness scope includes any inherited members. Dependency properties inherited through base types are considered to be already part of the registering type; names of inherited properties cannot be registered again.

Caution:
Although the name you provide here can be any identifier that is accepted in CLR programming for a CLR field entity, you should anticipate that your dependency property might also need to be settable in XAML. In order to be settable in XAML, the name you choose must be a valid XAML name. For more information, see XamlName Grammar.

When you create the identifier field, combine the name of the property as you registered it with the suffix Property (AquariumGraphicProperty, for example). This field is your identifier for the dependency property, and it is used as an input for the SetValue and GetValue calls you make in your own CLR wrappers, by the property system, and potentially by XAML processors.

Note:
Defining the dependency property in the class body is the typical implementation, but it is also possible to define a dependency property in the class static constructor. This approach might make sense if you need more than one line of code to initialize the dependency property.

Implementing the Wrapper

Public Shared ReadOnly AquariumGraphicProperty As DependencyProperty = DependencyProperty.Register("AquariumGraphic", GetType(Uri), GetType(AquariumObject), New PropertyMetadata(Nothing, New PropertyChangedCallback(AddressOf OnUriChanged)))

Public Property AquariumGraphic() As Uri 
    Get 
        Return DirectCast(GetValue(AquariumGraphicProperty), Uri) 
    End Get 
    Set(ByVal value As Uri) 
        SetValue(AquariumGraphicProperty, value) 
    End Set 
End Property 

public static readonly DependencyProperty AquariumGraphicProperty = DependencyProperty.Register(
  "AquariumGraphic",
  typeof(Uri),
  typeof(AquariumObject),
  new PropertyMetadata(null,
      new PropertyChangedCallback(OnUriChanged)
  )
);
public Uri AquariumGraphic
{
    get { return (Uri)GetValue(AquariumGraphicProperty); }
    set { SetValue(AquariumGraphicProperty, value); }
}

XAML Loading and Dependency Properties

Property Metadata for a Custom Dependency Property

When property metadata is assigned to a dependency property, the same metadata is applied to all cases of the property on all object instances. In property metadata, you can specify two behaviors of the property:

• A default value that the property system assigns to all cases of the property.

• A static callback method that is invoked within the property system whenever the property value is changed.

Default Value

If it is not specified, the default value for a dependency property is null for a reference type, or the default of the type for a value type. The main reason that you might want to establish a default value is that this value is restored if you ever call ClearValue on the property. Establishing a default value on a per-property basis might be more convenient than the pattern of establishing default values in constructors, particularly for value types. However, for reference types, you should make sure that establishing a default value does not create an unintentional singleton pattern. You can use class constructors to set initial values for a reference type dependency property if you want a non-null value, but be aware that this would be considered a local value for purposes of dependency property precedence. It might be more appropriate to use a template for this purpose, if your class is templatable. Another way to avoid a singleton pattern but still provide a useful default is to expose a static property on the reference type that provides a suitable default for the values of that class.

Important Note:
Do not register a dependency property with the specific default value of UnsetValue. This will be confusing for property consumers and will have unintended consequences within the property system.

Property-Changed Callback

    Private Shared Sub OnUriChanged(ByVal d As DependencyObject, ByVal e As DependencyPropertyChangedEventArgs) 
        Dim sh As Shape = DirectCast(d, Shape) 
        Dim ib As New ImageBrush() 
        ib.ImageSource = New BitmapImage(TryCast(e.NewValue, Uri)) 
        sh.Fill = ib 
    End Sub 
End Class 

private static void OnUriChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
{
    Shape sh = (Shape)d;
    ImageBrush ib = new ImageBrush();
    ib.ImageSource = new BitmapImage(e.NewValue as Uri);
    sh.Fill = ib;
}

More Information About Custom Dependency Properties

Collection-Type Dependency Properties

Dependency Property Security Considerations

Dependency Properties and Class Constructors

See Also

Concepts