Condividi tramite

Visualizzatori di dati personalizzati per il debugger di Visual Studio (.NET)

Importante

A partire da Visual Studio 2022 versione 17.9, i visualizzatori possono ora essere scritti in .NET 6.0+ per essere eseguiti out-of-process utilizzando il nuovo modello VisualStudio.Extensibility. Per le estensioni create con il nuovo modello, vedere invece la documentazione in Creare visualizzatori del debugger di Visual Studio . Se è necessario supportare le versioni precedenti di Visual Studio o si vogliono spedire i visualizzatori personalizzati come parte di una DLL di libreria, usare le informazioni contenute in questo articolo, che si applica solo al modello precedente di sviluppo di estensioni (VSSDK).

Un visualizzatore fa parte dell'interfaccia utente del debugger di Visual Studio che visualizza una variabile o un oggetto in modo appropriato per il relativo tipo di dati. Ad esempio, un visualizzatore bitmap interpreta una struttura bitmap e visualizza l'elemento grafico rappresentato. Alcuni visualizzatori consentono di modificare e visualizzare i dati. Nel debugger, un visualizzatore è rappresentato da un'icona a forma di lente di ingrandimento VisualizerIcona. È possibile selezionare l'icona in un DataTip, nella finestra del debugger finestra di controllo o nel finestra di controllo immediato, e quindi selezionare il visualizzatore appropriato per l'oggetto corrispondente.

Oltre ai visualizzatori predefiniti standard, potrebbero essere disponibili più visualizzatori per il download da Microsoft, da terze parti e dalla community. È anche possibile scrivere visualizzatori personalizzati e installarli nel debugger di Visual Studio.

Questo articolo offre una panoramica generale della creazione del visualizzatore. Per istruzioni dettagliate, vedere invece gli articoli seguenti:

Annotazioni

I visualizzatori personalizzati non sono supportati per le app UWP (Universal Windows Platform) e Windows 8.x.

Informazioni generali

È possibile scrivere un visualizzatore personalizzato per un oggetto di qualsiasi classe gestita, ad eccezione di Object e Array.

L'architettura di un visualizzatore di debugger ha due parti:

  • Il componente debugger viene eseguito all'interno del debugger di Visual Studio e crea e visualizza l'interfaccia utente del visualizzatore.

    Poiché Visual Studio viene eseguito nel runtime di .NET Framework, questo componente deve essere scritto per .NET Framework. Per questo motivo, non è possibile scriverlo per .NET Core.

  • Il lato del debuggee viene eseguito all'interno del processo che Visual Studio sta eseguendo il debug (debuggee). L'oggetto dati da visualizzare,ad esempio un oggetto String, esiste nel processo di debug. Il lato in esecuzione del debug invia l'oggetto al lato debugger, che lo visualizza nell'interfaccia utente che hai creato.

    Il runtime per cui si compila questo componente deve corrispondere a quello in cui verrà eseguito il processo di debug, ovvero .NET Framework o .NET Core.

Il debugger riceve l'oggetto dati da un fornitore di oggetti che implementa l'interfaccia IVisualizerObjectProvider. Il lato del debuggee invia l'oggetto tramite l'origine dell'oggetto, che deriva da VisualizerObjectSource.

Il provider di oggetti può anche inviare i dati all'origine oggetto, che consente di scrivere un visualizzatore in grado di modificare i dati. Si esegue l'override del provider di oggetti per interagire con l'analizzatore di espressioni e l'origine dell'oggetto.

Il lato del processo di debug e il lato del debugger comunicano tra loro tramite Stream metodi che serializzano un oggetto dati in Stream e deserializzano Stream di nuovo in un oggetto dati.

È possibile scrivere un visualizzatore per un tipo generico solo se il tipo è un tipo aperto. Questa restrizione equivale alla restrizione quando si usa l'attributo DebuggerTypeProxy . Per informazioni dettagliate, vedere Usare l'attributo DebuggerTypeProxy.

I visualizzatori personalizzati potrebbero avere considerazioni sulla sicurezza. Vedere Considerazioni sulla sicurezza del visualizzatore.

Creare l'interfaccia utente lato debugger

Per creare l'interfaccia utente del visualizzatore sul lato debugger, creare una classe che eredita da DialogDebuggerVisualizer ed eseguire l'override del metodo Microsoft.VisualStudio.DebuggerVisualizers.DialogDebuggerVisualizer.Show per visualizzare l'interfaccia. È possibile usare IDialogVisualizerService per visualizzare Windows Form, finestre di dialogo e controlli nel visualizzatore.

  1. Utilizzare i metodi IVisualizerObjectProvider per ottenere l'oggetto visualizzato dal lato del debugger.

  2. Creare una classe che eredita da DialogDebuggerVisualizer.

Annotazioni

A causa dei problemi di sicurezza descritti nella sezione seguente, a partire da Visual Studio 2022 versione 17.11, i visualizzatori non potranno specificare i Legacy criteri del formattatore nel costruttore della classe base. Da questo momento in poi, i visualizzatori possono usare solo la serializzazione JSON per comunicare tra il debugger e i componenti lato debuggee.

  1. Sovrascrivere il metodo Microsoft.VisualStudio.DebuggerVisualizers.DialogDebuggerVisualizer.Show per visualizzare la tua interfaccia. Utilizzare IDialogVisualizerService metodi per visualizzare moduli, finestre di dialogo e controlli nell'interfaccia.

  2. Applicare DebuggerVisualizerAttribute, dandogli il visualizzatore per mostrare (DialogDebuggerVisualizer).

Considerazioni speciali sul lato debugger per .NET 5.0+

I visualizzatori personalizzati trasferiscono i dati tra il debuggee e il debugger tramite la serializzazione binaria usando la classe BinaryFormatter per impostazione predefinita. Tuttavia, questo tipo di serializzazione viene limitato in .NET 5 e versioni successive a causa di problemi di sicurezza relativi alle vulnerabilità irrisolvibili. Inoltre, è stato contrassegnato completamente obsoleto in ASP.NET Core 5 e il relativo utilizzo genererà come descritto nella documentazione di ASP.NET Core. Questa sezione descrive i passaggi da eseguire per assicurarsi che il visualizzatore sia ancora supportato in questo scenario.

  • Per motivi di compatibilità, il metodo Show sottoposto a override nella sezione precedente accetta ancora un IVisualizerObjectProvider. Tuttavia, a partire da Visual Studio 2019 versione 16.10, è effettivamente di tipo IVisualizerObjectProvider3. Per questo motivo, effettuare il cast dell'oggetto objectProvider nell'interfaccia aggiornata.

  • Quando si inviano oggetti, come comandi o dati, sul lato del debugger, usare il metodo IVisualizerObjectProvider2.Serialize per passarli a un flusso; questo determinerà il miglior formato di serializzazione da utilizzare in base al runtime del processo del debugger. Passare quindi il flusso al metodo IVisualizerObjectProvider2.TransferData.

  • Se il componente del visualizzatore lato debug deve restituire qualsiasi elemento al lato debugger, si troverà nell'oggetto Stream restituito dal metodo TransferData. Usare il IVisualizerObjectProvider2.GetDeserializableObjectFrom metodo per ottenere un'istanza IDeserializableObject da essa ed elaborarla in base alle esigenze oppure usare DeserializeFromJson se si tratta di un tipo che si sa come deserializzare.

Fare riferimento alla sezione Considerazioni speciali sul lato debug per .NET 5.0+ per capire quali altre modifiche sono necessarie sul lato debug quando la serializzazione binaria non è supportata.

Annotazioni

Per altre informazioni sul problema, vedere la guida alla sicurezza BinaryFormatter.

Creare l'oggetto visualizzatore sorgente per il lato del debuggee

Nel codice del lato del debugger, modificare DebuggerVisualizerAttribute, assegnando il tipo da vedere (origine dell'oggetto lato debug) VisualizerObjectSource. La Target proprietà imposta l'origine dell'oggetto. Se si omette l'origine oggetto, il visualizzatore userà un'origine oggetto predefinita.

Il codice del debuggee contiene l'oggetto sorgente che viene visualizzato. L'oggetto dati può eseguire l'override dei metodi di VisualizerObjectSource. Se si vuole creare un visualizzatore autonomo, è necessaria una DLL per il lato debug.

Nel codice dal lato del processo di debug

  • Per consentire al visualizer di modificare gli oggetti dati, l'origine oggetto deve ereditare da VisualizerObjectSource ed eseguire l'override dei metodi TransferData o CreateReplacementObject.

  • Se è necessario supportare il multi-targeting nel visualizzatore, è possibile usare i seguenti TFM (Target Framework Monikers) nel file di progetto del programma in esecuzione in modalità di debug.

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

    Questi sono gli unici TFM supportati.

Considerazioni speciali sul lato debug per .NET 5.0+

Importante

Potrebbero essere necessari passaggi aggiuntivi per il funzionamento di un visualizzatore a partire da .NET 5.0 a causa di problemi di sicurezza relativi al metodo di serializzazione binario sottostante usato per impostazione predefinita. Leggere questa sezione prima di continuare.

  • Se il visualizzatore implementa il TransferData metodo , usare il metodo appena aggiunto GetDeserializableObject disponibile nella versione più recente di VisualizerObjectSource. Il valore restituito da IDeserializableObject aiuta a determinare il formato di serializzazione dell'oggetto (binario o JSON) e a deserializzare l'oggetto sottostante affinché possa essere utilizzato.

  • Se il lato debuggee restituisce dati al lato debugger come parte della TransferData chiamata, serializzare la risposta nel flusso del lato debugger tramite il Serialize metodo.

Contenuti correlati