Attached Properties and Behaviors

What attached properties are

You have used attached properties since your first layout. Look at this XAML:

<Grid>
    <Grid.RowDefinitions>
        <RowDefinition Height="Auto" />
        <RowDefinition Height="*" />
    </Grid.RowDefinitions>

    <TextBlock Grid.Row="0" Text="Expenses" />
    <ListBox Grid.Row="1" />
</Grid>

TextBlock has no Row property. Neither does ListBox. The Row property belongs to Grid, but you set it on the children. That is an attached property: a property that one class defines and other objects carry. It is like a sticky note that the Grid gives to each child, saying “you go in row 1”. The child does not care what the note says. The Grid reads it during layout.

Other attached properties you already know:

<Button DockPanel.Dock="Top" Content="Add" />
<Ellipse Canvas.Left="40" Canvas.Top="20" Width="10" Height="10" />
<TextBox ToolTipService.ShowDuration="5000" ToolTip="Amount in your currency" />
<Button AutomationProperties.Name="Add expense" Content="+" />

The pattern is always OwnerClass.PropertyName="value".

Attached properties are built on the same system as the dependency properties from the last lesson. The difference is who defines them and who uses them.

Why write your own

Attached properties are not only for panels. They are one of the best tricks in WPF for adding a small feature to a control without subclassing it and without code-behind.

Say you want every amount box in CoinJar to select its text when it gets focus, so the user can type a new number straight away. You could handle GotFocus in the code-behind of every window. Or you could write this once:

<TextBox Text="{Binding Amount}"
         behaviors:TextBoxHelper.SelectAllOnFocus="True" />

and reuse it everywhere, even from a style. Code that hooks into a control’s events through an attached property is often called an attached behavior.

Writing an attached property, step by step

Attached properties usually live in a small static class. Create a Behaviors folder and add TextBoxHelper.cs.

Step 1: register it

using System.Windows;

namespace CoinJar.Behaviors;

public static class TextBoxHelper
{
    public static readonly DependencyProperty SelectAllOnFocusProperty =
        DependencyProperty.RegisterAttached(
            "SelectAllOnFocus",        // the name you write in XAML
            typeof(bool),              // the type of value
            typeof(TextBoxHelper),     // the owner class (this one)
            new PropertyMetadata(false, OnSelectAllOnFocusChanged));
}

It looks almost like DependencyProperty.Register, but you call RegisterAttached. The field name must be the property name plus Property.

Step 2: add the Get and Set methods

An attached property has no normal C# property wrapper, because the value is stored on someone else’s object. Instead you write two static methods:

public static bool GetSelectAllOnFocus(DependencyObject element) =>
    (bool)element.GetValue(SelectAllOnFocusProperty);

public static void SetSelectAllOnFocus(DependencyObject element, bool value) =>
    element.SetValue(SelectAllOnFocusProperty, value);

The names must be exactly Get + name and Set + name. The XAML parser looks for them. If you misspell one, XAML says the property does not exist.

Step 3: react when the value changes

The changed callback is where the behavior lives. When someone sets the value to True, you subscribe to the control’s events. When it goes back to False, you unsubscribe.

private static void OnSelectAllOnFocusChanged(
    DependencyObject d, DependencyPropertyChangedEventArgs e)
{
    if (d is not TextBox textBox) return;   // only works on text boxes

    if ((bool)e.NewValue)
    {
        textBox.GotKeyboardFocus += OnGotKeyboardFocus;
    }
    else
    {
        textBox.GotKeyboardFocus -= OnGotKeyboardFocus;
    }
}

private static void OnGotKeyboardFocus(object sender, KeyboardFocusChangedEventArgs e)
{
    ((TextBox)sender).SelectAll();
}

The full version in the code panel also handles a mouse click, because clicking into a TextBox normally places the cursor and clears the selection right after focus arrives.

Step 4: use it in XAML

Map the namespace and set the property:

<Window ...
        xmlns:behaviors="clr-namespace:CoinJar.Behaviors">

    <TextBox Text="{Binding Amount}"
             behaviors:TextBoxHelper.SelectAllOnFocus="True" />
</Window>

Attached properties work in styles

This is the big win. Because an attached property is a real dependency property, a style setter can set it. One setter gives the feature to every TextBox in the window:

<Window.Resources>
    <Style TargetType="TextBox">
        <Setter Property="behaviors:TextBoxHelper.SelectAllOnFocus" Value="True" />
    </Style>
</Window.Resources>

Put that style in App.xaml and the whole app gets it. You learned about this kind of shared style in Styles and Setters.

An attached property that holds a command

Attached properties can hold any type, including ICommand. That lets a view model react to something the control does not expose as a command. Here is one that runs a command when the user presses Enter:

public static class EnterKeyCommand
{
    public static readonly DependencyProperty CommandProperty =
        DependencyProperty.RegisterAttached(
            "Command", typeof(ICommand), typeof(EnterKeyCommand),
            new PropertyMetadata(null, OnCommandChanged));

    public static ICommand? GetCommand(DependencyObject element) =>
        (ICommand?)element.GetValue(CommandProperty);

    public static void SetCommand(DependencyObject element, ICommand? value) =>
        element.SetValue(CommandProperty, value);

    private static void OnCommandChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
    {
        if (d is not UIElement element) return;
        element.KeyDown -= OnKeyDown;            // never subscribe twice
        if (e.NewValue is not null) element.KeyDown += OnKeyDown;
    }

    private static void OnKeyDown(object sender, KeyEventArgs e)
    {
        if (e.Key != Key.Enter) return;
        ICommand? command = GetCommand((DependencyObject)sender);
        if (command?.CanExecute(null) == true)
        {
            command.Execute(null);
            e.Handled = true;
        }
    }
}

Now the quick add box in CoinJar can add an expense on Enter, and the logic stays in the view model from MVVM with CommunityToolkit.Mvvm:

<TextBox Text="{Binding NewTitle, UpdateSourceTrigger=PropertyChanged}"
         behaviors:EnterKeyCommand.Command="{Binding AddCommand}" />

Behaviors with Microsoft.Xaml.Behaviors.Wpf

Writing static classes for every small feature gets repetitive. Microsoft publishes a library that gives you a cleaner shape for the same idea. It is the open source successor of the old Blend SDK “Interactivity” library.

Install it:

dotnet add package Microsoft.Xaml.Behaviors.Wpf

At the time of writing that installs version 1.1.161. Then map its XAML namespace:

xmlns:b="http://schemas.microsoft.com/xaml/behaviors"

The library gives you two main tools: behaviors and triggers with actions.

Writing a behavior class

A behavior is a class that attaches to one control and adds something to it. You inherit from Behavior<T>, where T is the control type. The library gives you:

• AssociatedObject: the control you are attached to, already typed as T.
• OnAttached(): runs when the behavior is attached. Subscribe to events here.
• OnDetaching(): runs when it is removed. Unsubscribe here.

using System.Windows.Controls;
using System.Windows.Input;
using Microsoft.Xaml.Behaviors;

namespace CoinJar.Behaviors;

public class SelectAllOnFocusBehavior : Behavior<TextBox>
{
    protected override void OnAttached()
    {
        base.OnAttached();
        AssociatedObject.GotKeyboardFocus += OnGotKeyboardFocus;
    }

    protected override void OnDetaching()
    {
        AssociatedObject.GotKeyboardFocus -= OnGotKeyboardFocus;
        base.OnDetaching();
    }

    private void OnGotKeyboardFocus(object sender, KeyboardFocusChangedEventArgs e)
    {
        AssociatedObject.SelectAll();
    }
}

Compare it with TextBoxHelper. There is no registration code, no Get and Set methods and no type check, because T already says it is a TextBox. The behavior is also an instance, so it can keep its own fields.

You attach it with Interaction.Behaviors:

<TextBox Text="{Binding Amount}">
    <b:Interaction.Behaviors>
        <behaviors:SelectAllOnFocusBehavior />
    </b:Interaction.Behaviors>
</TextBox>

Turning any event into a command

The most common use of the library has nothing to do with writing behaviors. It is EventTrigger with InvokeCommandAction, which turns any event into a command call. Many controls do not have a Command property: a ListBox double click, a window Loaded event, a SelectionChanged. Without this you would need code-behind.

In CoinJar, double clicking an expense should open it for editing:

<ListBox ItemsSource="{Binding Expenses}"
         SelectedItem="{Binding SelectedExpense}"
         DisplayMemberPath="Title">
    <b:Interaction.Triggers>
        <b:EventTrigger EventName="MouseDoubleClick">
            <b:InvokeCommandAction Command="{Binding EditCommand}"
                                   CommandParameter="{Binding SelectedExpense}" />
        </b:EventTrigger>
    </b:Interaction.Triggers>
</ListBox>

EventName is the event as a string. InvokeCommandAction runs the command when the event fires. The view model just has the ordinary Edit relay command from Dialogs and Message Boxes:

[RelayCommand]
private void Edit(Expense? expense)
{
    if (expense is null) return;
    _dialogs.EditExpense(expense);   // opens the edit window
}

If you want the event arguments, set PassEventArgsToCommand="True". The command then receives the EventArgs object as its parameter. Use this sparingly: event args are UI types, and a view model that depends on them is harder to test.

Loading data when a view appears is another classic:

<b:Interaction.Triggers>
    <b:EventTrigger EventName="Loaded">
        <b:InvokeCommandAction Command="{Binding LoadCommand}" />
    </b:EventTrigger>
</b:Interaction.Triggers>

Attached property or behavior: which one?

Both do the same job, so pick by these rules:

Need it in a Style setter?            -> attached property
Need one value, like True or a number? -> attached property
Need state, several settings, or
cleaner code for something bigger?     -> Behavior<T>
Need "when this event fires, run
a command"?                             -> EventTrigger + InvokeCommandAction

The first rule matters most. Interaction.Behaviors is a collection, and you cannot fill it from a normal style setter. If you want a feature on every TextBox through a style, write it as an attached property. A common middle way is an attached property whose changed callback creates and attaches a behavior.

Common mistakes

• Wrong method names. GetSelectAllOnFocus and SetSelectAllOnFocus must match the registered name exactly. A typo gives an XAML error that the property was not found.
• Wrong owner type. The third argument of RegisterAttached is the class that declares the property (TextBoxHelper), not the control you attach it to.
• Using Register instead of RegisterAttached. It compiles, but XAML may refuse to set it on other element types.
• Forgetting to unsubscribe. If you add an event handler when the value becomes True, remove it when it becomes False, and remove it in OnDetaching for behaviors. Otherwise handlers pile up.
• Subscribing twice. If the callback can run more than once with a “turned on” value, remove the handler before adding it, as EnterKeyCommand does.
• Putting business logic in a behavior. Behaviors are for view mechanics: focus, selection, keys, scrolling. Saving an expense still belongs in the view model, reached through a command.
• Old namespaces. Old tutorials use System.Windows.Interactivity and xmlns:i="http://schemas.microsoft.com/expression/2010/interactivity". With the NuGet package the C# namespace is Microsoft.Xaml.Behaviors and the XAML namespace is http://schemas.microsoft.com/xaml/behaviors.

Quick recap

• An attached property is defined by one class and set on other objects, like Grid.Row on a child.
• Create one with DependencyProperty.RegisterAttached plus static GetX and SetX methods with exact names.
• A property changed callback can subscribe to the target’s events. This “attached behavior” adds features without subclassing or code-behind.
• Attached properties can be set from styles, so one setter can add a feature to every control of a type.
• Microsoft.Xaml.Behaviors.Wpf gives you Behavior<T> with AssociatedObject, OnAttached and OnDetaching.
• EventTrigger with InvokeCommandAction turns any event, such as MouseDoubleClick or Loaded, into a command call.
• Always unsubscribe from events you subscribe to, and keep business logic in view models.