Post
Ask Question

Dependency Properties in WPF: Benefits, Usage, and Examples in C#

A dependency property is defined as a property supported by the Windows Presentation Foundation (WPF) property system in contrast to a conventional .NET field or property. This design facilitates optimal memory utilization and offers automatic notifications for changes, simplifying the development of dynamic, data-driven applications.

Advantages of Dependency Properties

  1. Data Binding: Facilitates seamless two-way binding between the user interface and underlying data.
  2. Styling: Permits the configuration of properties through styles or themes.
  3. Animation: Enables the animation of properties utilizing WPF’s animation capabilities.
  4. Value Inheritance: Allows child elements to inherit property values from their parent elements.
  5. Change Notification: Automatically alerts the system to changes in property values, eliminating the need for manual event management.
  6. Memory Efficiency: Properties are managed in a more memory-efficient manner compared to standard properties, minimizing memory usage for controls with numerous properties.

A dependency property is typically established within a class that inherits from DependencyObject, and it is registered through the DependencyProperty.Register method.

To establish a dependency property, it is common practice to define it within a class that inherits from DependencyObject. The registration of the property is accomplished through the DependencyProperty.Register method.

Step 1. For instance, consider the creation of a custom WPF control that includes a HeaderTitle property designated as a dependency property.

using System.Windows;
using System.Windows.Controls;
namespace DependencyPropertyExample
{
    /// <summary>
    /// Interaction logic for EmployeeDetails.xaml
    /// </summary>
    public partial class EmployeeDetails : UserControl
    {
        public EmployeeDetails()
        {
            InitializeComponent();
        }
        // Register the dependency property
        public static readonly DependencyProperty TitleProperty =
            DependencyProperty.Register(
                "HeaderTitle",                          // Name of the property
                typeof(string),                         // Property type
                typeof(EmployeeDetails),                // Owner type (this class)
                new PropertyMetadata("Default Title",   // Default value
                new PropertyChangedCallback(OnTitleChanged)) // Callback when value changes
            );
        // CLR Wrapper for the dependency property
        public string HeaderTitle
        {
            get { return (string)GetValue(TitleProperty); }
            set { SetValue(TitleProperty, value); }
        }
        // Callback method to handle changes in the Title property
        private static void OnTitleChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
        {
            var control = d as EmployeeDetails;
            // Perform actions when the Title property changes
            MessageBox.Show($"Title changed from {e.OldValue} to {e.NewValue}");
        }
    }
}

Key Elements of the Example

  • Property Registration: The property is defined using DependencyProperty.Register, which requires several parameters such as the property name, its type, the owner class, and the default value.
  • Property Metadata: We include property metadata that outlines the default value and an optional callback method (OnTitleChanged) that is executed whenever the property value is modified.
  • CLR Wrapper: Although the property is supported by the dependency system, a CLR property wrapper (HeaderTitle) is implemented to offer a more intuitive syntax for accessing and modifying the property value in C# code.
  • Callback Mechanism: When the property value is altered, the OnTitleChanged method is activated, enabling us to respond to these changes (for instance, by displaying a notification when the title is updated).

Step 2. Utilizing the Title Dependency Property in XAML At this point, you are able to implement the Title dependency property within XAML.

<Window x:Class="DependencyPropertyExample.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
        xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
        xmlns:local="clr-namespace:DependencyPropertyExample"
        mc:Ignorable="d"
        Title="MainWindow" Height="450" Width="800">
    <Grid>
        <StackPanel Orientation="Vertical">
            <TextBox Text="{Binding HeaderTitleProperty, Mode=TwoWay, UpdateSourceTrigger=PropertyChanged}" 
                     Height="40" Margin="20" />          
            <Border BorderBrush="Gray" BorderThickness="4" Height="300" Margin="0,50,0,0">
                <local:EmployeeDetails HeaderTitle="{Binding HeaderTitleProperty, Mode=TwoWay, UpdateSourceTrigger=PropertyChanged}" />
            </Border>
        </StackPanel>
    </Grid>

</Window>

Default title

Step 3. When executing the code, any input entered into the TextBox will result in the changes being reflected, as shown below.

Textbox

Dependency Properties application scenario

  • Data Binding Capability: The Title property allows for straightforward data binding, rendering it particularly suitable for MVVM (Model-View-ViewModel) applications. 
    <local:MyCustomControl 
    Title="{Binding MyViewModelTitle}" 
/>
  • Styling Assistance: The property is capable of being styled, enabling customization in accordance with the theme or style configurations. 
    <Style TargetType="local:MyCustomControl">
    <Setter Property="Title" Value="Styled Title" />
</Style>
  • Animation Support: The Title property can be animated through WPF animations. 
    <Storyboard>
    <StringAnimationUsingKeyFrames Storyboard.TargetProperty="Title">
        <DiscreteStringKeyFrame Value="New Title" KeyTime="0:0:2" />
    </StringAnimationUsingKeyFrames>
</Storyboard>
  • Value Inheritance: If HeaderTitle were inheritable, child elements could inherit the HeaderTitle value set at a parent level.

If a property such as HeaderTitle were designed to be inheritable, it would allow for a single assignment on a parent container, enabling all child elements to adopt that value unless they specify an alternative. This approach minimizes redundant coding and streamlines the management of uniform property values across various controls.

In examining an inheritable dependency property named HeaderTitle within a custom UserControl, it is important to note that if this property is designated as inheritable, it can be established at the highest level. Consequently, all descendant elements, including TextBlocks, will automatically inherit the value of HeaderTitle.

An illustration to clarify this situation

Step 1. Creating an Inheritable Dependency Property.

Use the FrameworkPropertyMetadataOptions.Inherits option to make a dependency property inheritable.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Windows;
namespace DependencyPropertyExample
{
    public class CustomControl : DependencyObject
    {
        // Registering an attached dependency property
        public static readonly DependencyProperty HeaderTitleProperty =
            DependencyProperty.RegisterAttached(
                "HeaderTitle",                // Property Name
                typeof(string),               // Property Type
                typeof(CustomControl),        // Owner Type
                new FrameworkPropertyMetadata(
                    string.Empty, 
                    FrameworkPropertyMetadataOptions.Inherits));

        // Getter method for the attached property
        public static string GetHeaderTitle(DependencyObject obj)
        {
            return (string)obj.GetValue(HeaderTitleProperty);
        }

        // Setter method for the attached property
        public static void SetHeaderTitle(DependencyObject obj, string value)
        {
            obj.SetValue(HeaderTitleProperty, value);
        }
    }
}

Step 2. Using the Inheritable Property in XAML.

<Window x:Class="DependencyPropertyExample.InheritableWindowForm"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
        xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
        xmlns:local="clr-namespace:DependencyPropertyExample"
        mc:Ignorable="d"
        Title="Inheritable Dependency Property Example" Height="300" Width="300">

    <StackPanel local:CustomControl.HeaderTitle="Welcome to WPF!">
        <TextBlock Text="{Binding RelativeSource={RelativeSource Self}, Path=(local:CustomControl.HeaderTitle)}" />
        <TextBlock Text="{Binding RelativeSource={RelativeSource Self}, Path=(local:CustomControl.HeaderTitle)}" />
        <Button Content="{Binding RelativeSource={RelativeSource Self}, Path=(local:CustomControl.HeaderTitle)}" />
    </StackPanel>

</Window>

Explanation of the above code

  • CustomControl.cs: Defines the attached dependency property HeaderTitle using DependencyProperty.RegisterAttached. It includes both getter and setter methods.
  • MainWindow.xaml
    • The StackPanel sets the attached property locally as CustomControl.HeaderTitle="Welcome to WPF!".
    • Child elements (two TextBlocks and a Button) use RelativeSource binding to bind their Text or Content to the parent's HeaderTitle property.
    • The AncestorType=StackPanel ensures that each child element looks up the visual tree to the parent StackPanel and retrieves the HeaderTitle value.
  • View of implementation

When to Use Dependency Properties?

  • Dependency properties should be utilized when developing custom controls in WPF that require the utilization of WPF's sophisticated features, including data binding, animation, styling, or property value inheritance.
  • They are also appropriate when efficient property change notifications are necessary, eliminating the need for manual implementation of INotifyPropertyChanged.
  • Additionally, dependency properties are essential for properties that must adapt to styles and themes within WPF applications.


Similar Articles