除錯器視覺化工具

偵錯工具視覺化檢視是 Visual Studio 功能,可在偵錯工作階段期間為特定 .NET 類型的變數或物件提供自訂視覺效果。 除錯器視覺化工具可從滑鼠移至變數時出現的 DataTip 存取,或是從 自動變數 視窗、 區域變數 和 監看 視窗中存取。

Note

本文使用 VisualStudio.Extensibility SDK。 如需在 VisualStudio.Extensibility 與舊有 VSSDK 之間做出選擇,請參見「 選擇正確的擴充性模型」。

Watch 視窗中顯示除錯器視覺化器的截圖。

完整範例

完整實作位於該範例中:

// 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 ↗ 取得資料。

預設的視覺化物件來源支援:

預設實作使用 Newtonsoft.JSON ↗ 進行序列化。 如果目標型別已經可序列化,或你能讓自己的型別可序列化,這個預設流程通常就足夠了。

使用自訂視覺化物件來源

如果要視覺化的型別無法被 Newtonsoft.JSON 自動序列化,請建立自訂的視覺化物件來源。

  1. 建立一個新的類別函式庫,目標為 netstandard2.0。 如有需要,你可以將目標設為更特定的框架,如 net472 或 net6.0。
  2. 新增一個套件參考給 Microsoft.VisualStudio.DebuggerVisualizers ↗ 版本為 17.6 或更新版本。
  3. 建立一個擴展 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 呼叫。

下一步