Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Debugger-Visualizer sind ein Visual Studio-Feature, das während einer Debug-Sitzung eine benutzerdefinierte Visualisierung für Variablen oder Objekte eines bestimmten .NET-Typs bereitstellt. Auf Debugger-Schnellansichten kann über die DataTip zugegriffen werden, die beim Zeigen auf eine Variable angezeigt wird, oder über die Fenster Autos, Lokal und Überwachung.
Note
In diesem Artikel wird das VisualStudio.Extensibility SDK verwendet. Hilfe bei der Auswahl zwischen VisualStudio.Extensibility und dem älteren VSSDK finden Sie unter Das richtige Erweiterbarkeitsmodell auswählen.
Vollständiges Beispiel
Die vollständige Implementierung befindet sich im Beispiel:
// 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
Sehen Sie sich das vollständige Arbeitsbeispiel an: RegexMatchDebugVisualizer ↗
Verwandte Konzepte:Remote-UI, Beiträge und Konfigurationen und Ihre erste Erweiterung erstellen
Verstehen des Beispiels
Get started
Erstellen Sie zunächst ein VisualStudio.Extensibility-Erweiterungsprojekt, indem Sie Erstellen Ihrer ersten Erweiterung befolgen.
Jede Erweiterung beginnt mit einem Extension Entry Point, der ExtensionConfiguration Metadaten definiert:
[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"),
};
}
Erstellen des Debuggervisualisierungsanbieters
Fügen Sie eine Klasse hinzu, die VisualStudioContribution ↗ erweitert, und wenden Sie das Attribut DebuggerVisualizerProvider ↗ darauf an:
[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);
}
}
Dieser Code definiert eine neue Debuggerschnellansicht für string Werte:
-
DebuggerVisualizerProviderConfigurationdefiniert den Anzeigenamen des Visualizers und den unterstützten .NET-Typ. -
CreateVisualizerAsyncwird aufgerufen, wenn der Benutzer die Visualisierung öffnet. Es wirdVisualizerTarget↗ verwendet, um Daten abzurufen, und gibt ein Remote-UI-Steuerelement zurück, das Visual Studio in einem Popupfenster anzeigt.
Dasselbe Konfigurationsobjekt ist der Ort, an dem Sie Details wie Zieltypen, Anzeigenamen der Schnellansicht, VisualizerObjectSourceType, deklarieren und ob die Schnellansicht als modales Dialogfeld oder als nicht modales Toolfenster geöffnet wird.
Mehrere Typen als Ziel
Die Konfigurationseigenschaft kann auf mehrere Typen angewendet werden, wenn es sinnvoll ist, dieselbe Benutzeroberfläche, Ansichtsmodelle und Visualisiererobjektquelle gemeinsam zu nutzen. Ein gängiges Beispiel ist eine tabellarische Schnellansicht, die DataSet, DataTable, DataView und DataViewManager unterstützt.
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)));
Arbeiten mit der Visualizer-Objektquelle
Die Schnellansicht-Objektquelle ist eine .NET-Klasse, die der Debugger in den zu debuggenden Prozess lädt. Der Debuggervisualisierer ruft darüber Daten ab VisualizerTarget.ObjectSource ↗.
Die standardmäßige Quelle des Visualisierungsobjekts unterstützt Folgendes:
-
RequestDataAsync<T>(JsonSerializer?, CancellationToken)↗ für stark typierte Daten -
RequestDataAsync(CancellationToken)↗ fürJToken
Die Standardimplementierung verwendet Newtonsoft.Json ↗ für die Serialisierung. Wenn der Zieltyp bereits serialisierbar ist oder Sie Ihren eigenen Typ serialisierbar machen können, ist dieser Standardfluss häufig genug.
Verwenden einer benutzerdefinierten Visualisiererobjektquelle
Wenn der zu visualisierende Typ nicht automatisch von Newtonsoft.Json serialisiert werden kann, erstellen Sie eine benutzerdefinierte Visualisierungsobjektquelle.
- Erstellen Sie eine neue Klassenbibliothek mit dem Ziel
netstandard2.0. Bei Bedarf können Sie ein spezifischeres Framework wienet472odernet6.0auswählen. - Fügen Sie einen Paketverweis auf Microsoft.VisualStudio.DebuggerVisualizers ↗ in Version 17.6 oder höher hinzu.
- Erstellen Sie eine Klasse, die
VisualizerObjectSource↗ erweitert undGetDataüberschreibt.
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();
}
}
Wenn Sie dem Regex-Beispiel folgen, konvertiert RegexMatchMatch in eine serialisierbare RegexMatchObjectSource-Form, bevor der Anbieter sie anfordert.
Verwenden der benutzerdefinierten Serialisierung
Verwenden Sie VisualizerObjectSource.SerializeAsJson, um Objekte mit Newtonsoft.Json zu serialisieren, ohne der Quellbibliothek des Objekts eine direkte Newtonsoft.Json-Abhängigkeit hinzuzufügen. Die Methode lädt die Newtonsoft.Json-Assembly im Debuggee-Prozess über Spiegelung.
Wenn Sie sich entschließen, direkt auf Newtonsoft.Json zu verweisen, verwenden Sie dieselbe Version, auf die auch Microsoft.VisualStudio.Extensibility.Sdk verweist. In den meisten Fällen ist es besser, für freigegebene Typen die Attribute DataMember und DataContract zu verwenden, anstatt sich auf Newtonsoft.Json-spezifische Typen zu verlassen.
Sie können auch ihr eigenes Serialisierungsformat implementieren und direkt in outgoingData schreiben.
Fügen Sie die Visualizer-Objektquelle-DLL zur Erweiterung hinzu
Fügen Sie ein ProjectReference-Objektquellprojekt hinzu, damit das Objektquellprojekt erstellt wird, bevor die Erweiterung gepackt wird, und fügen Sie ein Content-Element hinzu, damit die DLL in die Erweiterungsausgabe kopiert wird.
<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>
Sie können auch netcoreapp oder net462 Unterordner verwenden, wenn die Objektquellenbibliothek auf diese Frameworks ausgerichtet ist, aber netstandard2.0 wird nach Möglichkeit bevorzugt.
Halten Sie das Abhängigkeitsdiagramm der Objektquellbibliothek so klein wie möglich. Wenn es von anderen DLLs abhängt, die der Debuggee noch nicht geladen hat, schließen Sie diese DLLs in denselben Erweiterungsunterordner ein.
Konfigurieren Sie den Anbieter so, dass er die benutzerdefinierte Objektquelle verwendet
Nachdem die Objektquell-DLL verpackt wurde, aktualisieren Sie DebuggerVisualizerProviderConfiguration, sodass es darauf verweist:
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);
}
Wenn Sie absichtlich einen Assemblyverweis von der Erweiterung auf das Objektquellprojekt vermeiden, konfigurieren Sie VisualizerObjectSourceType mit dem assemblyqualifizierten Namen anstelle von typeof(...). Im Regex-Beispiel wird dieses Muster verwendet.
Arbeiten mit großen und komplexen Objekten
Wenn das Abrufen aller Daten in einem parameterlosen RequestDataAsync Aufruf nicht praktikabel ist, können Sie RequestDataAsync<TMessage, TResponse>(TMessage, JsonSerializer?, CancellationToken) ↗ verwenden, um Nachrichten mit der Objektquelle auszutauschen.
Dieses Muster ist für große Auflistungen nützlich, da jeder RequestDataAsync Aufruf über ein Fünf-Sekunden-Timeout verfügt. Ein allgemeiner Ansatz besteht darin, einträge einzeln anzufordern:
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);
}
Auf der Objektquellseite überschreiben Sie TransferData anstelle von 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 liest die Nachricht, die der Anbieter über incomingData gesendet hat.
Wenn eine Schnellansicht komplexeren Nachrichtenaustausch durchführt, ist es häufig besser, die VisualizerTarget ↗ an das Remote-Benutzersteuerelement zu übergeben, damit es Daten asynchron anfordern kann, während das Steuerelement geladen wird, oder später als Reaktion auf Benutzerinteraktion:
public override Task<IRemoteUserControl> CreateVisualizerAsync(
VisualizerTarget visualizerTarget,
CancellationToken cancellationToken)
{
return Task.FromResult<IRemoteUserControl>(new MyVisualizerUserControl(visualizerTarget));
}
Schnellansichten als Toolfenster öffnen
Debugger-Schnellansichten werden standardmäßig als modale Dialogfelder im Vordergrund von Visual Studio geöffnet. Wenn der Benutzer weiterhin mit der IDE interagieren möchte, muss er zuerst den modalen Visualizer schließen.
Wenn Sie Style = VisualizerStyle.ToolWindow festlegen, wird die Visualisierung als nicht modales Toolfenster geöffnet und kann für den Rest der Debugsitzung geöffnet bleiben. Wenn Sie Style nicht festlegen, lautet der Standardwert ModalDialog.
public override DebuggerVisualizerProviderConfiguration DebuggerVisualizerProviderConfiguration => new(
"My visualizer",
typeof(TypeToVisualize))
{
Style = VisualizerStyle.ToolWindow
};
Wenn eine Visualisierung als Toolfenster geöffnet wird, muss sie das VisualizerTarget.Changed Ereignis abonnieren. Toolfenster verhindern nicht, dass der Benutzer die Ausführung fortsetzen kann, sodass der Debugger Benachrichtigungen auslöst, wenn sich der Status des Debugziels ändert. Wenn das Ziel nicht verfügbar ist, schlagen Aufrufe an ObjectSource mit VisualizerTargetUnavailableException fehl.
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");
}
}
}
}
Available wird nach der Erstellung von RemoteUserControl ausgelöst und unmittelbar bevor Visual Studio das Toolfenster anzeigt.
ValueUpdated gibt an, dass der Ausdruck erfolgreich im aktuellen Unterbrechungszustand neu ausgewertet wurde und die Benutzeroberfläche aktualisiert werden soll.
Unavailable gibt an, dass die Ausführung fortgesetzt wurde oder dass der Ausdruck nach dem Beenden der Ausführung nicht erneut ausgewertet werden konnte.
Aktualisieren des visualisierten Objektwerts
Wenn VisualizerTarget.IsTargetReplaceable ↗true ist, kann der Visualizer den Debuggee-Wert durch Aufrufen von ReplaceTargetObjectAsync ↗ aktualisieren.
await visualizerTarget.ObjectSource.ReplaceTargetObjectAsync(
newValue,
jsonSerializer: null,
cancellationToken);
Die Schnellansicht-Objektquelle muss folgendes überschreiben CreateReplacementObject:
public override object CreateReplacementObject(object target, Stream incomingData)
{
// Read the replacement value from incomingData.
return newValue;
}
Tips
✅ DO
- Platzieren Sie Erweiterungsmetadaten in
ExtensionConfigurationund Beitragseinstellungen inDebuggerVisualizerProviderConfiguration. - Verwenden Sie
netstandard2.0für das Objektquellprojekt, es sei denn, Sie haben einen bestimmten Grund, ein anderes Framework zu verwenden. - Verwenden Sie
DataContractundDataMemberfür gemeinsam genutzte Datentypen. - Packen Sie die Object-Source-DLL und alle erforderlichen Abhängigkeiten mit der Erweiterung.
- Verwenden Sie paginierte Aufrufe
RequestDataAsyncfür große oder teure Objekte. -
VisualizerTarget.Changedbeim Öffnen als Toolfenster behandeln.
❌ BITTE NICHT
- Verweisen Sie nicht auf VisualStudio.Extensibility-Pakete aus dem Objektquellprojekt.
- Gehen Sie nicht davon aus, dass jeder Typ von der Standardobjektquelle serialisiert werden kann.
- Lassen Sie nicht zu, dass eine Toolfenster-Schnellansicht
Unavailable-Benachrichtigungen nicht zur Kenntnis nimmt. - Vergessen Sie nicht, dass
RequestDataAsyncAnrufe nach fünf Sekunden ablaufen können.
🔧 Problembehandlung
| Symptom | Was soll überprüft werden? |
|---|---|
| Visualizer wird nicht angezeigt | Stellen Sie sicher, dass die Anbieterklasse [VisualStudioContribution] enthält und dass DebuggerVisualizerProviderConfiguration auf den richtigen .NET-Typ verweist. |
RequestDataAsync schlägt fehl oder es kommt zu einer Zeitüberschreitung |
Verschieben Sie den Abruf großer Datenmengen auf TransferData und paginieren Sie die Daten über mehrere Aufrufe hinweg. |
| Benutzerdefinierte Objektquelle wurde nicht gefunden | Vergewissern Sie sich, dass die DLL in den Ordner der Erweiterung netstandard2.0 kopiert wurde und VisualizerObjectSourceType auf den richtigen Typ oder assemblyqualifizierten Namen verweist. |
| Toolfenster-Schnellansicht verursacht einen Fehler, wenn das Debuggen fortgesetzt wird | Bearbeiten Sie VisualizerTargetStateNotification.Unavailable und vermeiden Sie ObjectSource-Aufrufe, bis das Ziel wieder verfügbar ist. |
Nächste Schritte
- Erkunden Sie das vollständige RegexMatchDebugVisualizer-Beispiel ↗.
- Weitere Informationen zur Remote-UI.
- Überprüfen Sie Beiträge und Konfigurationen.
- Vergleichen Sie Modelle in Wählen Sie das richtige Erweiterbarkeitsmodell.