逐步解說：在 C# 中撰寫視覺化檢視

發行項
10/31/2023

本逐步解說顯示如何使用 C# 撰寫簡易的視覺化檢視。您在本逐步解說中建立的視覺化檢視會使用 Windows Form 顯示字串的內容。這個簡單的字串視覺化檢視本身並不特別有用，但其會顯示您必須遵循的基本步驟，才能為其他資料類型建立更有用的視覺化檢視。

注意

根據目前使用的設定與版本，您所看到的對話方塊與功能表命令可能會與 [說明] 中所描述的不同。若要變更您的設定，請移至 [工具] 功能表，然後選擇 [匯入和匯出設定]。如需詳細資訊，請參閱重設設定。

視覺化檢視的程式碼必須放置在偵錯工具讀取的 DLL 檔案中。因此，第一步就是為 DLL 建立類別庫專案。

手動建立視覺化檢視

請完成下列工作以建立視覺化檢視。

建立類別庫專案

若要建立新的類別庫專案，請選取 [檔案]>[新增]>[專案]。
在語言下拉式清單中，選取 [C#]。
在搜尋方塊中，輸入類別庫。選取 [類別庫 (.NET Framework)]，然後選取 [下一步]。
在對話方塊中，輸入名稱 MyFirstVisualizer，然後選取 [建立]。

針對視覺化檢視專案，請確定您選取 .NET Framework 類別庫，而不是 .NET。雖然視覺化檢視必須是 .NET Framework，但呼叫應用程式可以是 .NET。

建立類別庫之後，您必須新增 Microsoft.VisualStudio.DebuggerVisualizers.DLL 檔案的參考，才能使用該處定義的類別。新增參考之前，您必須重新命名某些類別，使其使用有意義的名稱。

重新命名 Class1.cs 和新增 Microsoft.VisualStudio.DebuggerVisualizers

在 [方案總管] 中，以滑鼠右鍵按一下 [Class1.cs]，然後選取捷徑功能表上的 [重新命名]。
將名稱從 Class1.vb 變更為有意義的名稱，例如 DebuggerSide.cs。

注意

Visual Studio 會自動變更 DebuggerSide.vb 中的類別宣告，以符合新的檔案名稱。如果您看到完成動作的提示，請選取 [是]。
在 [方案總管] 中，以滑鼠右鍵按一下 [參考]，然後選擇捷徑功能表上的 [新增參考]。
在 [新增參考] 對話方塊的 [瀏覽] 索引標籤上，選取 [瀏覽] 並尋找 Microsoft.VisualStudio.DebuggerVisualizers.DLL。

您可以在 Visual Studio 安裝目錄的 <Visual Studio 安裝目錄>\Common7\IDE\PublicAssemblies 子目錄中，找到 DLL。
選取 [確定]。
在 DebuggerSide.cs 中，將下列內容新增至 using 指示詞：
```
using Microsoft.VisualStudio.DebuggerVisualizers;
```

現在，您可以準備建立偵錯工具端的程式碼了。這個程式碼會在偵錯工具內執行，以顯示您要視覺化的資訊。首先，您必須變更 DebuggerSide 物件的宣告，以設定從基底類別 DialogDebuggerVisualizer 進行的繼承。

從 DialogDebuggerVisualizer 繼承

在 DebuggerSide.vb 中，移至下列程式碼：
```
public class DebuggerSide
```
將程式碼變更為：
```
public class DebuggerSide : DialogDebuggerVisualizer
```
DialogDebuggerVisualizer 含有一個您必須覆寫的抽象方法 (Show)。

覆寫 DialogDebuggerVisualizer.Show 方法

在 public class DebuggerSide 中新增下列方法：

protected override void Show(IDialogVisualizerService windowService, IVisualizerObjectProvider objectProvider)
{
}

Show 方法中包含實際建立視覺化檢視對話方塊 (或其他使用者介面) 的程式碼，並會在偵錯工具中顯示已傳遞至視覺化檢視的資訊。您必須加入該程式碼，以建立對話方塊並顯示資訊。在本逐步解說中，您會使用 Windows Forms 訊息方塊。首先，您必須新增 System.Windows.Forms 的參考和 using 指示詞。

新增 System.Windows.Forms

在 [方案總管] 中，以滑鼠右鍵按一下 [參考]，然後選擇捷徑功能表上的 [新增參考]。
在 [新增參考] 對話方塊的 [瀏覽] 索引標籤上，選取 [瀏覽]，然後尋找 System.Windows.Forms.DLL。

您可以在 C:\Windows\Microsoft.NET\Framework\v4.0.30319 中找到 DLL。
選取 [確定]。
在 DebuggerSide.cs 中，將下列內容新增至 using 指示詞：
```
using System.Windows.Forms;
```

現在，您可以新增某些程式碼，建立並顯示視覺化檢視的使用者介面。由於這個範例是您的第一個視覺化檢視，您可以建立簡單的使用者介面，並使用訊息方塊。

在對話方塊中顯示視覺化檢視輸出

在 Show 方法中，加入下列程式碼行：
```
MessageBox.Show(objectProvider.GetObject().ToString());
```
這個程式碼範例不包括錯誤處理。在真實的視覺化檢視或其他任何類型的應用程式中，都應該包括錯誤處理功能。
在 [建置] 功能表上，選擇 [建置 MyFirstVisualizer]。專案應該會順利建置。在繼續進行之前，請更正任何建置錯誤。

偵錯工具端的程式碼現已完成。但是還有一個步驟，就是會告知偵錯項目端構成視覺化檢視類別集合的屬性。

新增要針對偵錯項目端程式碼來進行視覺化的類型

在偵錯工具端程式碼中，您會使用 DebuggerVisualizerAttribute 屬性，指定要針對偵錯項目視覺化的類型 (物件來源)。 Target 屬性會設定要視覺化的類型。

將下列屬性程式碼新增至 DebuggerSide.cs，在 using 指示詞後面，但在 namespace MyFirstVisualizer 前面：

[assembly:System.Diagnostics.DebuggerVisualizer(
typeof(MyFirstVisualizer.DebuggerSide),
typeof(VisualizerObjectSource),
Target = typeof(System.String),
Description = "My First Visualizer")]

在 [建置] 功能表上，選擇 [建置 MyFirstVisualizer]。專案應該會順利建置。在繼續進行之前，請更正任何建置錯誤。

這時，您的第一個視覺化檢視已完成。如果您已正確遵循這些步驟，則可以建置視覺化檢視，並將其安裝至 Visual Studio。不過，在將視覺化檢視安裝至 Visual Studio 之前，應該先對其進行測試，以確定其可正確執行。現在，您會建立測試載入器以執行視覺化檢視，而不將其安裝至 Visual Studio。

新增用來顯示視覺化檢視的測試方法

將下列方法加入至 public DebuggerSide 類別：

public static void TestShowVisualizer(object objectToVisualize)
{
   VisualizerDevelopmentHost visualizerHost = new VisualizerDevelopmentHost(objectToVisualize, typeof(DebuggerSide));
   visualizerHost.ShowVisualizer();
}

在 [建置] 功能表上，選擇 [建置 MyFirstVisualizer]。專案應該會順利建置。在繼續進行之前，請更正任何建置錯誤。

接下來，您必須建立可執行的專案，以呼叫視覺化檢視的 DLL。為了簡單起見，請使用主控台應用程式專案。

將主控台應用程式專案新增至方案

在 [方案總管] 中，以滑鼠右鍵按一下方案，選擇 [新增]，然後選取 [新增專案]。
選擇 [檔案]>[新增]>[專案]。在語言下拉式清單中，選擇 [C#]。在搜尋方塊中，輸入主控台應用程式，然後選擇 [主控台應用程式 (.NET Framework)] 或適用於 .NET 的主控台應用程式。選取 [下一步] 。在出現的對話方塊中，輸入名稱 MyTestConsole，然後選取 [建立]。

注意

如果您想要使用測試載入器輕鬆地測試視覺化檢視，請建立 .NET Framework 主控台應用程式。您可以改為建立 .NET 主控台應用程式，但 .NET 尚未支援稍後所述的測試載入器，因此您必須安裝視覺化檢視來進行測試。針對 .NET 主控台應用程式，首先在這裡建立主控台應用程式、新增必要的 DLL 和專案參考，然後遵循新增偵錯項目端資料物件中所述的步驟。如需 ASP.NET 核心案例，請參閱 .NET 5.0+ 的特殊偵錯工具端考量。

此時，你必須加入必要的參考，如此 MyTestConsole 才能呼叫 MyFirstVisualizer。

將必要參考新增至 MyTestConsole

在 [方案總管] 中以滑鼠右鍵按一下 [MyTestConsole]，然後選擇捷徑功能表上的 [新增參考]。
在 [新增參考] 對話方塊中，開啟 [瀏覽] 索引標籤，然後選取 [Microsoft.VisualStudio.DebuggerVisualizers.DLL]。
選取 [確定]。
以滑鼠右鍵按一下 [MyTestConsole]，然後再次選擇 [新增參考]。
在 [新增參考] 對話方塊中，開啟 [專案] 索引標籤，然後選取 [MyFirstVisualizer]。
選取 [確定]。

現在，請新增程式碼以完成測試載入器。

將程式碼新增至 MyTestConsole

在 [方案總管] 中，以滑鼠右鍵按一下 Program.cs，然後選擇捷徑功能表上的 [重新命名]。
將名稱從 Program.cs 編輯為更有意義的名稱，例如 TestConsole.cs。

注意

Visual Studio 會自動變更 TestConsole.cs 中的類別宣告，以符合新的檔案名稱。
在 TestConsole.cs 中，將下列程式碼新增至 using 指示詞：
```
using MyFirstVisualizer;
```

在 Main 方法中，加入下列程式碼：

String myString = "Hello, World";
DebuggerSide.TestShowVisualizer(myString);

現在，您可以準備測試第一個視覺化檢視了。

測試視覺化檢視

在 [方案總管] 中，以滑鼠右鍵按一下 [MyTestConsole]，然後選擇捷徑功能表上的 [設定為啟始專案]。
在 [偵錯] 功能表上選擇 [啟動]。

主控台應用程式即會啟動，而且視覺化檢視會出現，並顯示字串「Hello， World」。

恭喜！您已建置並測試第一個視覺化檢視了！

如果您想要在 Visual Studio 中使用視覺化檢閱，而不只是從測試載入器進行呼叫，則必須安裝該視覺化檢閱。如需詳細資訊，請參閱作法：安裝視覺化檢視。

新增偵錯項目端資料物件

在本節中，您會從 System.String 資料物件切換到自訂資料物件。

在 [方案總管] 中，以滑鼠右鍵按一下方案，選擇 [新增]，然後選取 [新增專案]。在語言下拉式清單中，選擇 [C#]。在搜尋方塊中，輸入類別庫，然後選擇 [類別庫 (.NET Framework)] 或適用於 .NET Standard 的 [類別庫]。

注意

如果您是使用 .NET Framework 測試主控台應用程式，請確定您建立 .NET Framework 類別庫專案。
選取 [下一步] 。在出現的對話方塊中，輸入名稱 MyDataObject，然後選取 [建立]。
(僅限 .NET Standard 類別庫) 在 [方案總管] 中，以滑鼠右鍵按一下專案，然後選擇 [編輯專案檔]。將 <TargetFramework> 值變更為 netstandard2.0。
```
<TargetFramework>netstandard2.0</TargetFramework>
```
在 MyDataObject 命名空間內，將預設程式碼取代為下列程式碼。
```
[Serializable] 
public class CustomDataObject
{
   public CustomDataObject()
   {
      this.MyData = "MyTestData";
   }
   public string MyData { get; set; }
}
```
對於唯讀視覺化檢視，例如在此範例中，不需要實作 VisualizerObjectSource 的方法。

接下來，更新 MyFirstVisualizer 專案以使用新的資料物件。
在方案總管中，以滑鼠右鍵按一下 MyFirstVisualizer 專案下的 [參考] 節點，然後選擇 [新增參考]。
在 [專案] 下，選取 [MyDataObject] 專案。
在 DebuggerSide.cs 的屬性程式碼中，更新 Target 值，將 System.String 變更為 MyDataObject.CustomDataObject。
```
Target = typeof(MyDataObject.CustomDataObject),
```

在 MyFirstVisualizer 專案中，將 Show 方法的程式碼取代為下列程式碼。

var data = objectProvider.GetObject() as MyDataObject.CustomDataObject;

// You can replace displayForm with your own custom Form or Control.  
Form displayForm = new Form();
displayForm.Text = data.MyData;
windowService.ShowDialog(displayForm);

上述程式碼會使用要在表單標題中顯示的資料物件屬性。

接下來，更新主控台應用程式以使用自訂資料物件。

在方案總管中，以滑鼠右鍵按一下 MyTestConsole 專案下的 [參考] 或 [相依性] 節點，並將專案參考新增至 MyDataObject。

在 Program.cs 中，將 Main 方法中的程式碼取代為下列程式碼。

// String myString = "Hello, World";
CustomDataObject customDataObject = new CustomDataObject();

DebuggerSide.TestShowVisualizer(customDataObject);

(.NET 主控台應用程式) 以 try-catch 陳述式括住對 TestShowVisualizer 的呼叫，因為不支援測試載入器。
```
try
{
      DebuggerSide.TestShowVisualizer(customDataObject);
}
catch (Exception) {
}
```
主控台應用程式需要視覺化檢視的執行階段參考。您可以保留上述程式碼來維護參考，而不是將其註解化。
針對 .NET Framework 主控台應用程式，您可以執行測試載入器 (按 F5)，也可以遵循作法：安裝視覺化檢視中的指示。

如果您使用測試載入器執行應用程式，則應用程式會顯示 Windows Form。
針對 .NET 主控台應用程式，將 MyFirstVisualizer.dll 和 MyDataObject.dll 複製到作法：安裝視覺化檢視中所述的資料夾。
在安裝視覺化檢視之後，請設定中斷點、執行主控台應用程式，然後將滑鼠停留在 customDataObject 上。如果一切都正確設定，您應該會看到放大鏡圖示。

當您從放大鏡中選擇 MyFirstVisualizer 時，您會看到標題中帶有資料物件文字的表單。

逐步解說：在 C# 中撰寫視覺化檢視

手動建立視覺化檢視

建立類別庫專案

重新命名 Class1.cs 和新增 Microsoft.VisualStudio.DebuggerVisualizers

從 DialogDebuggerVisualizer 繼承

覆寫 DialogDebuggerVisualizer.Show 方法

新增 System.Windows.Forms

在對話方塊中顯示視覺化檢視輸出

新增要針對偵錯項目端程式碼來進行視覺化的類型

新增用來顯示視覺化檢視的測試方法

將主控台應用程式專案新增至方案

將必要參考新增至 MyTestConsole

將程式碼新增至 MyTestConsole

測試視覺化檢視

新增偵錯項目端資料物件

意見反應

意見反應

其他資源

逐步解說：在 C# 中撰寫視覺化檢視

手動建立視覺化檢視

建立類別庫專案

重新命名 Class1.cs 和新增 Microsoft.VisualStudio.DebuggerVisualizers

從 DialogDebuggerVisualizer 繼承

覆寫 DialogDebuggerVisualizer.Show 方法

新增 System.Windows.Forms

在對話方塊中顯示視覺化檢視輸出

新增要針對偵錯項目端程式碼來進行視覺化的類型

新增用來顯示視覺化檢視的測試方法

將主控台應用程式專案新增至方案

將必要參考新增至 MyTestConsole

將程式碼新增至 MyTestConsole

測試視覺化檢視

新增偵錯項目端資料物件

相關內容

意見反應

意見反應

其他資源