偵錯工具視覺化檢視是 Visual Studio 功能,可在偵錯工作階段期間為特定 .NET 類型的變數或物件提供自訂視覺效果。 除錯器視覺化工具可從滑鼠移至變數時出現的 DataTip 存取,或是從 自動變數 視窗、 區域變數 和 監看 視窗中存取。
Note
本文使用 VisualStudio.Extensibility SDK。 如需在 VisualStudio.Extensibility 與舊有 VSSDK 之間做出選擇,請參見「 選擇正確的擴充性模型」。
完整範例
完整實作位於該範例中:
// Copyright (c) Microsoft. All rights reserved.
// Licensed under the MIT license. See LICENSE file in the project root for full license information.
namespace RegexMatchVisualizer;
using System.Text.RegularExpressions;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.VisualStudio.Extensibility;
using Microsoft.VisualStudio.Extensibility.DebuggerVisualizers;
using Microsoft.VisualStudio.RpcContracts.RemoteUI;
using RegexMatchVisualizer.ObjectSource;
/// <summary>
/// Debugger visualizer provider class for <see cref="Match"/>.
/// </summary>
[VisualStudioContribution]
internal class RegexMatchDebuggerVisualizerProvider : DebuggerVisualizerProvider
{
/// <inheritdoc/>
public override DebuggerVisualizerProviderConfiguration DebuggerVisualizerProviderConfiguration => new("%RegexMatchVisualizer.RegexMatchDebuggerVisualizerProvider.DisplayName%", typeof(Match))
{
VisualizerObjectSourceType = new("RegexMatchVisualizer.ObjectSource.RegexMatchObjectSource, RegexMatchObjectSource"),
};
/// <inheritdoc/>
public override async Task<IRemoteUserControl> CreateVisualizerAsync(VisualizerTarget visualizerTarget, CancellationToken cancellationToken)
{
var regexMatch = await visualizerTarget.ObjectSource.RequestDataAsync<RegexMatch>(jsonSerializer: null, cancellationToken);
return new RegexMatchVisualizerUserControl(regexMatch);
}
}
Tip
完整工作範例: RegexMatchDebugVisualizer ↗
相關概念:遠端使用者介面、 貢獻與設定,以及 建立你的第一個擴充功能
理解這個例子
開始
要開始,請依照「 建立你的第一個擴充功能」建立 VisualStudio.Extensibility 擴充專案。
每個擴充功能都以定義 ExtensionConfiguration 中繼資料的 Extension 進入點開始:
[VisualStudioContribution]
internal class MyExtension : Extension
{
public override ExtensionConfiguration ExtensionConfiguration => new()
{
Metadata = new(
id: "MyExtension.01234567",
version: this.ExtensionAssemblyVersion,
publisherName: "Contoso",
displayName: "My debugger visualizer extension"),
};
}
建立偵錯工具視覺化檢視提供程式
新增一個繼承 DebuggerVisualizerProvider ↗ 的類別,並將 VisualStudioContribution ↗ 屬性套用到該類別上:
[VisualStudioContribution]
internal class StringDebuggerVisualizerProvider : DebuggerVisualizerProvider
{
public override DebuggerVisualizerProviderConfiguration DebuggerVisualizerProviderConfiguration => new(
"My string visualizer",
typeof(string));
public override async Task<IRemoteUserControl> CreateVisualizerAsync(
VisualizerTarget visualizerTarget,
CancellationToken cancellationToken)
{
string targetObjectValue = await visualizerTarget.ObjectSource.RequestDataAsync<string>(
jsonSerializer: null,
cancellationToken);
return new MyStringVisualizerControl(targetObjectValue);
}
}
此程式碼定義了一個新的除錯器視覺化工具,用於以下 string 值:
-
DebuggerVisualizerProviderConfiguration定義視覺化器的顯示名稱及支援的 .NET 類型。 -
CreateVisualizerAsync當使用者開啟視覺化器時會被呼叫。 它用VisualizerTarget↗來擷取資料,並回傳一個 Remote UI 控制項,Visual Studio 會以彈出視窗顯示。
同一個設定物件是你宣告細節的地方,例如目標類型、視覺化工具的顯示名稱、VisualizerObjectSourceType,以及視覺化工具是以模態對話框還是非模態工具視窗開啟。
鎖定多種類型
當需要共用相同的 UI、檢視模型和視覺化物件來源時,配置屬性可以針對多種類型。 一個常見的例子是支援 DataSet、 DataTable、 DataView和 DataViewManager的表格視覺化器。
public override DebuggerVisualizerProviderConfiguration DebuggerVisualizerProviderConfiguration => new(
new VisualizerTargetType("DataSet Visualizer", typeof(System.Data.DataSet)),
new VisualizerTargetType("DataTable Visualizer", typeof(System.Data.DataTable)),
new VisualizerTargetType("DataView Visualizer", typeof(System.Data.DataView)),
new VisualizerTargetType("DataViewManager Visualizer", typeof(System.Data.DataViewManager)));
處理視覺化物件來源
視覺化物件來源是一個 .NET 類別,除錯器會將其載入到被除錯的程序中。 你的除錯器視覺化工具會透過 VisualizerTarget.ObjectSource ↗ 取得資料。
預設的視覺化物件來源支援:
-
RequestDataAsync<T>(JsonSerializer?, CancellationToken)↗ 適用於強型別資料 -
RequestDataAsync(CancellationToken)↗ 適用於JToken
預設實作使用 Newtonsoft.JSON ↗ 進行序列化。 如果目標型別已經可序列化,或你能讓自己的型別可序列化,這個預設流程通常就足夠了。
使用自訂視覺化物件來源
如果要視覺化的型別無法被 Newtonsoft.JSON 自動序列化,請建立自訂的視覺化物件來源。
- 建立一個新的類別函式庫,目標為
netstandard2.0。 如有需要,你可以將目標設為更特定的框架,如net472或net6.0。 - 新增一個套件參考給 Microsoft.VisualStudio.DebuggerVisualizers ↗ 版本為 17.6 或更新版本。
- 建立一個擴展
VisualizerObjectSource並覆寫 的類別。
public class MyObjectSource : VisualizerObjectSource
{
public override void GetData(object target, Stream outgoingData)
{
MySerializableType result = Convert(target);
SerializeAsJson(outgoingData, result);
}
private static MySerializableType Convert(object target)
{
// Convert the debuggee object into a serializable type.
throw new NotImplementedException();
}
}
如果你是依照正則表達式範例,RegexMatchObjectSource 會在提供者要求之前,將 Match 轉換成可序列化的 RegexMatch 形狀。
使用自訂序列化
使用 VisualizerObjectSource.SerializeAsJson 以 Newtonsoft.Json 序列化物件,而不需讓物件來源函式庫直接相依於 Newtonsoft.Json。 此方法透過反射在偵錯處理程序中載入 Newtonsoft.Json 組件。
如果你決定直接參考 Newtonsoft.Json,請使用與 Microsoft.VisualStudio.Extensibility.Sdk 參考的相同版本。 在大多數情況下,使用 DataContract 和 DataMember 屬性來處理共用型別,比依賴 Newtonsoft.Json 專屬型別更好。
你也可以實作自己的序列化格式,直接寫入 outgoingData。
將視覺化檢視物件來源 DLL 新增至延伸模組
新增一個 ProjectReference 讓物件原始碼專案在擴充套件打包前建置,並新增 Content 項目讓 DLL 複製到擴充套件輸出中。
<ItemGroup>
<Content Include="pathToTheObjectSourceDllBinPath\$(Configuration)\netstandard2.0\MyObjectSourceLibrary.dll"
Link="netstandard2.0\MyObjectSourceLibrary.dll">
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
</Content>
</ItemGroup>
<ItemGroup>
<ProjectReference Include="..\MyObjectSourceLibrary\MyObjectSourceLibrary.csproj" />
</ItemGroup>
如果物件原始碼函式庫以這些架構為目標,也可以使用 net462 或 netcoreapp 子資料夾,但如果可能,仍以 netstandard2.0 為首選。
盡量保持物件來源函式庫的相依關係圖最小。 如果依賴受偵錯程式尚未載入的其他 DLL,請將這些 DLL 放在同一個擴充功能子資料夾中。
設定提供者使用自訂物件來源
物件來源 DLL 打包完成後,更新 DebuggerVisualizerProviderConfiguration 指向它:
public override DebuggerVisualizerProviderConfiguration DebuggerVisualizerProviderConfiguration => new(
"My visualizer",
typeof(TypeToVisualize))
{
VisualizerObjectSourceType = new(typeof(MyObjectSource)),
};
public override async Task<IRemoteUserControl> CreateVisualizerAsync(
VisualizerTarget visualizerTarget,
CancellationToken cancellationToken)
{
MySerializableType result = await visualizerTarget.ObjectSource.RequestDataAsync<MySerializableType>(
jsonSerializer: null,
cancellationToken);
return new MyVisualizerUserControl(result);
}
如果你刻意避免從擴充套件參考組件到物件來源專案,請將 VisualizerObjectSourceType 設定為組件限定名稱,而非 typeof(...)。 正則表達式範例使用了這個模式。
處理大型且複雜的物件
如果一次無參數 RequestDataAsync 呼叫中取得所有資料不實際,請使用 RequestDataAsync<TMessage, TResponse>(TMessage, JsonSerializer?, CancellationToken) ↗ 與物件來源交換訊息。
此模式對大型集合非常有用,因為每次 RequestDataAsync 呼叫有五秒的逾時。 一種常見的做法是一次請求一個條目:
for (int i = 0; ; i++)
{
MySerializableType? collectionEntry =
await visualizerTarget.ObjectSource.RequestDataAsync<int, MySerializableType?>(
i,
jsonSerializer: null,
cancellationToken);
if (collectionEntry is null)
{
break;
}
observableCollection.Add(collectionEntry);
}
在物件來源端,覆寫 TransferData,而非 GetData:
public class MyCollectionTypeObjectSource : VisualizerObjectSource
{
public override void TransferData(object target, Stream incomingData, Stream outgoingData)
{
var index = (int)DeserializeFromJson(incomingData, typeof(int))!;
if (target is MyCollectionType collection && index < collection.Count)
{
var result = Convert(collection[index]);
SerializeAsJson(outgoingData, result);
}
else
{
SerializeAsJson(outgoingData, null);
}
}
}
DeserializeFromJson 讀取提供者透過 incomingData發送的訊息。
當視覺化器執行較複雜的訊息交換時,通常最好將 VisualizerTarget ↗ 傳遞給遠端使用者控制項,讓遠端使用者能在控制項載入時非同步請求資料,或在使用者互動後回應:
public override Task<IRemoteUserControl> CreateVisualizerAsync(
VisualizerTarget visualizerTarget,
CancellationToken cancellationToken)
{
return Task.FromResult<IRemoteUserControl>(new MyVisualizerUserControl(visualizerTarget));
}
以工具視窗開啟視覺化工具
預設情況下,除錯器視覺化工具會以模態對話框的形式在 Visual Studio 前景開啟。 若使用者想繼續與 IDE 互動,必須先關閉模態視窗中的視覺化工具。
如果你設定 Style = VisualizerStyle.ToolWindow,視覺化工具會以非模態工具視窗的形式開啟,並且可以在除錯會話的其餘時間保持開啟。 如果你不設定 Style,預設值為 ModalDialog。
public override DebuggerVisualizerProviderConfiguration DebuggerVisualizerProviderConfiguration => new(
"My visualizer",
typeof(TypeToVisualize))
{
Style = VisualizerStyle.ToolWindow
};
當視覺化檢視器以工具視窗開啟時,必須訂閱該 VisualizerTarget.Changed 事件。 工具視窗不會阻擋使用者繼續執行,因此除錯器會在除錯目標改變狀態時發出通知。 當目標不可用時,對 ObjectSource 的呼叫會因 VisualizerTargetUnavailableException 而失敗。
internal class MyVisualizerUserControl : RemoteUserControl
{
private readonly VisualizerDataContext dataContext;
#pragma warning disable CA2000 // Dispose objects before losing scope
public MyVisualizerUserControl(VisualizerTarget visualizerTarget)
: base(dataContext: new VisualizerDataContext(visualizerTarget))
#pragma warning restore CA2000 // Dispose objects before losing scope
{
this.dataContext = (VisualizerDataContext)this.DataContext!;
}
protected override void Dispose(bool disposing)
{
if (disposing)
{
this.dataContext.Dispose();
}
}
[DataContract]
private class VisualizerDataContext : NotifyPropertyChangedObject, IDisposable
{
private readonly VisualizerTarget visualizerTarget;
private MySerializableType? _value;
public VisualizerDataContext(VisualizerTarget visualizerTarget)
{
this.visualizerTarget = visualizerTarget;
this.visualizerTarget.Changed += this.OnStateChangedAsync;
}
[DataMember]
public MySerializableType? Value
{
get => this._value;
set => this.SetProperty(ref this._value, value);
}
public void Dispose()
{
this.visualizerTarget.Dispose();
}
private async Task OnStateChangedAsync(object? sender, VisualizerTargetStateNotification args)
{
switch (args)
{
case VisualizerTargetStateNotification.Available:
case VisualizerTargetStateNotification.ValueUpdated:
Value = await this.visualizerTarget.ObjectSource.RequestDataAsync<MySerializableType>(
jsonSerializer: null,
CancellationToken.None);
break;
case VisualizerTargetStateNotification.Unavailable:
Value = null;
break;
default:
throw new NotSupportedException("Unexpected visualizer target state notification");
}
}
}
}
在建立 RemoteUserControl 之後,Available 會在 Visual Studio 顯示工具視窗之前被引發。
ValueUpdated 表示表達式已成功在當前中斷狀態重新評估,UI 應該會重新整理。
Unavailable 表示執行已恢復,或執行停止後表達式無法重新評估。
更新視覺化物件值
若 VisualizerTarget.IsTargetReplaceable ↗ 是 true,視覺化工具可透過呼叫 ReplaceTargetObjectAsync ↗ 來更新被偵錯程式的值。
await visualizerTarget.ObjectSource.ReplaceTargetObjectAsync(
newValue,
jsonSerializer: null,
cancellationToken);
視覺化物件來源必須覆寫 CreateReplacementObject:
public override object CreateReplacementObject(object target, Stream incomingData)
{
// Read the replacement value from incomingData.
return newValue;
}
Tips
✅ DO
- 將擴充功能中繼資料放在
ExtensionConfiguration,並將貢獻設定放在DebuggerVisualizerProviderConfiguration。 - 除非你有特定理由要針對其他框架,否則請對物件來源專案使用
netstandard2.0。 - 使用
DataContract及DataMember於共享資料型態上。 - 將物件來源 DLL 及任何必要的相依性打包到擴充功能中。
- 對於大型或昂貴的物件,請使用分頁
RequestDataAsync呼叫。 - 以工具視窗開啟時處理
VisualizerTarget.Changed
❌ 不要
- 不要從物件來源專案參考 VisualStudio.Extensibility 套件。
- 不要假設每個類型都能被預設物件來源序列化。
- 不要讓工具視窗視覺化器對
Unavailable通知一無所知。 - 別忘了
RequestDataAsync通話可能會在五秒內逾時。
🔧 故障排除
| 徵兆 | 要檢查的事項 |
|---|---|
| 視覺化器未顯示 | 確認提供者類別有 [VisualStudioContribution],且 DebuggerVisualizerProviderConfiguration 以正確的 .NET 類型為目標。 |
RequestDataAsync 失敗或超時 |
將大型資料擷取移至 TransferData,並在多次呼叫中對資料進行分頁。 |
| 找不到自訂物件來源 | 確認 DLL 是否已複製到擴充功能的 netstandard2.0 資料夾中,並確認 VisualizerObjectSourceType 指向正確的類型或組件限定名稱。 |
| 工具視窗視覺化工具在繼續偵錯時擲回例外 | 在目標再次可用之前,處理 VisualizerTargetStateNotification.Unavailable 並避免 ObjectSource 呼叫。 |
下一步
- 探索完整的 RegexMatchDebugVisualizer 範例↗。
- 了解更多關於 Remote UI 的資訊。
- 查看 參與內容和組態。
- 請在「 選擇合適的可擴展性模型」中比較模型。