如何创建用户控件库？跨方案使用遇XAML解析异常问题

1. 检查控件库输出类型与引用方式 #

• 确保控件库是WinUI 3 Class Library（而非普通.NET类库），跨解决方案引用优先用项目引用，不要直接复制DLL文件。如果必须用DLL，需同时将控件库同目录下的pri资源索引文件复制到引用项目的输出目录，XAML解析依赖该文件加载资源。

2. 验证XAML命名空间声明 #

• 在引用项目的XAML中，确认命名空间声明完全匹配控件库的实际命名空间（大小写一致）：

  xmlns:custom="using:你的控件库命名空间"
  

3. 排查控件库内资源引用 #

• 控件库中本地资源（图片、样式字典等）的生成操作需设为Content，复制到输出目录设为如果较新则复制。
• 资源引用建议改用ms-appx:///绝对路径，避免跨解决方案时相对路径失效：

  <Image Source="ms-appx:///你的控件库命名空间/Assets/Icon.png"/>
  

4. 检查控件初始化逻辑 #

• 控件构造函数中，InitializeComponent()方法必须放在最前面，避免在XAML解析前执行可能抛出异常的代码（如访问未初始化的依赖属性）。
• 确认依赖属性注册参数完整、元数据设置合理，错误的属性注册会直接触发XAML解析异常。

5. 获取详细错误日志 #

• 在引用项目的App.xaml.cs的OnLaunched方法中添加异常捕获，输出内部错误信息定位问题：

  protected override void OnLaunched(LaunchActivatedEventArgs args)
  {
      try
      {
          // 原有启动代码
      }
      catch (XamlParseException ex)
      {
          System.Diagnostics.Debug.WriteLine($"XAML解析详细错误: {ex.InnerException?.Message ?? ex.Message}");
      }
  }
  

6. 清理重建解决方案 #

• 同时删除控件库和引用项目的bin、obj目录，先重新生成控件库，再生成引用项目，避免旧缓存文件导致资源不匹配。

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