Partilhar 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 depuração do Visual Studio. Se você precisar oferecer 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 aplica somente 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 Windows Form. Este visualizador de cadeia de caracteres simples não é especialmente útil em si, 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 exibidos podem ser diferentes dos descritos na Ajuda, dependendo das configurações ativas ou da 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 de 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 idioma, selecione C#.

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

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

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

Depois de criar a biblioteca de classes, 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.

Renomeie Class1.cs e adicione 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

    Visual Studio altera automaticamente a declaração de classe em DebuggerSide.cs para corresponder ao novo nome de arquivo. Se vir um pedido 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 <subdiretório Install Directory>\Common7\IDE\PublicAssemblies do diretório de instalação do Visual Studio.

  5. Selecione OK.

  6. Em DebuggerSide.cs, aditar 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 dentro do depurador para exibir as informações que você deseja visualizar. Primeiro, deve alterar a declaração do objeto DebuggerSide para configurar a herança a partir da classe base DialogDebuggerVisualizer.

Herdar de DialogDebuggerVisualizer

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

    public class DebuggerSide

  2. Alterar 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 do formatador Legacy.

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

Substituir o método Show do DialogDebuggerVisualizer

No 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 a partir do depurador. Você deve adicionar o código que cria a caixa de diálogo e exibe as informações. Nesta explicação passo a passo, você usa uma caixa de mensagem do Windows Forms. Primeiro, você deve adicionar uma referência e using diretiva 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, aditar 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 seu 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 Build , escolha Build MyFirstVisualizer. O projeto deve ser construído com sucesso. Corrija quaisquer erros de compilação antes de continuar.

O código lateral do depurador agora está completo. No entanto, há mais um passo; O atributo que informa ao lado do depurador 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, você especifica 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 de namespace MyFirstVisualizer:

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

  2. No menu Build , escolha Build MyFirstVisualizer. O projeto deve ser construído com sucesso. Corrija quaisquer erros de compilação antes de continuar.

    Neste ponto, seu primeiro visualizador está concluído. Se você tiver seguido as etapas corretamente, você pode criar o visualizador e instalá-lo no Visual Studio. Antes de instalar um visualizador no Visual Studio, no entanto, você deve testá-lo para certificar-se de que ele é executado corretamente. Agora você cria um conjunto 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 Build , escolha Build MyFirstVisualizer. O projeto deve ser construído com sucesso. Corrija quaisquer erros de compilação antes de continuar.

    Em seguida, você deve criar um projeto executável para chamar sua 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 aplicativo de console e escolha Aplicativo de Console (.NET Framework) ou Aplicativo de Console para .NET. Selecione Seguinte. Na caixa de diálogo apresentada, escreva o nome MyTestConsolee, em seguida, selecione Criar.

Observação

Se você quiser testar facilmente o visualizador usando um conjunto de teste, crie um aplicativo de console do .NET Framework. Em vez disso, você pode criar um aplicativo de console .NET, mas o conjunto de teste descrito posteriormente ainda não é suportado para o .NET, portanto, você precisará instalar o visualizador para testá-lo. Para um aplicativo de console .NET, primeiro crie o aplicativo de console aqui, adicione a DLL necessária e as referências de projeto e siga as etapas descritas em Adicionar um objeto de dados do lado do depurador. Para cenários ASP.NET Core, consulte Considerações especiais do lado de depuração 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 a 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 conjunto de teste.

Adicionar código a 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 no TestConsole.cs para corresponder ao novo nome de 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 cadeia de caracteres "Olá, Mundo".

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

Se você quiser usar seu visualizador no Visual Studio em vez de apenas chamá-lo a partir do conjunto de teste, você precisa instalá-lo. Para obter mais informações, consulte Como instalar um visualizador.

Adicionar um objeto de dados do lado do depurador

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 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 do .NET Framework, certifique-se de criar um projeto de biblioteca de classes do .NET Framework.

  2. Selecione Seguinte. Na caixa de diálogo apresentada, escreva o nome MyDataObjecte, em seguida, 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 <TargetFramework> 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 leitura única, 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 Target, alterando System.String para MyDataObject.CustomDataObject.

    Target = typeof(MyDataObject.CustomDataObject),

  8. No projeto MyFirstVisualizer, substitua o código para o Show método com o 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 ao MyDataObject.

  10. No ficheiro Program.cs, substitua o código no método Main pelo seguinte código.

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

DebuggerSide.TestShowVisualizer(customDataObject);

  11. (aplicação de consola .NET) Coloque a chamada em TestShowVisualizer dentro de uma instrução try-catch, uma vez que a estrutura de teste não é suportada.

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

    O aplicativo de console precisa de uma referência de tempo de execução 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 do .NET Framework, você pode executar o conjunto de teste (pressione F5) ou seguir as instruções em Como instalar um visualizador.

    Se você executar o aplicativo usando o conjunto de teste, o aplicativo mostrará o Windows Form.

  13. Para uma aplicação de console .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ê verá o ícone da lupa ícone do VisualizerIcon.

    Ícone de lupa do visualizador.

    Quando você escolhe MyFirstVisualizer na lupa, você vê o formulário com o texto do objeto de dados no título.

    Visualizador mostrando um Windows Form

Conteúdo relacionado

  • Last updated on