Instruções passo a passo: escrevendo um visualizador em C#

Este passo a passo mostra como escrever um visualizador simples usando C#. O visualizador criado neste passo a passo exibe o conteúdo de uma cadeia de caracteres usando um Formulário do Windows. Esse visualizador simples de cadeia de caracteres não é especialmente útil em si mesmo, mas mostra as etapas básicas a seguir para criar visualizadores mais úteis para outros tipos de dados.

O código do visualizador deve ser colocado em um arquivo DLL que o depurador lê. Consequentemente, a primeira etapa é criar um projeto da Biblioteca de Classes para a DLL.

Criar um visualizador manualmente

Conclua as tarefas a seguir para criar um visualizador.

Criar um projeto de biblioteca de classes

1. Para criar um novo projeto de biblioteca de classes, selecione Arquivo>Novo>Projeto.

2. Na lista suspensa de idiomas, selecione C#.

3. Na caixa de pesquisa, insira biblioteca de classes. Selecione Biblioteca de Classes (.NET Framework) e, depois, Avançar.

4. Na caixa de diálogo, insira o nome MyFirstVisualizere selecione Criar.

Para o projeto do visualizador, selecione uma biblioteca de classes .NET Framework, e não o .NET. Embora o visualizador precise ser .NET Framework, o aplicativo de chamada pode ser .NET.

Depois de criar a biblioteca de classes, você deve adicionar uma referência ao arquivo Microsoft.VisualStudio.DebuggerVisualizers.DLL para poder usar as classes definidas lá. Antes de adicionar a referência, você deve renomear algumas classes para usar nomes significativos.

Para renomear Class1.cs e adicionar Microsoft.VisualStudio.DebuggerVisualizers

1. No Gerenciador de Soluções, clique com o botão direito do mouse em Class1.cs e escolha Renomear no menu de atalho.

2. Altere o nome de Class1.cs para algo significativo, por exemplo, DebuggerSide.cs.

   Observação

   O Visual Studio automaticamente altera a declaração de classes em DebuggerSide.cs para corresponder ao novo nome do arquivo. Se você vir uma solicitação para concluir a ação, selecione Sim.

3. No Gerenciador de Soluções, clique com o botão direito do mouse em Referências e escolha Adicionar Referência no menu de atalho.

4. Na caixa de diálogo Adicionar Referência, na guia Procurar, selecione Procurar e localize o Microsoft.VisualStudio.DebuggerVisualizers.DLL.

   Você pode encontrar a DLL no <Diretório de Instalação do Visual Studio>\Common7\IDE\PublicAssemblies subdiretório do diretório de instalação do Visual Studio.

5. Selecione OK.

6. Em DebuggerSide.cs, adicione a seguinte às diretivas using:

   using Microsoft.VisualStudio.DebuggerVisualizers;
   

Agora, você está pronto para criar o código do lado do depurador. Esse código é executado no depurador para exibir as informações que você deseja visualizar. Primeiro, você precisa alterar a declaração do objeto DebuggerSide para configurar a herança da classe base DialogDebuggerVisualizer.

Herde do DialogDebuggerVisualizer

1. Em DebuggerSide.cs, vá para a seguinte linha de código:

   public class DebuggerSide
   

2. Altere o código para:

   public class DebuggerSide : DialogDebuggerVisualizer
   

3. Adicione um construtor vazio para que você possa passar para o construtor da classe base a política de serialização que será usada para se comunicar entre os componentes do visualizador.

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

   Observação

   Devido aos problemas de segurança descritos em Considerações especiais do lado do depurador para o .NET 5.0+, a partir do Visual Studio 2022 versão 17.11, os visualizadores não poderão especificar a política Legacy do formatador.

4. DialogDebuggerVisualizer tem um método abstrato (Show) que você deve substituir.

Substitua o método DialogDebuggerVisualizer.Show

Em public class DebuggerSide, adicione o seguinte método:

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

O método Show contém o código que realmente cria a caixa de diálogo DO visualizador ou outra interface de usuário e exibe as informações que foram passadas para o visualizador do depurador. Adicione o código que cria a caixa de diálogo e exibe as informações. Neste passo a passo, você usa uma caixa de mensagem do Windows Forms. Primeiro, você deve adicionar uma referência e uma diretiva using para System.Windows.Forms.

Adicione System.Windows.Forms

1. No Gerenciador de Soluções, clique com o botão direito do mouse em Referências e escolha Adicionar Referência no menu de atalho.

2. Na caixa de diálogo Adicionar Referência, na guia Procurar, selecione Procurar e localize o System.Windows.Forms.DLL.

   Você pode encontrar a DLL em C:\Windows\Microsoft.NET\Framework\v4.0.30319.

3. Selecione OK.

4. Em DebuggerSide.cs, adicione a seguinte às diretivas using:

   using System.Windows.Forms;
   

Agora, você adiciona um código para criar e mostrar a interface do usuário no seu visualizador. Como esse é seu primeiro visualizador, você manterá a interface do usuário simples e usará uma caixa de mensagem.

Mostre a Saída do Visualizador em uma caixa de diálogo

1. No método Show, adicione a linha de código a seguir:

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

   Esse código de exemplo não inclui tratamento de erros. Você deve incluir o tratamento de erros em um visualizador real ou qualquer outro tipo de aplicativo.

2. No menu Compilar, escolha Compilar MyFirstVisualizer. O projeto deve ser compilado com êxito. Corrija os erros de compilação antes de continuar.

O código lateral do depurador já está concluído. Há mais uma etapa, entretanto; o atributo que informa ao lado depurado qual coleção de classes compreende o visualizador.

Adicione o tipo para visualizar o código do lado do depurador

No código do lado do depurador, especifique o tipo a ser visualizado (a origem do objeto) para o depurador usando o atributo DebuggerVisualizerAttribute. A propriedade Target define o tipo a ser visualizado.

1. Adicione o seguinte código do atributo a DebuggerSide.cs, depois das diretivas using, mas antes de namespace MyFirstVisualizer:

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

2. No menu Compilar, escolha Compilar MyFirstVisualizer. O projeto deve ser compilado com êxito. Corrija os erros de compilação antes de continuar.

   Neste momento, o primeiro visualizador é concluído. Se você seguiu as etapas corretamente, poderá compilar o visualizador e instalá-lo no Visual Studio. Antes de instalar um visualizador no Visual Studio, no entanto, você deverá testá-lo para garantir que seja executado corretamente. Agora, você criará um agente de teste para executar o visualizador sem instalá-lo no Visual Studio.

Adicione um método de teste para mostrar o visualizador

1. Adicione o método a seguir à classe public DebuggerSide.

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

2. No menu Compilar, escolha Compilar MyFirstVisualizer. O projeto deve ser compilado com êxito. Corrija os erros de compilação antes de continuar.

   Em seguida, você deverá criar um projeto executável para chamar sua DLL do visualizador. Para simplificar, use um projeto de Aplicativo de Console.

Adicione um projeto de aplicativo de console à solução

1. No Gerenciador de Soluções, clique com o botão direito do mouse na solução, escolha Adicionare selecione Novo Projeto.

2. Escolha Arquivo>Novo>Projeto. Na lista suspensa de linguagens, escolha C#. Na caixa de pesquisa, digite aplicativo de console e escolha Aplicativo de Console (.NET Framework) ou Aplicativo de Console para .NET. Selecione Avançar. Na caixa de diálogo exibida, digite o nome MyTestConsolee selecione Criar.

Agora, você deve adicionar as referências necessárias para que MyTestConsole possa chamar MyFirstVisualizer.

Adicione as referências necessárias ao MyTestConsole

1. No Gerenciador de Soluções, clique com o botão direito do mouse em MyTestConsole e escolha Adicionar Referência no menu de atalho.

2. Na caixa de diálogo Adicionar Referência, abra a guia Procurar e selecione Microsoft.VisualStudio.DebuggerVisualizers.DLL.

3. Selecione OK.

4. Clique com o botão direito do mouse em MyTestConsole e escolha Adicionar Referência novamente.

5. Na caixa de diálogo Adicionar Referência, clique na guia Projetos e selecione MyFirstVisualizer.

6. Selecione OK.

Agora, você adicionará o código para concluir um agente de teste.

Adicione o código ao MyTestConsole

1. No Gerenciador de Soluções, clique com o botão direito do mouse em Program.cs e escolha Renomear no menu de atalho.

2. Edite o nome de Program.cs para algo mais significativo, por exemplo, TestConsole.cs.

   Observação

   O Visual Studio altera automaticamente a declaração de classes em TestConsole.cs para corresponder ao novo nome do arquivo.

3. Em TestConsole.cs, adicione o seguinte código às diretivas using:

   using MyFirstVisualizer;
   

4. No método Main, adicione o seguinte código:

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

Agora, você está pronto para testar seu primeiro visualizador.

Teste o visualizador

1. No Gerenciador de Soluções, clique com o botão direito do mouse em MyTestConsole e escolha Definir como Projeto de Inicialização no menu de atalho.

2. No menu Depurar, escolha Iniciar.

   O aplicativo de console inicia e o visualizador aparece e exibe a cadeia de caracteres “Hello World”.

Parabéns. Você criou e testou seu primeiro visualizador!

Se você quiser usar o visualizador no Visual Studio em vez de apenas chamá-lo do teste automatizado, será preciso instalá-lo. Para obter mais informações, consulte Como instalar um visualizador.

Adicionar um objeto de dados do lado do depurado

Nesta seção, você alterna do objeto de dados System.String para um objeto de dados personalizado.

1. No Gerenciador de Soluções, clique com o botão direito do mouse na solução, escolha Adicionare selecione Novo Projeto. Na lista suspensa de linguagens, escolha C#. Na caixa de pesquisa, digite biblioteca de classes e escolha Biblioteca de Classes (.NET Framework) ou Biblioteca de Classes para .NET Standard.

   Observação

   Se você estiver usando um aplicativo de console de teste .NET Framework, crie um projeto de biblioteca de classes .NET Framework.

2. Selecione Avançar. Na caixa de diálogo exibida, digite o nome MyDataObjecte selecione Criar.

3. (somente biblioteca de classes .NET Standard) No Gerenciador de Soluções, clique com o botão direito do mouse no projeto e escolha Editar Arquivo de Projeto. Altere o valor de <TargetFramework> para netstandard2.0.

   <TargetFramework>netstandard2.0</TargetFramework>
   

4. Dentro do namespace MyDataObject, substitua o código padrão pelo código a seguir.

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

   Para um visualizador somente leitura, como neste exemplo, não é necessário implementar os métodos de VisualizerObjectSource.

   Em seguida, atualize o projeto MyFirstVisualizer para usar o novo objeto de dados.

5. No Gerenciador de Soluções no projeto MyFirstVisualizer, clique com o botão direito do mouse no nó Referências e escolha Adicionar Referência.

6. Em Projetos, selecione o projeto MyDataObject.

7. No código de atributo de DebuggerSide.cs, atualize o valor de destino, alterando System.String para MyDataObject.CustomDataObject.

   Target = typeof(MyDataObject.CustomDataObject),
   

8. No projeto MyFirstVisualizer, substitua o código do método Show pelo código a seguir.

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

   O código anterior usa uma propriedade do objeto de dados para mostrar no título do Formulário.

   Em seguida, atualize o aplicativo de console para usar o objeto de dados personalizado.

9. No Gerenciador de Soluções no projeto MyTestConsole, clique com o botão direito do mouse no nó Referências ou Dependências e adicione uma referência de projeto a MyDataObject.

10. Em Program.cs, substitua o código no método Main pelo código a seguir.

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

11. (aplicativo de console.NET) Coloque a chamada para TestShowVisualizer em uma instrução try-catch, já que o agente de teste não tem suporte.

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

    O aplicativo de console precisa de uma referência de runtime para o visualizador. Você pode manter a referência mantendo o código anterior em vez de comentá-lo.

12. Para um aplicativo de console .NET Framework, você pode executar o agente de teste (pressione F5) ou siga as instruções em Como instalar um visualizador.

    Se você executar o aplicativo usando o agente de teste, o aplicativo mostrará o Formulário do Windows.

13. Para um aplicativo de console do .NET, copie o MyFirstVisualizer.dll e o MyDataObject.dll para as pastas descritas em Como instalar um visualizador.

14. Depois de instalar o visualizador, defina um ponto de interrupção, execute o aplicativo de console e passe o mouse sobre customDataObject. Se tudo estiver configurado corretamente, você deverá ver o ícone de lupa .

    

    Ao escolher MyFirstVisualizer na lupa, você verá o Formulário com o texto do objeto de dados no título.

    

Conteúdo relacionado

• Arquitetura do visualizador
• Como instalar um visualizador
• Criar visualizadores personalizados