Important
Visual Studio 2022 バージョン 17.9 以降では、新しい VisualStudio.Extensibility モデルを使用してアウトプロセスで実行される .NET 6.0 以降でビジュアライザーを記述できるようになりました。 新しいモデルを使用して作成された拡張機能については、「 Visual Studio デバッガー ビジュアライザーを作成 する」のドキュメントを参照してください。 以前のバージョンの Visual Studio をサポートする必要がある場合、またはライブラリ DLL の一部としてカスタム ビジュアライザーを配布する場合は、この記事の情報を使用します。これは、以前の拡張機能開発モデル (VSSDK) にのみ適用されます。
ビジュアライザーは、データ型に適した方法で変数またはオブジェクトを表示する Visual Studio デバッガーのユーザー インターフェイスの一部です。 たとえば、 ビットマップ ビジュアライザーはビットマップ 構造を解釈し、それが表すグラフィックを表示します。 一部のビジュアライザーでは、データを変更したり、表示したりすることができます。 デバッガーでは、ビジュアライザーは虫眼鏡アイコン 
で表されます。
[データヒント]、[デバッガー ウォッチ] ウィンドウ、または [クイック ウォッチ] ダイアログ ボックスでアイコンを選択し、対応するオブジェクトに適したビジュアライザーを選択できます。
標準の組み込みビジュアライザーに加えて、Microsoft、サード パーティ、コミュニティからより多くのビジュアライザーをダウンロードできる場合があります。 独自のビジュアライザーを記述し、Visual Studio デバッガーにインストールすることもできます。
この記事では、ビジュアライザーの作成の概要について説明します。 詳細な手順については、代わりに次の記事を参照してください。
- チュートリアル: C でビジュアライザーを記述する#
- チュートリアル: Visual Basic でビジュアライザーを記述する
- ビジュアライザーをインストールする
- Natvis のドキュメントでは、UIVisualizer 要素を参照してください。 また、 SQLite ネイティブ デバッガー ビジュアライザーの サンプルも参照してください。
注
カスタム ビジュアライザーは、ユニバーサル Windows プラットフォーム (UWP) アプリと Windows 8.x アプリではサポートされていません。
概要
ObjectとArrayを除き、任意のマネージド クラスのオブジェクトのカスタム ビジュアライザーを記述できます。
デバッガー ビジュアライザーの アーキテクチャ には、次の 2 つの部分があります。
デバッガー側は Visual Studio デバッガー内で実行され、ビジュアライザーのユーザー インターフェイスを作成して表示します。
Visual Studio は .NET Framework ランタイムで実行されるため、このコンポーネントは .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 フォーム、ダイアログ、コントロールを表示できます。
IVisualizerObjectProviderメソッドを使用して、デバッガー側で視覚化されたオブジェクトを取得します。
DialogDebuggerVisualizerから継承するクラスを作成します。
注
Visual Studio 2022 バージョン 17.11 以降のセクションで説明されているセキュリティの問題により、ビジュアライザーは基底クラスのコンストラクターで Legacy フォーマッタ ポリシーを指定できません。 今後は、ビジュアライザーは JSON シリアル化を使用して デバッガー と デバッグ対象側 のコンポーネント間の通信のみを行うことができます。
インターフェイスを表示するには、 Microsoft.VisualStudio.DebuggerVisualizers.DialogDebuggerVisualizer.Show メソッドをオーバーライドします。 IDialogVisualizerServiceメソッドを使用して、インターフェイスに Windows フォーム、ダイアログ、コントロールを表示します。
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メソッドに渡します。デバッグ対象側のビジュアライザー コンポーネントがデバッガー側に何かを返す必要がある場合は、Stream メソッドによって返されるTransferData オブジェクトに配置されます。
IVisualizerObjectProvider2.GetDeserializableObjectFromメソッドを使用して、IDeserializableObject インスタンスを取得し、必要に応じて処理します。逆シリアル化する方法がわかっている型の場合は、DeserializeFromJsonを使用します。
バイナリ シリアル化がサポートされていない場合のデバッグ対象側で必要な他の変更については、.NET 5.0 以降の特別なデバッグ対象側の考慮事項に関するセクションを参照してください。
注
問題の詳細については、 BinaryFormatter セキュリティ ガイドを参照してください。
デバッグ対象側のビジュアライザー オブジェクト ソースを作成する
デバッガー側のコードで、 DebuggerVisualizerAttributeを編集し、視覚化する型 (デバッグ対象側のオブジェクト ソース) (VisualizerObjectSource) を指定します。
Target プロパティは、オブジェクト ソースを設定します。 オブジェクト ソースを省略すると、ビジュアライザーは既定のオブジェクト ソースを使用します。
デバッグ対象側コードには、視覚化されるオブジェクト ソースが含まれています。 データ オブジェクトは、 VisualizerObjectSourceのメソッドをオーバーライドできます。 スタンドアロン ビジュアライザーを作成する場合は、デバッグ対象側 DLL が必要です。
デバッグ対象側のコードで、次の操作を行います。
ビジュアライザーがデータ オブジェクトを編集できるようにするには、オブジェクト ソースが VisualizerObjectSource から継承し、
TransferDataまたはCreateReplacementObjectメソッドをオーバーライドする必要があります。ビジュアライザーでマルチターゲットをサポートする必要がある場合は、デバッグ対象側プロジェクト ファイルで次のターゲット フレームワーク モニカー (TFM) を使用できます。
<TargetFrameworks>net20;netstandard2.0;netcoreapp2.0</TargetFrameworks>これらは、サポートされている唯一の TFM です。
.NET 5.0 以降のデバッグ対象側に関する特別な考慮事項
Important
既定で使用される基になるバイナリ シリアル化方法に関するセキュリティ上の問題により、ビジュアライザーが .NET 5.0 以降で動作するには、追加の手順が必要になる場合があります。 続行する前に、この セクション をお読みください。
ビジュアライザーで TransferData メソッドが実装されている場合は、最新バージョンのGetDeserializableObjectで使用できる新しく追加された
VisualizerObjectSourceメソッドを使用します。 返される IDeserializableObject は、オブジェクトのシリアル化形式 (バイナリまたは JSON) を特定し、基になるオブジェクトを逆シリアル化して使用できるようにするのに役立ちます。デバッグ対象側が呼び出しの一部として
TransferDataにデータを返す場合は、 メソッドを使用してSerializeストリームへの応答をシリアル化します。