Procedura dettagliata: Scrittura di un visualizzatore in C#

2025-06-26

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).

Questa procedura dettagliata illustra come scrivere un visualizzatore semplice usando C#. Il visualizzatore creato in questa procedura dettagliata visualizza il contenuto di una stringa usando un Windows Form. Questo visualizzatore di stringhe semplice non è particolarmente utile in se stesso, ma mostra i passaggi di base da seguire per creare visualizzatori più utili per altri tipi di dati.

Annotazioni

Le finestre di dialogo e i comandi di menu visualizzati potrebbero essere diversi da quelli descritti nella Guida, a seconda delle impostazioni o dell'edizione attiva. Per modificare le impostazioni, passare al menu Strumenti e scegliere Importa ed Esporta impostazioni. Per altre informazioni vedere Reimpostare le impostazioni.

Il codice del visualizzatore deve essere inserito in un file DLL letto dal debugger. Di conseguenza, il primo passaggio consiste nel creare un progetto libreria di classi per la DLL.

Creare manualmente un visualizzatore

Completare le attività seguenti per creare un visualizzatore.

Creare un progetto di libreria di classi

Per creare un nuovo progetto di libreria di classi, selezionare File>Nuovo>progetto.
Nell'elenco a discesa del linguaggio selezionare C#.
Nella casella di ricerca immettere libreria di classi. Selezionare Libreria di classi (.NET Framework) e quindi selezionare Avanti.
Nella finestra di dialogo immettere il nome MyFirstVisualizere quindi selezionare Crea.

Per il progetto del visualizzatore, assicurarsi di selezionare una libreria di classi .NET Framework e non .NET. Anche se il visualizzatore deve essere .NET Framework, l'app chiamante può essere .NET.

Dopo aver creato la libreria di classi, è necessario aggiungere un riferimento al Microsoft.VisualStudio.DebuggerVisualizers.DLL file in modo da poter usare le classi definite. Prima di aggiungere il riferimento, è necessario rinominare alcune classi per usare nomi significativi.

Rinominare Class1.cs e aggiungere Microsoft.VisualStudio.DebuggerVisualizers

In Esplora soluzioni, fare clic con il pulsante destro del mouse su Class1.cs e scegliere Rinomina nel menu di scelta rapida.
Modificare il nome da Class1.cs a qualcosa di significativo, ad esempio DebuggerSide.cs.

Annotazioni

Visual Studio modifica automaticamente la dichiarazione di classe in DebuggerSide.cs in modo che corrisponda al nuovo nome file. Se viene visualizzato un prompt per completare l'azione, selezionare Sì.
In Esplora soluzioni fare clic con il pulsante destro del mouse su Riferimenti e scegliere Aggiungi riferimento dal menu di scelta rapida.
Nella scheda Sfoglia della finestra di dialogo Aggiungi riferimento selezionare Sfoglia e trovare il Microsoft.VisualStudio.DebuggerVisualizers.DLL.

È possibile trovare la DLL nel sottodirectory <Visual Studio Install Directory>\Common7\IDE\PublicAssemblies della directory di installazione di Visual Studio.
Seleziona OK.
In DebuggerSide.cs aggiungere quanto segue alle using direttive :
```
using Microsoft.VisualStudio.DebuggerVisualizers;
```

A questo momento è possibile creare il codice sul lato debugger. Questo codice viene eseguito all'interno del debugger per visualizzare le informazioni desiderate. Prima di tutto, è necessario modificare la dichiarazione dell'oggetto DebuggerSide per configurare l'ereditarietà dalla classe base DialogDebuggerVisualizer.

Ereditare da DialogDebuggerVisualizer

In DebuggerSide.cs passare alla riga di codice seguente:
```
public class DebuggerSide
```

Cambiare il codice in:

public class DebuggerSide : DialogDebuggerVisualizer

Aggiungere un costruttore vuoto in modo da poter passare al costruttore della classe base i criteri di serializzazione che verranno usati per comunicare tra i componenti del visualizzatore.
```
public DebuggerSide() : base(FormatterPolicy.NewtonsoftJson) // or FormatterPolicy.Json
{
}
```
Annotazioni

A causa dei problemi di sicurezza descritti in Considerazioni speciali sul lato debugger per .NET 5.0+, a partire da Visual Studio 2022 versione 17.11, i visualizzatori non potranno specificare la politica del Legacy formattatore.
DialogDebuggerVisualizer dispone di un metodo astratto (Show) di cui è necessario eseguire l'override.

Eseguire l'override del metodo DialogDebuggerVisualizer.Show

In public class DebuggerSideaggiungere il metodo seguente :

protected override void Show(IDialogVisualizerService windowService, IVisualizerObjectProvider objectProvider)
{
}

Il Show metodo contiene il codice che crea effettivamente la finestra di dialogo del visualizzatore o un'altra interfaccia utente e visualizza le informazioni passate al visualizzatore dal debugger. È necessario aggiungere il codice che crea la finestra di dialogo e visualizzare le informazioni. In questa procedura dettagliata viene usata una finestra di messaggio di Windows Form. Prima di tutto, è necessario aggiungere un riferimento e la direttiva using per System.Windows.Forms.

Aggiungere System.Windows.Forms

In Esplora soluzioni fare clic con il pulsante destro del mouse su Riferimenti e scegliere Aggiungi riferimento dal menu di scelta rapida.
Nella scheda Sfoglia della finestra di dialogo Aggiungi riferimento selezionare Sfoglia e trovare il System.Windows.Forms.DLL.

La DLL è disponibile in C:\Windows\Microsoft.NET\Framework\v4.0.30319.
Seleziona OK.
In DebuggerSide.cs aggiungere quanto segue alle using direttive :
```
using System.Windows.Forms;
```

Ora si aggiunge codice per creare e visualizzare l'interfaccia utente per il visualizzatore. Poiché questo esempio è il primo visualizzatore, è possibile mantenere semplice l'interfaccia utente e usare una finestra di messaggio.

Visualizzare l'output del visualizzatore in una finestra di dialogo

Show Nel metodo aggiungere la riga di codice seguente:
```
MessageBox.Show(objectProvider.GetObject().ToString());
```
Questo codice di esempio non include la gestione degli errori. È consigliabile includere la gestione degli errori in un visualizzatore reale o in qualsiasi altro tipo di applicazione.
Scegliere Compila MyFirstVisualizer dal menu Compila. Il progetto dovrebbe essere completato con successo. Correggere eventuali errori di compilazione prima di continuare.

Il codice laterale del debugger è ora completo. C'è un altro passo da compiere, però: l'attributo che indica al lato del programma da sottoporre a debug quale raccolta di classi comprende il visualizzatore.

Aggiungere il tipo da visualizzare per il codice sul lato del debuggee

Nel codice sul lato del debugger, specificare il tipo da visualizzare (la sorgente dell'oggetto) per l'oggetto in debug utilizzando l'attributo DebuggerVisualizerAttribute. La Target proprietà imposta il tipo da visualizzare.

Aggiungere il codice di attributo seguente a DebuggerSide.cs, dopo le direttive using ma prima di namespace MyFirstVisualizer:

[assembly:System.Diagnostics.DebuggerVisualizer(
typeof(MyFirstVisualizer.DebuggerSide),
typeof(VisualizerObjectSource),
Target = typeof(System.String),
Description = "My First Visualizer")]

Scegliere Compila MyFirstVisualizer dal menu Compila. Il progetto dovrebbe essere completato con successo. Correggere eventuali errori di compilazione prima di continuare.

A questo punto, il primo visualizzatore è terminato. Se sono stati eseguiti correttamente i passaggi, è possibile compilare il visualizzatore e installarlo in Visual Studio. Prima di installare un visualizzatore in Visual Studio, è tuttavia necessario testarlo per assicurarsi che venga eseguito correttamente. È ora possibile creare un test harness per eseguire il visualizzatore senza installarlo in Visual Studio.

Aggiungere un metodo di test per visualizzare il visualizzatore

Aggiungere il metodo seguente alla classe public DebuggerSide:

public static void TestShowVisualizer(object objectToVisualize)
{
   VisualizerDevelopmentHost visualizerHost = new VisualizerDevelopmentHost(objectToVisualize, typeof(DebuggerSide));
   visualizerHost.ShowVisualizer();
}

Scegliere Compila MyFirstVisualizer dal menu Compila. Il progetto dovrebbe essere completato con successo. Correggere eventuali errori di compilazione prima di continuare.

Successivamente, è necessario creare un progetto eseguibile per chiamare la DLL del visualizzatore. Per semplicità, usare un progetto di applicazione Console.

Aggiungere un progetto di applicazione console alla soluzione

In Esplora soluzioni fare clic con il pulsante destro del mouse sulla soluzione, scegliere Aggiungi e quindi selezionare Nuovo progetto.
Scegliere File>Nuovo>progetto. Nell'elenco a discesa del linguaggio scegliere C#. Nella casella di ricerca digitare app console e quindi scegliere App console (.NET Framework) o Applicazione console per .NET. Seleziona Avanti. Nella finestra di dialogo visualizzata digitare il nome MyTestConsolee quindi selezionare Crea.

Annotazioni

Per testare facilmente il visualizzatore utilizzando un test harness, crea un'applicazione console .NET Framework. È invece possibile creare un'app console .NET, ma il test harness descritto in seguito non è ancora supportato per .NET, quindi è necessario installare il visualizzatore per testarlo. Per un'app console .NET, creare prima di tutto l'app console qui, aggiungere le DLL e i riferimenti al progetto necessari e quindi seguire i passaggi descritti in Aggiungere un oggetto dati sul lato debug. Per gli scenari ASP.NET Core, vedere Considerazioni speciali sul lato debugger per .NET 5.0+.

È ora necessario aggiungere i riferimenti necessari in modo che MyTestConsole possa chiamare MyFirstVisualizer.

Aggiungere i riferimenti necessari a MyTestConsole

In Esplora soluzioni fare clic con il pulsante destro del mouse su MyTestConsole e scegliere Aggiungi riferimento dal menu di scelta rapida.
Nella finestra di dialogo Aggiungi riferimento aprire la scheda Sfoglia e selezionare Microsoft.VisualStudio.DebuggerVisualizers.DLL.
Seleziona OK.
Fare clic con il pulsante destro del mouse su MyTestConsole e scegliere di nuovo Aggiungi riferimento .
Nella finestra di dialogo Aggiungi riferimento aprire la scheda Progetti e selezionare MyFirstVisualizer.
Seleziona OK.

Ora, aggiungi il codice per completare il test harness.

Aggiungere codice a MyTestConsole

In Esplora soluzioni fare clic con il pulsante destro del mouse Program.cs e scegliere Rinomina dal menu di scelta rapida.
Modificare il nome da Program.cs a qualcosa di più significativo, ad esempio TestConsole.cs.

Annotazioni

Visual Studio modifica automaticamente la dichiarazione di classe in TestConsole.cs in modo che corrisponda al nuovo nome file.
In TestConsole.cs aggiungere il codice seguente alle using direttive :
```
using MyFirstVisualizer;
```

Nel metodo Mainaggiungere il codice seguente:

String myString = "Hello, World";
DebuggerSide.TestShowVisualizer(myString);

A questo momento, si è pronti per testare il primo visualizzatore.

Testare il visualizzatore

In Esplora soluzioni fare clic con il pulsante destro del mouse su MyTestConsole e scegliere Imposta come progetto di avvio dal menu di scelta rapida.
Nel menu Debug scegliere Avvia.

L'applicazione console viene avviata e il visualizzatore appare e visualizza la stringa "Hello, World".

Felicitazioni. Il primo visualizzatore è stato creato e testato.

Se si vuole usare il visualizzatore in Visual Studio anziché semplicemente chiamarlo dal test harness, è necessario installarlo. Per altre informazioni, vedere Procedura: Installare un visualizzatore.

Aggiungere un oggetto dati sul lato del debuggee

In questa sezione si passa dall'oggetto System.String dati a un oggetto dati personalizzato.

In Esplora soluzioni fare clic con il pulsante destro del mouse sulla soluzione, scegliere Aggiungi e quindi selezionare Nuovo progetto. Nell'elenco a discesa del linguaggio scegliere C#. Nella casella di ricerca digitare libreria di classi e quindi scegliere Libreria di classi (.NET Framework) o Libreria di classi per .NET Standard.

Annotazioni

Se si usa un'app console di test di .NET Framework, assicurarsi di creare un progetto di libreria di classi .NET Framework.
Seleziona Avanti. Nella finestra di dialogo visualizzata digitare il nome MyDataObjecte quindi selezionare Crea.
(solo libreria di classi.NET Standard) In Esplora soluzioni fare clic con il pulsante destro del mouse sul progetto e scegliere Modifica file di progetto. Modificare il valore <TargetFramework> in netstandard2.0.
```
<TargetFramework>netstandard2.0</TargetFramework>
```
All'interno dello spazio dei nomi MyDataObject, sostituire il codice predefinito con il codice seguente.
```
[Serializable] 
public class CustomDataObject
{
   public CustomDataObject()
   {
      this.MyData = "MyTestData";
   }
   public string MyData { get; set; }
}
```
Per un visualizzatore di sola lettura, ad esempio in questo esempio, non è necessario implementare metodi di VisualizerObjectSource.

Aggiornare quindi il progetto MyFirstVisualizer per usare il nuovo oggetto dati.
In Esplora soluzioni nel progetto MyFirstVisualizer fare clic con il pulsante destro del mouse sul nodo Riferimenti e scegliere Aggiungi riferimento.
In Progetti selezionare il progetto MyDataObject .
Nel codice dell'attributo di DebuggerSide.cs aggiornare il valore target, impostando System.String su MyDataObject.CustomDataObject.
```
Target = typeof(MyDataObject.CustomDataObject),
```
Nel progetto MyFirstVisualizer sostituire il codice per il Show metodo con il codice seguente.
```
var data = objectProvider.GetObject() as MyDataObject.CustomDataObject;

// You can replace displayForm with your own custom Form or Control.  
Form displayForm = new Form();
displayForm.Text = data.MyData;
windowService.ShowDialog(displayForm);
```
Il codice precedente usa una proprietà dell'oggetto dati da visualizzare nel titolo del modulo.

Aggiornare quindi l'app console per usare l'oggetto dati personalizzato.
In Esplora soluzioni nel progetto MyTestConsole fare clic con il pulsante destro del mouse sul nodo Riferimenti o dipendenze e aggiungere un riferimento al progetto a MyDataObject.

In Program.cs sostituire il codice nel Main metodo con il codice seguente.

// String myString = "Hello, World";
CustomDataObject customDataObject = new CustomDataObject();

DebuggerSide.TestShowVisualizer(customDataObject);

(app console .NET) Racchiudere la chiamata a TestShowVisualizer in un'istruzione try-catch, perché il test harness non è supportato.
```
try
{
      DebuggerSide.TestShowVisualizer(customDataObject);
}
catch (Exception) {
}
```
L'app console richiede un riferimento di runtime al visualizzatore. È possibile mantenere il riferimento mantenendo il codice precedente anziché impostarlo come commento.
Per un'app console .NET Framework, è possibile eseguire il test harness (premere F5) oppure seguire le istruzioni in Procedura: Installare un visualizzatore.

Se si esegue l'app usando il test harness, l'app visualizza Windows Form.
Per un'app console .NET, copiare MyFirstVisualizer.dll e MyDataObject.dll nelle cartelle descritte in Procedura: Installare un visualizzatore.
Dopo aver installato il visualizzatore, impostare un punto di interruzione, eseguire l'app console e passare il puntatore del mouse su customDataObject. Se tutto è configurato correttamente, verrà visualizzata l'icona della lente di ingrandimento .

Quando si sceglie MyFirstVisualizer dalla lente di ingrandimento, viene visualizzato il Modulo con il testo dell'oggetto dati nel titolo.

Condividi tramite