为何无法为UserControl的Object类型依赖属性内的控件命名？

我自定义了一个名为HeaderControl的UserControl，当往其ControlContent属性中放入带x:Name的Button时程序无法正常运行，不带x:Name则可以正常工作，以下是相关代码及问题分析：

自定义HeaderControl的C#代码 #

public partial class HeaderControl : UserControl
{
    public HeaderControl()
    {
        InitializeComponent();
       DataContext = this;
    }

    public static readonly DependencyProperty ControlContentProperty =
       DependencyProperty.Register(nameof(ControlContent), typeof(object), 
           typeof(HeaderControl), new PropertyMetadata(null));
    public object ControlContent
    {
        get { return (object)GetValue(ControlContentProperty); }
        set { SetValue(ControlContentProperty, value); }
    }
}

HeaderControl的XAML代码 #

<Grid Grid.Row="1">
     <ContentControl Content="{Binding ControlContent, ElementName=root}"/>
</Grid>

正常运行的使用示例（不带x:Name） #

<ctrl:HeaderControl >
    <ctrl:HeaderControl.ControlContent>
                <Button Content="Hallooo" FontSize="40"
                         Foreground="Black" Height="100"/>
    </ctrl:HeaderControl.ControlContent>
 </ctrl:HeaderControl>

出错的使用示例（带x:Name） #

<ctrl:HeaderControl >
    <ctrl:HeaderControl.ControlContent>
                <Button x:Name="Btn" Content="Hallooo" FontSize="40"
                         Foreground="Black" Height="100"/>
    </ctrl:HeaderControl.ControlContent>
 </ctrl:HeaderControl>

原因分析 #

给元素设置x:Name时，XAML编译器会尝试在当前XAML命名空间的代码隐藏类中生成对应的字段引用。但此处Button是作为ControlContent（类型为object的依赖属性）的值传入的，它的作用域属于父级页面/窗口的XAML，而普通的object类型依赖属性无法支持WPF的名称范围（Name Scope）传递机制，导致编译器生成字段时找不到对应的注册目标，最终引发错误。

简单来说，普通object类型的依赖属性无法承载带命名的UI元素，因为它不具备处理名称范围的能力。

解决办法 #

要让自定义控件的内容属性支持带x:Name的元素，有两种常用方案：

方案1：改用ContentControl基类 #

直接让HeaderControl继承ContentControl，利用其内置的Content属性来承载内容，这是WPF内容控件的标准实现方式：

public class HeaderControl : ContentControl
{
    public HeaderControl()
    {
        InitializeComponent();
    }
}

对应的XAML根元素改为ContentControl：

<ContentControl x:Class="YourNamespace.HeaderControl"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <Grid Grid.Row="1">
        <ContentPresenter Content="{TemplateBinding Content}"/>
    </Grid>
</ContentControl>

使用时直接嵌套元素即可，带x:Name的Button能正常工作：

<ctrl:HeaderControl >
    <Button x:Name="Btn" Content="Hallooo" FontSize="40"
            Foreground="Black" Height="100"/>
</ctrl:HeaderControl>

方案2：保留UserControl，修改依赖属性类型 #

如果必须保留UserControl基类，将ControlContent的类型从object改为UIElement，WPF会自动为UIElement类型处理名称范围：

public partial class HeaderControl : UserControl
{
    public HeaderControl()
    {
        InitializeComponent();
        DataContext = this;
    }

    public static readonly DependencyProperty ControlContentProperty =
       DependencyProperty.Register(nameof(ControlContent), typeof(UIElement), 
           typeof(HeaderControl), new PropertyMetadata(null));
    public UIElement ControlContent
    {
        get { return (UIElement)GetValue(ControlContentProperty); }
        set { SetValue(ControlContentProperty, value); }
    }
}

内容的提问来源于stack exchange，提问作者christophe etse