Edit

XAML loading and dependency properties (WPF .NET)

  • Article

The Windows Presentation Foundation (WPF) implementation of its Extensible Application Markup Language (XAML) processor is inherently dependency property aware. As such, the XAML processor uses WPF property system methods to load XAML and process dependency property attributes, and entirely bypasses dependency property wrappers by using WPF property system methods like GetValue and SetValue. So, if you add custom logic to the property wrapper of your custom dependency property, it won't be called by the XAML processor when a property value is set in XAML.

Prerequisites

The article assumes a basic knowledge of dependency properties, and that you've read Dependency properties overview. To follow the examples in this article, it helps if you're familiar with Extensible Application Markup Language (XAML) and know how to write WPF applications.

WPF XAML loader performance

It's computationally less expensive for the WPF XAML processor to directly call SetValue to set the value of a dependency property, rather than use the property wrapper of a dependency property.

If the XAML processor did use the property wrapper, it would require inferring the entire object model of the backing code based only on the type and member relationships indicated in markup. Although the type can be identified from markup by using a combination of xmlns and assembly attributes, identifying the members, determining which members can be set as an attribute, and resolving supported property value types, would require extensive reflection using PropertyInfo.

The WPF property system maintains a storage table of dependency properties implemented on a given DependencyObject derived type. The XAML processor uses that table to infer the dependency property identifier for a dependency property. For example, by convention the dependency property identifier for a dependency property named ABC is ABCProperty. The XAML processor can efficiently set the value of any dependency property by calling the SetValue method on its containing type using the dependency property identifier.

For more information on dependency property wrappers, see Custom dependency properties.

Implications for custom dependency properties

The WPF XAML processor bypasses property wrappers and directly calls SetValue to set a dependency property value. So, avoid putting any extra logic in the set accessor of your custom dependency property because that logic won't run when a property value is set in XAML. The set accessor should only contain a SetValue call.

Similarly, aspects of the WPF XAML processor that get property values bypass the property wrapper and directly call GetValue. So, also avoid putting any extra logic in the get accessor of your custom dependency property because that logic won't run when a property value is read in XAML. The get accessor should only contain a GetValue call.

Dependency property with wrapper example

The following example shows a recommended dependency property definition with property wrappers. The dependency property identifier is stored as a public static readonly field, and the get and set accessors contain no code beyond the necessary WPF property system methods that back the dependency property value. If you have code that needs to run when the value of your dependency property changes, consider putting that code in the PropertyChangedCallback for your dependency property. For more information, see Property-changed callbacks.

// Register a dependency property with the specified property name,
// property type, owner type, and property metadata. Store the dependency
// property identifier as a public static readonly member of the class.
public static readonly DependencyProperty AquariumGraphicProperty =
    DependencyProperty.Register(
      name: "AquariumGraphic",
      propertyType: typeof(Uri),
      ownerType: typeof(Aquarium),
      typeMetadata: new FrameworkPropertyMetadata(
          defaultValue: new Uri("http://www.contoso.com/aquarium-graphic.jpg"),
          flags: FrameworkPropertyMetadataOptions.AffectsRender,
          propertyChangedCallback: new PropertyChangedCallback(OnUriChanged))
    );

// Property wrapper with get & set accessors.
public Uri AquariumGraphic
{
    get => (Uri)GetValue(AquariumGraphicProperty);
    set => SetValue(AquariumGraphicProperty, value);
}

// Property-changed callback.
private static void OnUriChanged(DependencyObject dependencyObject, 
    DependencyPropertyChangedEventArgs e)
{
    // Some custom logic that runs on effective property value change.
    Uri newValue = (Uri)dependencyObject.GetValue(AquariumGraphicProperty);
    Debug.WriteLine($"OnUriChanged: {newValue}");
}

' Register a dependency property with the specified property name,
' property type, owner type, and property metadata. Store the dependency
' property identifier as a public static readonly member of the class.
Public Shared ReadOnly AquariumGraphicProperty As DependencyProperty =
    DependencyProperty.Register(
        name:="AquariumGraphic",
        propertyType:=GetType(Uri),
        ownerType:=GetType(Aquarium),
        typeMetadata:=New FrameworkPropertyMetadata(
            defaultValue:=New Uri("http://www.contoso.com/aquarium-graphic.jpg"),
            flags:=FrameworkPropertyMetadataOptions.AffectsRender,
            propertyChangedCallback:=New PropertyChangedCallback(AddressOf OnUriChanged)))

' Property wrapper with get & set accessors.
Public Property AquariumGraphic As Uri
    Get
        Return CType(GetValue(AquariumGraphicProperty), Uri)
    End Get
    Set
        SetValue(AquariumGraphicProperty, Value)
    End Set
End Property

' Property-changed callback.
Private Shared Sub OnUriChanged(dependencyObject As DependencyObject,
                                e As DependencyPropertyChangedEventArgs)
    ' Some custom logic that runs on effective property value change.
    Dim newValue As Uri = CType(dependencyObject.GetValue(AquariumGraphicProperty), Uri)
    Debug.WriteLine($"OnUriChanged: {newValue}")
End Sub

See also