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
• 針對 .NET MAUI：.NET MAUI 數據系結

系結失敗一律會寫入 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
  • 描述：此數據行包含系結完全失敗的詳細資訊。
  • File、Line和 Project：如果已知，這是定義系結之 XAML 中的位置。
• 按右鍵選取的列或多列，即會顯示一個右鍵選單，並有標準選項來顯示/隱藏欄或將欄分組。 其他選項如下：
  • 將所有文字從數據列複製，或只將單一數據行複製到剪貼簿。
  • 複製原始錯誤會將錯誤訊息複製到除錯輸出視窗中。
  • 檢視原始碼會導向到 XAML 中的綁定原始碼，適用於選定的其中一列。
  • 重置欄位會撤銷所有欄位可見性和排序的變更，快速回到最初顯示的狀態。

若要排序列表，請點擊任何資料行標頭。 若要再按額外的數據行排序，請按住 Shift 鍵，然後按兩下另一個數據行標頭。 若要選取要顯示哪些資料行，以及隱藏哪些數據行，請從快捷方式功能表選擇 [顯示資料行]。 若要變更顯示數據行的順序，請將任何數據行標頭拖曳到左側或右側。

按兩下某一行或按 Enter 導航到來源之後，您可以按 F8 或 Shift+F8，以向下或向上移動綁定失敗清單。 這就像 Visual Studio 中顯示清單的其他窗格一樣。

支援的平臺

如果綁定失敗會寫入偵錯輸出，則大多數的 XAML 平台會受到支援。 某些平臺會提供額外的來源資訊給調試程式，以允許流覽至來源。

平臺	支援	導航到被支援的來源
WPF .NET 架構	是的	不
WPF .NET 5.0 RC2+	是的	是的
UWP	是的	不
WinUI3 桌面	是的	不
MAUI （多平臺應用程式 UI）	是的	不
Xamarin 4.5.0.266-pre3+	是的	是的
在 4.5.0.266-pre3 之前 Xamarin	不	不

為了支援導向來源，必須在 Visual Studio 啟用 XAML 熱載入功能。 在 工具>選項 面板中，展開 「所有設定>除錯>XAML 熱載入 」區塊，並選擇 啟用 XAML 熱重載 勾選框。

流覽至來源僅適用於 XAML 原始程式檔中定義的系結，而不是透過程式代碼建立的系結。 您可以清楚地看到哪些數據列支援瀏覽至來源。 如果第二個數據行中沒有角括弧圖示，則不支援巡覽至來源，例如在下列螢幕快照中反白顯示的數據列：

針對 .NET Framework 中的 WPF，數據系結失敗必須顯示在 [XAML 系結失敗] 窗格的偵錯輸出中，才能偵測並顯示它們。 在工具>選項面板中的所有設定>除錯>輸出視窗>WPF 追蹤設定區段設定資料綁定。

如果設定值是 關閉 或 關鍵，資料綁定錯誤就不會寫入除錯輸出，無法被偵測到。 在 .NET 5、.NET 6 和更新版本中使用 WPF 時，數據系結輸出設定不會影響失敗清單。

相關內容

• XAML 熱重載