WPF DependencyProperty Patterns

Defining dependency properties for data binding, styling, animation, and property value inheritance.

Advanced Patterns: See ADVANCED.md for value inheritance, metadata override, and event integration.

1. DependencyProperty Overview

Standard CLR Property:
    private string _name;
    public string Name { get => _name; set => _name = value; }

DependencyProperty:
    public static readonly DependencyProperty NameProperty = ...
    public string Name { get => (string)GetValue(NameProperty); set => SetValue(NameProperty, value); }

Benefits:
    ✅ Data Binding
    ✅ Styling & Templating
    ✅ Animation
    ✅ Property Value Inheritance
    ✅ Default Values
    ✅ Change Notifications
    ✅ Value Coercion
    ✅ Validation

---

2. Basic DependencyProperty

2.1 Standard Registration

namespace MyApp.Controls;

using System.Windows;
using System.Windows.Controls;

public class MyControl : Control
{
    // 1. Register DependencyProperty
    public static readonly DependencyProperty TitleProperty = DependencyProperty.Register(
        name: nameof(Title),
        propertyType: typeof(string),
        ownerType: typeof(MyControl),
        typeMetadata: new PropertyMetadata(defaultValue: string.Empty));

    // 2. CLR property wrapper
    public string Title
    {
        get => (string)GetValue(TitleProperty);
        set => SetValue(TitleProperty, value);
    }
}

2.2 With FrameworkPropertyMetadata

public static readonly DependencyProperty ValueProperty = DependencyProperty.Register(
    name: nameof(Value),
    propertyType: typeof(double),
    ownerType: typeof(MyControl),
    typeMetadata: new FrameworkPropertyMetadata(
        defaultValue: 0.0,
        flags: FrameworkPropertyMetadataOptions.AffectsRender |
               FrameworkPropertyMetadataOptions.BindsTwoWayByDefault,
        propertyChangedCallback: OnValueChanged,
        coerceValueCallback: CoerceValue),
    validateValueCallback: ValidateValue);

public double Value
{
    get => (double)GetValue(ValueProperty);
    set => SetValue(ValueProperty, value);
}

---

3. FrameworkPropertyMetadataOptions

Flag	Description
None	No special behavior
AffectsMeasure	Triggers Measure pass on change
AffectsArrange	Triggers Arrange pass on change
AffectsRender	Triggers Render on change
Inherits	Value inherits to child elements
BindsTwoWayByDefault	Default binding mode is TwoWay

Common Combinations

// Read-only display property (AffectsRender)
new FrameworkPropertyMetadata(
    defaultValue: null,
    flags: FrameworkPropertyMetadataOptions.AffectsRender);

// Layout-affecting property (AffectsMeasure)
new FrameworkPropertyMetadata(
    defaultValue: 100.0,
    flags: FrameworkPropertyMetadataOptions.AffectsMeasure |
           FrameworkPropertyMetadataOptions.AffectsArrange);

// Two-way bindable property
new FrameworkPropertyMetadata(
    defaultValue: false,
    flags: FrameworkPropertyMetadataOptions.BindsTwoWayByDefault);

---

4. Callbacks

4.1 PropertyChangedCallback

public static readonly DependencyProperty IsActiveProperty = DependencyProperty.Register(
    nameof(IsActive),
    typeof(bool),
    typeof(MyControl),
    new PropertyMetadata(false, OnIsActiveChanged));

private static void OnIsActiveChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
{
    var control = (MyControl)d;
    var oldValue = (bool)e.OldValue;
    var newValue = (bool)e.NewValue;

    // Handle property change
    control.UpdateVisualState(newValue);
}

4.2 CoerceValueCallback

public static readonly DependencyProperty ProgressProperty = DependencyProperty.Register(
    nameof(Progress),
    typeof(double),
    typeof(ProgressControl),
    new FrameworkPropertyMetadata(
        0.0,
        propertyChangedCallback: null,
        coerceValueCallback: CoerceProgress));

private static object CoerceProgress(DependencyObject d, object baseValue)
{
    var value = (double)baseValue;

    // Clamp value to valid range
    if (value < 0.0) return 0.0;
    if (value > 100.0) return 100.0;

    return value;
}

4.3 ValidateValueCallback

public static readonly DependencyProperty CountProperty = DependencyProperty.Register(
    nameof(Count),
    typeof(int),
    typeof(MyControl),
    new PropertyMetadata(0),
    ValidateCount);  // Note: Not part of PropertyMetadata

private static bool ValidateCount(object value)
{
    var count = (int)value;

    // Return false to reject the value (throws exception)
    return count >= 0;
}

4.4 Callback Execution Order

1. ValidateValueCallback - Can reject value (throw exception)
2. CoerceValueCallback   - Can modify value
3. PropertyChangedCallback - Handle the change

---

5. Read-Only DependencyProperty

namespace MyApp.Controls;

using System.Windows;

public class StatusControl : Control
{
    // 1. Register read-only property key (private)
    private static readonly DependencyPropertyKey IsConnectedPropertyKey =
        DependencyProperty.RegisterReadOnly(
            nameof(IsConnected),
            typeof(bool),
            typeof(StatusControl),
            new FrameworkPropertyMetadata(false));

    // 2. Expose public DependencyProperty
    public static readonly DependencyProperty IsConnectedProperty =
        IsConnectedPropertyKey.DependencyProperty;

    // 3. Read-only CLR property
    public bool IsConnected => (bool)GetValue(IsConnectedProperty);

    // 4. Internal setter using key
    protected void SetIsConnected(bool value)
    {
        SetValue(IsConnectedPropertyKey, value);
    }
}

---

6. Attached Property

6.1 Defining Attached Property

namespace MyApp.Attached;

using System.Windows;

public static class GridHelper
{
    // Register attached property
    public static readonly DependencyProperty ColumnSpacingProperty =
        DependencyProperty.RegisterAttached(
            name: "ColumnSpacing",
            propertyType: typeof(double),
            ownerType: typeof(GridHelper),
            defaultMetadata: new FrameworkPropertyMetadata(
                0.0,
                FrameworkPropertyMetadataOptions.AffectsMeasure,
                OnColumnSpacingChanged));

    // Getter
    public static double GetColumnSpacing(DependencyObject obj)
    {
        return (double)obj.GetValue(ColumnSpacingProperty);
    }

    // Setter
    public static void SetColumnSpacing(DependencyObject obj, double value)
    {
        obj.SetValue(ColumnSpacingProperty, value);
    }

    private static void OnColumnSpacingChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
    {
        if (d is Grid grid)
        {
            UpdateGridSpacing(grid, (double)e.NewValue);
        }
    }

    private static void UpdateGridSpacing(Grid grid, double spacing)
    {
        // Implementation
    }
}

6.2 Using Attached Property in XAML

<Grid local:GridHelper.ColumnSpacing="10">
    <Grid.ColumnDefinitions>
        <ColumnDefinition Width="*"/>
        <ColumnDefinition Width="*"/>
        <ColumnDefinition Width="*"/>
    </Grid.ColumnDefinitions>
    <!-- Children -->
</Grid>

---

7. References

• Dependency Properties Overview - Microsoft Docs
• Custom Dependency Properties - Microsoft Docs
• Attached Properties Overview - Microsoft Docs