Compartir vía

Tutorial: Escribir un visualizador en C#

  • Artículo

Importante

A partir de la versión 17.9 de Visual Studio 2022, los visualizadores se pueden escribir en .NET 6.0+, que se ejecuta fuera de proceso mediante el nuevo modelo VisualStudio.Extensibility. Animamos a los autores de visualizadores a hacer referencia a la nueva documentación en Creación de visualizadores del depurador de Visual Studio a menos que quieran admitir versiones anteriores de Visual Studio o que quieran enviar sus visualizadores personalizados como parte de un archivo DLL de biblioteca.

En este tutorial se muestra cómo escribir un visualizador sencillo con C#. El visualizador que va a crear en este tutorial muestra el contenido de una cadena mediante un formulario de Windows. Este sencillo visualizador de cadenas no es especialmente útil, pero muestra los pasos básicos que se deben seguir para crear visualizadores más útiles para otros tipos de datos.

Nota:

Los cuadros de diálogo y los comandos de menú que se ven pueden diferir de los descritos en la Ayuda, dependiendo de los valores de configuración o de edición activos. Para cambiar la configuración, vaya al menú Herramientas, y elija Importar y exportar configuraciones. Para obtener más información, vea Restablecer la configuración.

El código del visualizador se debe colocar en un archivo DLL que leerá el depurador. Por lo tanto, el primer paso es crear un proyecto de biblioteca de clases para el archivo DLL.

Crear un visualizador manualmente

Complete las siguientes tareas para crear un visualizador.

Crear un proyecto de biblioteca de clases

  1. Para crear un nuevo proyecto de biblioteca de clases, seleccione Archivo>Nuevo>Proyecto.

  2. En la lista desplegable de lenguaje, seleccione C#.

  3. En el cuadro de búsqueda, escriba la biblioteca de clases. Seleccione Biblioteca de clases (.NET Framework) y, a continuación, seleccione Siguiente.

  4. En el cuadro de diálogo, escriba el nombre MyFirstVisualizer y seleccione Crear.

Para el proyecto del visualizador, asegúrese de seleccionar una biblioteca de clases de .NET Framework y no de .NET. Aunque el visualizador debe ser de .NET Framework, la aplicación que realiza la llamada puede ser de .NET.

Después de crear la biblioteca de clases, debe agregar una referencia al archivo Microsoft.VisualStudio.DebuggerVisualizers.DLL para poder usar las clases definidas allí. Antes de agregar la referencia, debe cambiar el nombre de algunas clases para usar nombres significativos.

Cambio de nombre de Class1.cs y adición de Microsoft.VisualStudio.DebuggerVisualizers

  1. En el Explorador de soluciones, haga clic con el botón derecho en Class1.cs y seleccione Cambiar nombre en el menú contextual.

  2. Cambie el nombre Class1.cs por un nombre significativo, como DebuggerSide.cs.

    Nota

    Visual Studio cambia automáticamente la declaración de clase en DebuggerSide.cs para que coincida con el nuevo nombre del archivo. Si ve un mensaje para completar la acción, seleccione Sí.

  3. En el Explorador de soluciones, haga clic con el botón derecho en Referencias y después elija Agregar referencia en el menú contextual.

  4. En el cuadro de diálogo Agregar referencia, en la pestaña Examinar, seleccione Examinar y busque Microsoft.VisualStudio.DebuggerVisualizers.DLL.

    Puede encontrar el archivo DLL en el subdirectorio <Visual Studio Install Directory>\Common7\IDE\PublicAssemblies del directorio de instalación de Visual Studio.

  5. Seleccione Aceptar.

  6. En DebuggerSide.cs, agregue lo siguiente a las directivas using:

    using Microsoft.VisualStudio.DebuggerVisualizers;

Ahora, ya está listo para crear el código del depurador. Este código se ejecuta dentro del depurador para mostrar la información que desea visualizar. En primer lugar, hay que cambiar la declaración del objeto DebuggerSide para configurar la herencia de la clase base DialogDebuggerVisualizer.

Heredar de DialogDebuggerVisualizer

  1. En DebuggerSide.cs, vaya a la línea siguiente del código:

    public class DebuggerSide

  2. Cambie el código por:

    public class DebuggerSide : DialogDebuggerVisualizer

  3. Agregue un constructor vacío para que pueda pasar al constructor de la clase base la directiva de serialización que se utilizará para comunicarse entre los componentes del visualizador.

    public DebuggerSide() : base(FormatterPolicy.NewtonsoftJson) // or FormatterPolicy.Json
{
}

    Nota:

    Debido a los problemas de seguridad descritos en Consideraciones especiales del lado depurador para .NET 5.0+, a partir de Visual Studio 2022 versión 17.11, los visualizadores no podrán especificar la directiva de formateador Legacy.

  4. DialogDebuggerVisualizer tiene un método abstracto (Show) que debe reemplazar.

Invalidar el método DialogDebuggerVisualizer.Show

En public class DebuggerSide, agregue el siguiente método:

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

El método Show contiene el código que verdaderamente crea el cuadro de diálogo del visualizador, u otra interfaz de usuario, y muestra la información que se ha pasado del depurador al visualizador. Es necesario agregar el código que crea el cuadro de diálogo y muestra la información. En este tutorial, usará un cuadro de mensaje de Windows Forms. En primer lugar debe agregar una referencia y una directiva using para System.Windows.Forms.

Agregar System.Windows.Forms

  1. En el Explorador de soluciones, haga clic con el botón derecho en Referencias y después elija Agregar referencia en el menú contextual.

  2. En el cuadro de diálogo Agregar referencia, en la pestaña Examinar, seleccione Examinar y busque System.Windows.Forms.DLL.

    Puede encontrar el archivo DLL en C:\Windows\Microsoft.NET\Framework\v4.0.30319.

  3. Seleccione Aceptar.

  4. En DebuggerSide.cs, agregue lo siguiente a las directivas using:

    using System.Windows.Forms;

Ahora, agregará código para crear y mostrar la interfaz de usuario del visualizador. Debido que este ejemplo es su primer visualizador, puede mantener la interfaz de usuario sencilla y utilizar un cuadro de mensaje.

Mostrar la salida del visualizador en un cuadro de diálogo

  1. En el método Show, agregue la siguiente línea de código:

    MessageBox.Show(objectProvider.GetObject().ToString());

    En este código de ejemplo, no se incluye el control de errores. Debe incluir el control de errores en un visualizador real o en cualquier otro tipo de aplicación.

  2. En el menú Compilar, elija Compilar MyFirstVisualizer. El proyecto debería compilarse correctamente. Corrija cualquier error de compilación antes de continuar.

El código del depurador ya está completo. Sin embargo, hay un paso más que realizar; el atributo que indica al lado depurado qué colección de clases incluye el visualizador.

Agregar el tipo que se va a visualizar en el código del lado depurado

En el código del depurador, especifique el tipo que se va a visualizar (el origen del objeto) en el lado depurado con el atributo DebuggerVisualizerAttribute. La propiedad Target establece el tipo que se va a visualizar.

  1. Agregue el código de atributo siguiente a DebuggerSide.cs, después de las directivas using, pero antes de namespace MyFirstVisualizer:

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

  2. En el menú Compilar, elija Compilar MyFirstVisualizer. El proyecto debería compilarse correctamente. Corrija cualquier error de compilación antes de continuar.

    En este momento, el primer visualizador está terminado. Si ha seguido los pasos correctamente, debería poder compilar el visualizador e instalarlo en Visual Studio. Sin embargo, antes de instalar un visualizador en Visual Studio, debería probarlo para asegurarse de que se ejecuta correctamente. A continuación, creará una herramienta de ejecución de pruebas para ejecutar el visualizador sin instalarlo en Visual Studio.

Agregar un método de prueba para mostrar el visualizador

  1. Agregue el método siguiente a la clase public DebuggerSide:

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

  2. En el menú Compilar, elija Compilar MyFirstVisualizer. El proyecto debería compilarse correctamente. Corrija cualquier error de compilación antes de continuar.

    Luego, debe crear un proyecto ejecutable para llamar al archivo DLL del visualizador. Para que resulte más sencillo, use un proyecto de aplicación de consola.

Agregar un proyecto de aplicación de consola a la solución

  1. En el Explorador de soluciones, haga clic con el botón derecho en la solución, elija Agregar y luego seleccione Nuevo proyecto.

  2. Elija Archivo>Nuevo>Proyecto. En la lista desplegable de lenguaje, elija C# . En el cuadro de búsqueda, escriba consola y, luego, seleccione Aplicación de consola (.NET Framework) o Aplicación de consola para .NET. Seleccione Siguiente. En el cuadro de diálogo que aparece, escriba el nombre MyTestConsole y, después, seleccione Crear.

Nota:

Si quiere probar el visualizador mediante una herramienta de ejecución de pruebas, cree una aplicación de consola de .NET Framework. En su lugar, puede crear una aplicación de consola de .NET, pero la herramienta de ejecución de pruebas que se describe más adelante todavía no es compatible con .NET, por lo que tendrá que instalar el visualizador para probarla. En el caso de una aplicación de consola de .NET, primero cree la aplicación de consola aquí, agregue el archivo DLL y las referencias de proyecto necesarios y, a continuación, siga los pasos descritos en Adición de un objeto de datos depurado. Para los escenarios de ASP.NET Core, consulte Consideraciones especiales del lado depurador para .NET 5.0+.

Ahora, debe agregar las referencias necesarias para que MyTestConsole pueda llamar a MyFirstVisualizer.

Agregar las referencias necesarias a MyTestConsole

  1. En el Explorador de soluciones, haga clic con el botón derecho en MyTestConsole y elija Agregar referencia en el menú contextual.

  2. En el cuadro de diálogo Agregar referencia, abra la pestaña Examinar y seleccione Microsoft.VisualStudio.DebuggerVisualizers.DLL.

  3. Seleccione Aceptar.

  4. Haga clic con el botón derecho en MyTestConsole y elija nuevamente Agregar referencia.

  5. En el cuadro de diálogo Agregar referencia, abra la pestaña Proyectos y seleccione MyFirstVisualizer.

  6. Seleccione Aceptar.

Ahora, agregue el código para finalizar la herramienta de ejecución de pruebas.

Agregar el código a MyTestConsole

  1. En el Explorador de soluciones, haga clic con el botón derecho en Program.cs y elija Cambiar nombre en el menú contextual.

  2. Cambie el nombre Program.cs por un nombre más significativo, como TestConsole.cs.

    Nota

    Visual Studio cambia automáticamente la declaración de clase en TestConsole.cs para que coincida con el nuevo nombre del archivo.

  3. En TestConsole.cs, agregue el siguiente código a las directivas using:

    using MyFirstVisualizer;

  4. En el método Main, agregue el código siguiente:

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

Ahora, está preparado para probar su primer visualizador.

Probar el visualizador

  1. En el Explorador de soluciones, haga clic con el botón derecho en MyTestConsole y, en el menú contextual, elija Establecer como proyecto de inicio.

  2. En el menú Depurar, elija Iniciar.

    Se iniciará la aplicación de consola y aparecerá el visualizador, que mostrará la cadena "Hello, World".

¡Enhorabuena! Ha creado y probado su primer visualizador.

Si desea utilizar el visualizador en Visual Studio, en lugar de simplemente llamarlo desde el instrumento de prueba, tendrá que instalarlo. Para obtener más información, vea Cómo: instalar un visualizador.

Adición de un objeto de datos depurado

En esta sección, se cambia del objeto de datos System.String por un objeto de datos personalizado.

  1. En el Explorador de soluciones, haga clic con el botón derecho en la solución, elija Agregar y luego seleccione Nuevo proyecto. En la lista desplegable de lenguaje, elija C# . En el cuadro de búsqueda, escriba biblioteca de clases y, después, elija Biblioteca de clases (.NET Framework) o Biblioteca de clases para .NET Standard.

    Nota

    Si usa una aplicación de consola de prueba de .NET Framework, asegúrese de crear un proyecto de biblioteca de clases de .NET Framework.

  2. Seleccione Siguiente. En el cuadro de diálogo que aparece, escriba el nombre MyDataObject y, después, seleccione Crear.

  3. (Solo para la biblioteca de clases de .NET Standard) En el Explorador de soluciones, haga clic con el botón derecho en el proyecto y elija Editar archivo de proyecto. Cambie el valor <TargetFramework> por netstandard2.0.

    <TargetFramework>netstandard2.0</TargetFramework>

  4. Dentro del espacio de nombres MyDataObject, reemplace el código predeterminado por el siguiente.

    [Serializable] 
public class CustomDataObject
{
   public CustomDataObject()
   {
      this.MyData = "MyTestData";
   }
   public string MyData { get; set; }
}

    Para un visualizador de solo lectura, como el de este ejemplo, no es necesario implementar métodos de VisualizerObjectSource.

    A continuación, actualice el proyecto MyFirstVisualizer para usar el nuevo objeto de datos.

  5. En el Explorador de soluciones del proyecto MyFirstVisualizer, haga clic con el botón derecho en el nodo Referencias y elija Agregar referencia.

  6. En Proyectos, seleccione el proyecto MyDataObject.

  7. En el código de atributo de DebuggerSide.cs, actualice el valor de Target y cambie System.String por MyDataObject.CustomDataObject.

    Target = typeof(MyDataObject.CustomDataObject),

  8. En el proyecto MyFirstVisualizer, reemplace el código del método Show por el código siguiente.

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

    En el código anterior se usa una propiedad del objeto de datos para mostrar el título del formulario.

    A continuación, actualice la aplicación de consola para usar el objeto de datos personalizado.

  9. En el Explorador de soluciones del proyecto MyTestConsole, haga clic con el botón derecho en el nodo Referencias o Dependencias y agregue una referencia de proyecto a MyDataObject.

  10. En Program.cs, reemplace el código del método Main por el código siguiente.

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

DebuggerSide.TestShowVisualizer(customDataObject);

  11. (Aplicación de consola de .NET) Incluya la llamada a TestShowVisualizer en una instrucción try-catch, ya que no se admite la herramienta de ejecución de pruebas.

    try
{
      DebuggerSide.TestShowVisualizer(customDataObject);
}
catch (Exception) {
}

    La aplicación de consola necesita una referencia del entorno de ejecución para el visualizador. Puede mantener la referencia manteniendo el código anterior en lugar de ponerlo como comentario.

  12. Para una aplicación de consola de .NET Framework, puede ejecutar la herramienta de ejecución de pruebas (presione F5), o bien seguir las instrucciones de Procedimiento para instalar un visualizador.

    Si ejecuta la aplicación mediante la herramienta de ejecución de pruebas, la aplicación muestra el formulario Windows.

  13. Para una aplicación de consola de .NET, copie MyFirstVisualizer.dll y MyDataObject.dll en las carpetas descritas en Procedimiento para instalar un visualizador.

  14. Después de instalar el visualizador, establezca un punto de interrupción, ejecute la aplicación de consola y mantenga el puntero sobre customDataObject. Si todo se ha configurado correctamente, debería ver el icono de lupa VisualizerIcon.

    Icono de lupa del visualizador.

    Al elegir MyFirstVisualizer en la lupa, verá el formulario con el texto del objeto de datos en el título.

    Formulario de Windows mostrado en el visualizador

Contenido relacionado