为UserControl设置ImageSource不生效，抽取公共控件后图片不显示

这是WPF自定义控件开发中最常遇到的两个绑定断点：

• 定义的ImageSource是普通CLR属性，无法作为WPF绑定的目标。WPF绑定系统仅支持依赖属性作为绑定目标，即便外部调用时给这个普通属性赋了值，绑定流程也不会感知到属性变化，内部Image元素和这个属性完全没有建立关联。
• 内部Image的绑定没有指定来源，默认会顺着视觉树查找当前元素的DataContext，通常最终会匹配到外部窗口/页面的ViewModel，根本不会定位到UserControl自身定义的ImageSource属性。

• 将原有普通CLR属性替换为依赖属性，后台实现参考：

public partial class TitleUC : UserControl
{
    public ImageSource ImageSource
    {
        get { return (ImageSource)GetValue(ImageSourceProperty); }
        set { SetValue(ImageSourceProperty, value); }
    }

    public static readonly DependencyProperty ImageSourceProperty =
        DependencyProperty.Register(
            nameof(ImageSource), 
            typeof(ImageSource), 
            typeof(TitleUC), 
            new PropertyMetadata(default(ImageSource)));

    public TitleUC()
    {
        InitializeComponent();
    }
}

• 修改UserControl内部Image的绑定，指定绑定源为当前UserControl本身，两种等效写法可选：
  1. 通过RelativeSource指定查找的祖先类型为UserControl：

  <Image 
      Source="{Binding ImageSource, RelativeSource={RelativeSource AncestorType=UserControl}}" 
      Width="20" 
      Height="20" />
  

  2. 给UserControl根节点设置唯一名称，通过ElementName绑定：
     首先在UserControl的根标签添加x:Name="RootControl"，再把Image的绑定写为：

  <Image 
      Source="{Binding ImageSource, ElementName=RootControl}" 
      Width="20" 
      Height="20" />
  

• 原有外部调用代码无需调整，WPF内置的类型转换器会自动将传入的字符串图片路径转换为对应的ImageSource实例：

<uc:TitleUC x:Name="TitleBar" ImageSource="/Images/MainWindow/Label.png" />

• 直接查看Visual Studio的输出窗口，WPF绑定流程失败时会在这里输出带详细原因的红色错误日志，可快速定位是属性路径不匹配、还是绑定源为null。
• 给绑定附加PresentationTraceSources.TraceLevel=High属性，输出绑定从查找源到匹配值的全流程日志，排查绑定链路的效率远高于手动打断点：

<Image 
    Source="{Binding ImageSource, RelativeSource={RelativeSource AncestorType=UserControl}, PresentationTraceSources.TraceLevel=High}" 
    Width="20" 
    Height="20" />

• 额外排查资源配置：确认图片文件的生成操作设置为「资源」，否则哪怕绑定链路完全正常，也会因为资源加载失败无法渲染图片。
• 避坑提醒：不要在UserControl的构造函数中写this.DataContext = this，这会破坏WPF原生的DataContext继承机制，导致外部使用该控件时，面向外部的绑定全部失效。

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