共用方式為

Visual Studio 偵錯工具的自訂資料視覺化檢視 (.NET)

  • 發行項

重要

從 Visual Studio 2022 17.9 版開始，現在可以使用新的 VisualStudio.Extensibility 模型，以 .NET 6.0+ 撰寫執行跨處理序的視覺化檢視。 我們鼓勵視覺化檢視作者參考建立 Visual Studio 偵錯工具視覺化檢視的新文件，除非他們想支援舊版 Visual Studio，或想要將自訂視覺化檢視當做程式庫 DLL 的一部分發佈。

「視覺化檢視」是 Visual Studio 偵錯工具使用者介面的一部分，其會以適合資料類型的方式顯示變數或物件。 例如，點陣圖視覺化檢視解譯點陣圖結構並顯示其所代表的圖形。 除了檢視資料外，有些視覺化檢視也能讓您修改資料。 在偵錯工具中，視覺化檢視是以放大鏡圖示 VisualizerIcon 表示。 您可以在 DataTip、偵錯工具 [監看式] 視窗或 [快速監看式] 對話方塊中選取圖示，然後選取對應物件的適當視覺化檢視。

除了標準內建視覺特效播放器之外，還可以從 Microsoft、第三方和社群下載更多視覺特效播放器。 您也可以撰寫自己的視覺化檢視並將其安裝在 Visual Studio 偵錯工具中。

本文提供視覺化檢視建立的高階概觀。 如需詳細指示，請改為參閱下列文章：

注意

通用 Windows 平台 (UWP) 和 Windows 8.x 應用程式不支援自訂視覺特效播放器。

概觀

您可以為任何受控類別的物件撰寫自訂視覺化檢視，除了 Object 和 Array 以外。

偵錯工具視覺化檢視的架構有兩個部分：

  • 「偵錯工具端」在 Visual Studio 偵錯工具內執行，以及建立並顯示視覺化檢視使用者介面。

    因為 Visual Studio 會在 .NET Framework Runtime 上執行，所以此元件必須針對 .NET Framework 撰寫。 基於這個理由，無法針對 .NET Core 撰寫它。

  • 「偵錯項目端」會在 Visual Studio 正在偵錯的處理序 (亦即「偵錯項目」) 中執行。 要視覺化的資料物件 (例如，String 物件) 會存在於偵錯項目處理序中。 偵錯項目端會將物件傳送至偵錯工具端，以在您所建立的使用者介面中顯示該物件。

    您建置此元件的執行階段應該符合將執行偵錯項目處理序的執行階段，也就是 .NET Framework 或 .NET Core。

偵錯工具端會從實作 IVisualizerObjectProvider 介面的「物件提供者」收到資料物件。 偵錯項目端會透過衍生自 VisualizerObjectSource 的「物件來源」傳送此物件。

物件提供者也可以將資料送回物件來源，讓您撰寫可編輯資料的視覺化檢視。 您可覆寫物件提供者來與運算式評估工具和物件來源交談。

偵錯項目端和偵錯工具端會透過 Stream 方法彼此通訊，該方法會將資料物件序列化為 Stream 並將 Stream 還原序列化回資料物件。

只有在類型是開放式類型時，才能為泛型類型撰寫視覺化檢視。 這項限制與使用 DebuggerTypeProxy 屬性時的限制相同。 如需詳細資訊，請參閱使用 DebuggerTypeProxy 屬性。

自訂視覺特效播放器會有安全性考量。 請參閱視覺化檢視安全性考量。

建立偵錯工具端使用者介面

若要在偵錯工具端建立視覺化檢視使用者介面，您可建立繼承自 DialogDebuggerVisualizer 的類別，並覆寫 Microsoft.VisualStudio.DebuggerVisualizers.DialogDebuggerVisualizer.Show 方法顯示此介面。 您可以使用 IDialogVisualizerService，在您的視覺化檢視中顯示 Windows 表單、對話方塊和控制項。

  1. 請使用 IVisualizerObjectProvider 方法，取得偵錯工具端的視覺化物件。

  2. 建立繼承自 DialogDebuggerVisualizer 的類別。

注意

由於下列章節所述的安全性問題，從 Visual Studio 2022 17.11 版開始，視覺化檢視將無法在基底類別建構函式中指定 Legacy 格式器原則。 從現在開始，視覺化檢視只能使用 JSON 序列化在偵錯工具和偵錯項目端元件之間通訊。

  1. 覆寫 Microsoft.VisualStudio.DebuggerVisualizers.DialogDebuggerVisualizer.Show 方法以顯示介面。 使用 IDialogVisualizerService 方法以在您的介面中顯示 Windows 表單、對話方塊和控制項。

  2. 套用 DebuggerVisualizerAttribute，並提供要顯示的視覺化檢視 (DialogDebuggerVisualizer)。

.NET 5.0+ 的特殊偵錯工具端考量

根據預設，自訂視覺化檢視會使用 BinaryFormatter 類別透過二進位序列化，在「偵錯項目」端與「偵錯工具」端之間傳輸資料。 不過，由於其「無法修復」的弱點相關安全性考量，這種序列化正在 .NET 5 和更新版本中受到限制。 此外，其已在 ASP.NET Core 5 中標示為完全過時，而且其使用方式將會如 ASP.NET Core 文件所述擲回。 本節說明您應該採取的步驟，以確保此案例中仍支援視覺化檢視。

  • 基於相容性考量，在上一節中覆寫的 Show 方法仍會接受 IVisualizerObjectProvider。 不過，從 Visual Studio 2019 16.10 版開始，其類型實際上是 IVisualizerObjectProvider3。 因此，請將 objectProvider 物件轉換成已更新的介面。

  • 將命令或資料等物件傳送至「偵錯項目端」時，使用 IVisualizerObjectProvider2.Serialize 方法將其傳遞至串流時，其會根據「偵錯項目」處裡序的執行階段判斷要使用的最佳序列化格式。 然後，將串流傳遞至 IVisualizerObjectProvider2.TransferData 方法。

  • 如果「偵錯項目端」視覺化檢視元件需要將任何項目傳回給「偵錯工具端」，其會位於 TransferData 方法所傳回的 Stream 物件中。 IVisualizerObjectProvider2.GetDeserializableObjectFrom使用 方法從中取得IDeserializableObject實例，並視需要加以處理;或者，如果它是您知道如何還原串行化的型別，請使用 DeserializeFromJson 。

請參閱 .NET 5.0+ 的特殊偵錯項目端考量一節，以了解不支援使用二進位序列化時，「偵錯項目端」需要哪些其他變更。

注意

如果您想要有關此問題的詳細資訊，請參閱 BinaryFormatter 安全性指南。

建立偵錯項目端的視覺化檢視物件來源

在偵錯工具端程式碼中，編輯 DebuggerVisualizerAttribute，並提供要視覺化的類型 (偵錯項目端物件來源) (VisualizerObjectSource)。 Target 屬性會設定物件來源。 如果您忽略了物件來源，視覺化檢視將使用預設的物件來源。

偵錯項目端程式碼包含已視覺化的物件來源。 資料物件可以覆寫 VisualizerObjectSource 的方法。 如果您想要建立一個獨立的視覺化檢視，則需要偵錯項目端 DLL。

在偵錯項目端程式碼中：

  • 若要讓視覺化檢視編輯資料物件，物件來源必須繼承自 VisualizerObjectSource 並覆寫 TransferData 或 CreateReplacementObject 方法。

  • 如果您需要在視覺化檢視中支援多重目標，您可以在偵錯項目端專案檔案中使用下列目標 Framework Moniker (TFM)。

    <TargetFrameworks>net20;netstandard2.0;netcoreapp2.0</TargetFrameworks>

    這些是唯一支援的 TFM。

.NET 5.0+ 的特殊偵錯項目端考量

重要

因為預設所使用的基礎二進位序列化方法的相關安全性考量，視覺化檢視可能需要其他步驟，才能從 .NET 5.0 開始運作。 請先閱讀這一節，再繼續進行。

  • 如果視覺化檢視實作 TransferData 方法，請使用最新版的 VisualizerObjectSource 中可用的新增 GetDeserializableObject 方法。 其傳回的 IDeserializableObject 有助於判斷物件的序列化格式 (二進位或 JSON) 以及還原序列化基礎物件，以便使用它。

  • 如果「偵錯項目端」將資料傳回到「偵錯工具端」當作 TransferData 呼叫的一部分，請透過 Serialize 方法序列化對「偵錯工具端」串流的回應。

相關內容