Compartilhar via

Passo a passo: escrevendo um visualizador em C#

Importante

A partir do Visual Studio 2022 versão 17.9, os visualizadores agora podem ser escritos no .NET 6.0+ que são executados fora do processo usando o novo modelo VisualStudio.Extensibility. Para extensões criadas usando o novo modelo, consulte a documentação no Criar visualizadores de depurador do Visual Studio. Se você precisar dar suporte a versões mais antigas do Visual Studio ou quiser enviar seus visualizadores personalizados como parte de uma DLL de biblioteca, use as informações neste artigo, que se aplicam apenas ao modelo mais antigo de desenvolvimento de extensão (VSSDK).

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 de cadeia de caracteres simples não é especialmente útil em si mesmo, mas mostra as etapas básicas que você deve seguir para criar visualizadores mais úteis para outros tipos de dados.

Observação

As caixas de diálogo e os comandos de menu que você vê podem ser diferentes daqueles descritos na Ajuda, dependendo de suas configurações ativas ou edição. Para alterar suas configurações, vá para o menu Ferramentas e escolha Importar e Exportar Configurações. Para obter mais informações, consulte Redefinir configurações.

O código do visualizador deve ser colocado em um arquivo DLL que o depurador lê. Portanto, 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 selecione Avançar.

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

Para o projeto do visualizador, selecione uma biblioteca de classes do .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.

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 selecione Renomear no menu de contexto.

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

    Observação

    O Visual Studio altera automaticamente a declaração de classe em DebuggerSide.cs para corresponder ao novo nome de arquivo. Se você vir um prompt 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 o seguinte às using diretivas:

    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.

Herdar de 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 nas considerações especiais do depurador para .NET 5.0+, os visualizadores, a partir da versão 17.11 do Visual Studio 2022, não poderão especificar a Legacy política de formatação.

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

Sobrescrever o método DialogDebuggerVisualizer.Show

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

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

O Show método contém o código que realmente cria a caixa de diálogo do visualizador ou outra interface do usuário e exibe as informações que foram passadas para o visualizador do depurador. Você deve adicionar 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.

Adicionar 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 o seguinte às using diretivas:

    using System.Windows.Forms;

Agora, você adiciona algum código para criar e mostrar a interface do usuário para o visualizador. Como este exemplo é seu primeiro visualizador, você pode manter a interface do usuário simples e usar uma Caixa de Mensagem.

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

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

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

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

  2. No menu Compilar , escolha Criar MyFirstVisualizer. O projeto deve ser construído com êxito. Corrija os erros de build antes de continuar.

O código do lado do depurador agora está concluído. Há mais uma etapa, no entanto; um atributo que informa o lado do depurador sobre qual coleção de classes compreende o visualizador.

Adicionar o tipo para visualizar o código do lado de depuração

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

  1. Adicione o seguinte código de atributo a DebuggerSide.cs, após as using diretivas, mas antes namespace MyFirstVisualizer:

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

  2. No menu Compilar , escolha Criar MyFirstVisualizer. O projeto deve ser construído com êxito. Corrija os erros de build antes de continuar.

    Neste ponto, seu primeiro visualizador está concluído. Se você seguiu as etapas corretamente, poderá criar o visualizador e instalá-lo no Visual Studio. No entanto, antes de instalar um visualizador no Visual Studio, você deve testá-lo para garantir que ele seja executado corretamente. Agora você cria um cinto de teste para executar o visualizador sem instalá-lo no Visual Studio.

Adicionar um método de teste para mostrar o visualizador

  1. Adicione o seguinte método à classe public DebuggerSide:

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

  2. No menu Compilar , escolha Criar MyFirstVisualizer. O projeto deve ser construído com êxito. Corrija os erros de build antes de continuar.

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

Adicionar 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 Adicionar e selecione Novo Projeto.

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

Observação

Se você quiser testar facilmente o visualizador usando um cinto de teste, crie um aplicativo de console do .NET Framework. Em vez disso, você pode criar um aplicativo de console do .NET, mas o cinto de teste descrito posteriormente ainda não tem suporte para .NET, portanto, você precisará instalar o visualizador para testá-lo. Para um aplicativo de console do .NET, primeiro crie o aplicativo de console aqui, adicione a DLL e as referências de projeto necessárias e siga as etapas descritas em Adicionar um objeto de dados do lado de depuração. Para cenários do ASP.NET Core, consulte as Considerações Especiais do Lado do Depurador para o .NET 5.0+.

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

Adicionar 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 , abra a guia Projetos e selecione MyFirstVisualizer.

  6. Selecione OK.

Agora, você adiciona o código para concluir o arreio de teste.

Adicionar 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, como TestConsole.cs.

    Observação

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

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

    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.

Testar 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 é iniciado e o Visualizador aparece e exibe a string "Olá, Mundo".

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 cinto de teste, será necessário instalá-lo. Para obter mais informações, consulte Como instalar um visualizador.

Adicionar um objeto de dados do lado de depuração

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

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

    Observação

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

  2. Selecione Próximo. Na caixa de diálogo exibida, digite o nome MyDataObjecte selecione Criar.

  3. (somente biblioteca de classes do .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 <TargetFramework> valor para netstandard2.0.

    <TargetFramework>netstandard2.0</TargetFramework>

  4. Dentro do MyDataObject namespace, 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 de somente leitura, como neste exemplo, não é necessário implementar 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 Show método 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 Main método pelo código a seguir.

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

DebuggerSide.TestShowVisualizer(customDataObject);

  11. (Aplicativo de console do .NET) Coloque a chamada TestShowVisualizer em uma instrução try-catch, já que o cinto 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 deixando o código anterior em vez de comentá-lo.

  12. Para um aplicativo de console do .NET Framework, você pode executar o harnês de teste (pressione F5) ou seguir as instruções em Como: Instalar um Visualizador.

    Se você executar o aplicativo usando o cinto 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 How to: Install a Visualizer.

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

    Ícone de lupa do visualizador.

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

    Visualizador mostrando um Formulário do Windows

Conteúdo relacionado

  • Last updated on