XAML 数据绑定诊断

处理 XAML 项目的开发人员通常需要检测并解决他们的应用程序中的 XAML 数据绑定失败。 现在，Visual Studio 2019 版本 16.8 或更高版本和 Visual Studio 2022 中提供了一些工具，可帮助在调试应用程序时找到这些令人烦恼的数据绑定失败。 常见绑定失败的示例：

• 绑定到不存在的属性名称：{Binding Wrong.Name}
• 绑定到类型错误的值，例如在需要枚举时却绑定到布尔值：Visibility="{Binding IsVisible}"

由于这些绑定是在运行时使用反射计算的，因此 XAML 编辑器并不总是能够捕获到它们，但生成仍会成功。 失败只在运行时发生。

以下文章中解释了 XAML 数据绑定：

• 对于 WPF：数据绑定概述 - WPF .NET
• 对于 UWP：数据绑定概述 - UWP 应用程序
• 对于 Xamarin.Forms：Xamarin.Forms 数据绑定 - Xamarin

绑定失败始终被写入 Visual Studio 中的调试输出窗口。 但是，在调试输出中很容易错过绑定失败，因为它包含了将绑定失败滚动到视图之外的其他调试信息。 下面是调试输出窗口中 WPF 绑定失败的一个示例：

绑定失败可能是窗口顶部的数百行，并且文本没有确切地告诉你是哪个绑定失败，你需要考虑这一点并进行搜索。

现在，通过 XAML 绑定失败工具窗口，可以清楚地看到哪些绑定失败，以及每个失败的相关数据，例如 XAML 中的文件位置。 此外，还有许多有用的功能，通过搜索、排序甚至打开 XAML 编辑器，将焦点设定在失败的绑定上，来调查失败的情况。

双击这些行可以打开绑定的源 XAML，如下图所示：

“XAML 绑定失败”工具窗口

在调试期间，可以使用“XAML 绑定失败”工具窗口。 若要打开该窗口，请转到“调试”>“Windows”>“XAML 绑定失败”。

或者，选择应用程序工具栏中的“绑定失败”按钮。 图标旁边的数字表示在工具窗口中显示的绑定失败次数。

如果工具窗口中没有绑定失败，图标将显示为灰色，旁边没有数字。 这在运行应用程序时很有用。 如果看到图标变为红色，并且旁边有数字，单击它可以快速跳转到工具窗口，查看发生了哪些绑定失败。 不需要一直关注 Visual Studio 工具窗口。 当有绑定失败时，图标将立即通知你。

“实时可视化树”工具窗口中也会显示类似的图标。

下面介绍“XAML 绑定失败”工具窗口的所有组件。

• 顶部的工具栏包含以下按钮：
  • 清除失败列表：如果你要在应用中显示新页面，并且想要查看是否显示任何绑定失败，此按钮非常有用。 当你启动新的调试会话时，该列表会自动清除。
  • 删除所选行：如果失败已修复或不相关，可以从列表中删除它。 如果绑定再次失败，已删除的行将再次显示。
  • 清除所有筛选器：如果列表中有任何筛选器（例如搜索文本），使用此按钮可以清除筛选器并显示完整列表。
  • 合并重复项：在项模板中，同一绑定通常会在一行中多次失败。 选择“合并重复项”按钮（周围带有轮廓）后，所有重复的失败都显示为一行。 “计数”列将显示失败发生的次数。
• 使用顶部角落的“搜索绑定失败”框，可以将失败筛选为仅包含特定文本的失败。
• 表列按顺序显示以下选项：
  • 一个显示行是错误还是警告的图标。
  • 如果支持在 XAML 中导航到失败的 {Binding}，则会有一个显示尖括号 <> 的图标。 请参阅支持的平台部分。
  • 数据上下文：这是绑定的源对象的类型名称
    • 请参阅 Binding.Source
  • 绑定路径：这是绑定的属性路径
    • 请参阅 Binding.Path
  • 目标：这是将设置绑定值的类型和属性名称。
    • 请参阅 BindingExpressionBase.Target 和 BindingExpressionBase.TargetProperty
  • 目标类型：这是绑定的目标属性的预期类型。
    • 请参阅 BindingExpressionBase.TargetProperty
  • 说明：此列包含有关绑定的确切失败的详细信息。
  • “文件”、“行”和“项目”：这是 XAML 中定义绑定的位置（如果已知）。
• 右键单击一行或多个选定的行将显示上下文菜单，其中包含用于显示/隐藏列或对列进行分组的标准选项。 其他选项如下：
  • 将某一行或某一列的所有文本复制到剪贴板。
  • “复制原始错误”将复制调试输出窗口中显示的文本。
  • 使用“查看源”将转到 XAML 中某个所选行的绑定源。
  • “重置列”将撤消对列可见性和排序的所有更改，快速恢复到最初显示的内容。

若要对列表进行排序，请单击任一列标题。 若要按额外的列对列表进行进一步排序，请按住 Shift 键并单击其他列标头。 若要选择显示哪些列和隐藏哪些列，请从快捷菜单中选择“显示列”。 若要更改列显示的顺序，请将任一列标题向左或向右拖动。

双击某行或按 Enter 导航到源后，可以按 F8 或 Shift+F8 在绑定失败列表中上下移动。 这与 Visual Studio 中显示列表的其他窗格类似。

受支持的平台

如果绑定失败写入调试输出，则大多数 XAML 平台都受支持。 一些平台向调试器提供额外的源信息，以便导航到源。

必须在 Visual Studio 中启用 XAML 热重载选项，才能正常导航到源。 此选项位于“工具”>“选项”>“调试”对话框中：

导航到源仅适用于 XAML 源文件中定义的绑定，不适用于通过代码创建的绑定。 可以清楚地看到哪些行支持导航到源。 如果第二列中没有尖括号图标，则不支持导航到源，如以下屏幕截图中突出显示的行所示：

对于 .NET Framework 中的 WPF，数据绑定失败必须显示在调试输出中，“XAML 绑定失败”窗格才能检测和显示它们。 此选项位于“工具”>“选项”>“调试”>“输出窗口”>“WPF 跟踪设置”对话框中。 如果设置为“关”或“严重”，数据绑定错误就不会写入调试输出，并且无法被检测到。 对于 .NET 5、.NET 6 和更高版本中的 WPF，数据绑定输出设置不会影响失败列表。

相关内容

• XAML 热重载