Dela via

Anpassade datavisualiserare för Visual Studio-felsökningsprogrammet (.NET)

Viktigt!

Från och med Visual Studio 2022 version 17.9 kan visualiserare nu skrivas i .NET 6.0+ som körs utanför processen med den nya VisualStudio.Extensibility-modellen. Information om tillägg som skapats med den nya modellen finns i dokumentationen i Skapa Visual Studio-felsökningsvisualiserare i stället. Om du behöver stöd för äldre versioner av Visual Studio eller vill skicka anpassade visualiserare som en del av en biblioteks-DLL använder du informationen i den här artikeln, som endast gäller för den äldre modellen för tilläggsutveckling (VSSDK).

En visualiserare är en del av Visual Studio-felsökningsanvändargränssnittet som visar en variabel eller ett objekt på ett sätt som är lämpligt för dess datatyp. En bitmappsvisualiserare tolkar till exempel en bitmappsstruktur och visar den bild som den representerar. Med vissa visualiseringar kan du ändra och visa data. I felsökningsprogrammet representeras en visualiserare av en förstoringsglasikon VisualizerIcon. Du kan välja ikonen i dialogrutan DataTip, felsökningsklocka eller QuickWatch och sedan välja lämplig visualiserare för motsvarande objekt.

Förutom de inbyggda standardvisualiseringarna kan fler visualiserare vara tillgängliga för nedladdning från Microsoft, tredje part och communityn. Du kan också skriva egna visualiserare och installera dem i Visual Studio-felsökningsprogrammet.

Den här artikeln innehåller en översikt över hur du skapar visualiserare på hög nivå. Detaljerade anvisningar finns i följande artiklar i stället:

Anmärkning

Anpassade visualiseringar stöds inte för UWP (Universal Windows Platform) och Windows 8.x-appar.

Översikt

Du kan skriva en anpassad visualiserare för ett objekt i en hanterad klass förutom Object och Array.

Arkitekturen för en felsökningsvisualiserare har två delar:

  • Felsökningssidan körs i Visual Studio-felsökningsprogrammet och skapar och visar visualiserarens användargränssnitt.

    Eftersom Visual Studio körs på .NET Framework Runtime måste den här komponenten skrivas för .NET Framework. Därför går det inte att skriva det för .NET Core.

  • Felsökningssidan körs i processen Visual Studio felsöker (debuggee). Dataobjektet som ska visualiseras (till exempel ett Strängobjekt) finns i felsökningsprocessen. Felsökningssidan skickar objektet till felsökningssidan, som visar det i användargränssnittet som du skapar.

    Körningen som du skapar den här komponenten för ska matcha den där felsökningsprocessen körs, dvs. antingen .NET Framework eller .NET Core.

Felsökningssidan tar emot dataobjektet från en objektprovider som implementerar IVisualizerObjectProvider gränssnittet. Felsökningssidan skickar objektet via objektkällan, som härleds från VisualizerObjectSource.

Objektprovidern kan också skicka tillbaka data till objektkällan, vilket gör att du kan skriva en visualiserare som kan redigera data. Du åsidosätter objektprovidern för att kommunicera med uttrycksutvärderaren och objektkällan.

Felsökningssidan och debuggersidan kommunicerar med varandra via Stream metoder som serialiserar ett dataobjekt till en Stream och deserialiserar Stream tillbaka till ett dataobjekt.

Du kan bara skriva en visualiserare för en allmän typ om typen är en öppen typ. Den här begränsningen är samma som begränsningen när du använder attributet DebuggerTypeProxy . Mer information finns i Använda attributet DebuggerTypeProxy.

Anpassade visualiseringar kan ha säkerhetsöverväganden. Se Säkerhetsöverväganden för Visualiserare.

Skapa användargränssnittet på felsökningssidan

Om du vill skapa visualiserarens användargränssnitt på felsökningssidan skapar du en klass som ärver från DialogDebuggerVisualizeroch åsidosätter Microsoft.VisualStudio.DebuggerVisualizers.DialogDebuggerVisualizer.Show metoden för att visa gränssnittet. Du kan använda IDialogVisualizerService för att visa Windows-formulär, dialogrutor och kontroller i visualiseraren.

  1. Använd IVisualizerObjectProvider metoder för att hämta det visualiserade objektet på felsökningssidan.

  2. Skapa en klass som ärver från DialogDebuggerVisualizer.

Anmärkning

På grund av de säkerhetsproblem som beskrivs i avsnittet nedan, från och med Visual Studio 2022 version 17.11, kan visualiserare inte ange Legacy formateringsprincipen i basklasskonstruktorn. Från och med nu kan visualiserare endast använda JSON-serialisering för att kommunicera mellan komponenter på debugger- och debuggee-sidan.

  1. Åsidosätt Microsoft.VisualStudio.DebuggerVisualizers.DialogDebuggerVisualizer.Show metoden för att visa gränssnittet. Använd IDialogVisualizerService metoder för att visa Windows-formulär, dialogrutor och kontroller i gränssnittet.

  2. Använd DebuggerVisualizerAttribute och tilldela den visualiseraren för att visa (DialogDebuggerVisualizer).

Särskilda överväganden på felsökningssidan för .NET 5.0+

Anpassade visualiserare överför data mellan debuggee - och felsökningssidorna via binär serialisering med klassen BinaryFormatter som standard. Den typen av serialisering begränsas dock i .NET 5 och senare på grund av säkerhetsproblem när det gäller dess ofixbara säkerhetsrisker. Dessutom har det markerats som helt föråldrat i ASP.NET Core 5 och dess användning kommer att orsaka ett fel enligt beskrivningen i ASP.NET Core-dokumentationen. I det här avsnittet beskrivs de steg du bör vidta för att se till att visualiseraren fortfarande stöds i det här scenariot.

  • Av kompatibilitetsskäl tar metoden Show som åsidosätts i föregående avsnitt fortfarande in en IVisualizerObjectProvider. Men från och med Visual Studio 2019 version 16.10 är det faktiskt av typen IVisualizerObjectProvider3. Därför omvandlar du objektet objectProvider till det uppdaterade gränssnittet.

  • När du skickar objekt, till exempel kommandon eller data, till felsökningssidan, använd IVisualizerObjectProvider2.Serialize-metoden för att skicka det till en ström och avgör det bästa serialiseringsformatet att använda baserat på körningen av felsökningsprocessen. Skicka sedan dataströmmen till IVisualizerObjectProvider2.TransferData -metoden.

  • Om visualiseringskomponenten på programsidan behöver returnera något till felsökar-sidan, finns det i Stream-objektet som returneras av TransferData-metoden. Använd IVisualizerObjectProvider2.GetDeserializableObjectFrom-metoden för att hämta en IDeserializableObject-instans från den och bearbeta den efter behov, eller använd DeserializeFromJson om det är en typ som du vet hur du deserialiserar.

Vänligen se avsnittet Special debuggee side considerations for .NET 5.0+ (Särskilda överväganden på felsökningssidan för .NET 5.0+) för att lära dig vilka andra ändringar som krävs på felsökningssidan när binär serialisering inte stöds.

Anmärkning

Om du vill ha mer information om problemet kan du läsa säkerhetsguiden BinaryFormatter.

Skapa visualiserarobjektkällan för felsökningssidan

I koden på debuggerns sida redigerar du DebuggerVisualizerAttribute, och tilldelar det typen som ska visualiseras (det objekt som ska visualiseras på debuggeesidan) (VisualizerObjectSource). Egenskapen Target anger objektkällan. Om du utelämnar objektkällan använder visualiseraren en standardobjektkälla.

Sidokoden för felsökningen innehåller den objektkälla som visualiseras. Dataobjektet kan åsidosätta metoderna för VisualizerObjectSource. En DLL på felsökningssidan krävs om du vill skapa en fristående visualiserare.

I koden på debug-klientsidan:

  • För att visualiseraren ska kunna redigera dataobjekt måste objektkällan ärva från VisualizerObjectSource och åsidosätta TransferData metoderna eller CreateReplacementObject .

  • Om du behöver stöd för flera mål i visualiseraren kan du använda följande Target Framework Monikers (TFM) i projektfilen på felsökningssidan.

    <TargetFrameworks>net20;netstandard2.0;netcoreapp2.0</TargetFrameworks>

    Dessa är de enda TFM:er som stöds.

Särskilda överväganden för felsökningssidan för .NET 5.0+

Viktigt!

Ytterligare steg kan behövas för att en visualiserare ska fungera från och med .NET 5.0 på grund av säkerhetsproblem när det gäller den underliggande binära serialiseringsmetoden som används som standard. Läs det här avsnittet innan du fortsätter.

  • Om visualiseraren TransferData implementerar metoden använder du den nyligen tillagda GetDeserializableObject metoden som är tillgänglig i den senaste versionen av VisualizerObjectSource. Den IDeserializableObject returnerar hjälper till att fastställa objektets serialiseringsformat (binärt eller JSON) och att deserialisera det underliggande objektet så att det kan användas.

  • Om felsökningssidan returnerar data till debuggersidan som en del av anropet TransferData serialiserar du svaret till dataströmmen på debuggersidan via Serialize metoden.

Relaterat innehåll