Partilhar via

Visualizadores de dados personalizados para o depurador do Visual Studio (.NET)

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

Um visualizador faz parte da interface do usuário do depurador do Visual Studio que exibe uma variável ou objeto de maneira apropriada ao seu tipo de dados. Por exemplo, um visualizador de bitmap interpreta uma estrutura de bitmap e exibe o gráfico que ele representa. Alguns visualizadores permitem modificar e visualizar os dados. No depurador, um visualizador é representado por um ícone de lupa VisualizerIcon. Você pode selecionar o ícone em uma DataTip, janela Watch do depurador ou caixa de diálogo QuickWatch e, em seguida, selecionar o visualizador apropriado para o objeto correspondente.

Além dos visualizadores internos padrão, mais visualizadores podem estar disponíveis para download da Microsoft, de terceiros e da comunidade. Você também pode escrever seus próprios visualizadores e instalá-los no depurador do Visual Studio.

Este artigo fornece uma visão geral de alto nível da criação do visualizador. Para obter instruções detalhadas, consulte os seguintes artigos:

Observação

Não há suporte para visualizadores personalizados para aplicativos da Plataforma Universal do Windows (UWP) e do Windows 8.x.

Visão geral

Você pode escrever um visualizador personalizado para um objeto de qualquer classe gerenciada, exceto para Object e Array.

A arquitetura de um visualizador de depurador tem duas partes:

  • A parte do depurador é executada dentro do depurador do Visual Studio e cria e exibe a interface do utilizador do visualizador.

    Como o Visual Studio é executado no .NET Framework Runtime, esse componente deve ser escrito para o .NET Framework. Por esse motivo, não é possível escrevê-lo para o .NET Core.

  • O lado do depurando é executado dentro do processo que o Visual Studio está a depurar (o depurando). O objeto de dados a ser visualizado (por exemplo, um objeto String) existe no processo de depuração. O lado do debuggee envia o objeto para o lado do depurador, que o exibe na interface do utilizador que você cria.

    O tempo de execução para o qual você cria esse componente deve corresponder àquele no qual o processo de depuração será executado, ou seja, .NET Framework ou .NET Core.

O lado do depurador recebe o objeto de dados de um provedor de objetos que implementa a interface IVisualizerObjectProvider. O lado do depurador envia o objeto através da fonte do objeto, que é derivada de VisualizerObjectSource.

O provedor de objetos também pode enviar dados de volta para a fonte do objeto, o que permite escrever um visualizador que pode editar dados. Você substitui o provedor de objeto para falar com o avaliador de expressão e a fonte do objeto.

O lado do depurado e o lado do depurador comunicam-se entre si por meio de Stream métodos que serializam um objeto de dados em um Stream e desserializam o Stream de volta em um objeto de dados.

Você pode escrever um visualizador para um tipo genérico somente se o tipo for um tipo aberto. Essa restrição é a mesma que a restrição ao usar o DebuggerTypeProxy atributo. Para obter detalhes, consulte Usar o atributo DebuggerTypeProxy.

Os visualizadores personalizados podem ter considerações de segurança. Consulte Considerações de segurança do Visualizer.

Criar a interface de usuário do lado do depurador

Para criar a interface do utilizador do visualizador no lado do depurador, crie uma classe que herda de DialogDebuggerVisualizer e substitua o método Microsoft.VisualStudio.DebuggerVisualizers.DialogDebuggerVisualizer.Show para exibir a interface. Você pode usar IDialogVisualizerService para exibir formulários, caixas de diálogo e controles do Windows no visualizador.

  1. Use IVisualizerObjectProvider métodos para obter o objeto visualizado do lado do depurador.

  2. Crie uma classe que herda do DialogDebuggerVisualizer.

Observação

Devido aos problemas de segurança descritos na secção abaixo, a partir do Visual Studio 2022 versão 17.11, os visualizadores não poderão especificar a política de formatação Legacy no construtor da classe base. A partir de agora, os visualizadores só podem usar a serialização JSON para se comunicar entre o depurador e os componentes do lado do depurador .

  1. Substitua o método Microsoft.VisualStudio.DebuggerVisualizers.DialogDebuggerVisualizer.Show para exibir a sua interface. Use IDialogVisualizerService métodos para exibir formulários, caixas de diálogo e controles do Windows em sua interface.

  2. Aplique DebuggerVisualizerAttribute, atribuindo-lhe o visualizador para exibição (DialogDebuggerVisualizer).

Considerações especiais do lado do depurador para o .NET 5.0+

Os visualizadores personalizados transferem dados entre os lados do depurador e do depurador por meio da serialização binária usando a BinaryFormatter classe por padrão. No entanto, esse tipo de serialização está sendo restringido no .NET 5 e acima devido a preocupações de segurança em relação às suas vulnerabilidades incorrigíveis . Além disso, ele foi marcado como completamente obsoleto no ASP.NET Core 5 e seu uso resultará em um erro conforme descrito na documentação do ASP.NET Core. Esta seção descreve as etapas que você deve seguir para garantir que seu visualizador ainda seja suportado nesse cenário.

  • Por motivos de compatibilidade, o Show método que foi sobrescrito na seção anterior ainda aceita um IVisualizerObjectProvider. No entanto, a partir da versão 16.10 do Visual Studio 2019, ele é efetivamente do tipo IVisualizerObjectProvider3. Por esse motivo, lance o objectProvider objeto para a interface atualizada.

  • Ao enviar objetos, como comandos ou dados, para o lado do debuggee, use o método IVisualizerObjectProvider2.Serialize para passá-los para um fluxo de dados, que determinará o melhor formato de serialização a ser usado com base no ambiente de execução do processo do debuggee. Em seguida, passe o fluxo para o IVisualizerObjectProvider2.TransferData método.

  • Se o componente do visualizador do lado do depurador precisar retornar algo para o lado do depurador, ele estará localizado no Stream objeto retornado pelo TransferData método. Use o IVisualizerObjectProvider2.GetDeserializableObjectFrom método para obter uma IDeserializableObject instância dele e processá-lo conforme necessário, ou use DeserializeFromJson se for um tipo que você sabe como desserializar.

Consulte a seção Considerações especiais do lado do depurador para o .NET 5.0+ para saber quais outras alterações são necessárias no lado do depurador quando o uso da serialização binária não é suportado.

Observação

Se desejar obter mais informações sobre o problema, consulte o guia de segurança BinaryFormatter.

Criar a fonte de objeto do visualizador para o lado do depurador

No código do lado do depurador, edite o DebuggerVisualizerAttribute, dando-lhe o tipo a ser visualizado (a origem do objeto do lado do depurador) (VisualizerObjectSource). A Target propriedade define a origem do objeto. Se você omitir a fonte do objeto, o visualizador usará uma fonte de objeto padrão.

O código lateral do depurador contém a fonte do objeto que é visualizada. O objeto de dados pode substituir métodos de VisualizerObjectSource. Uma DLL do lado do debuggee é necessária se você quiser criar um visualizador autônomo.

No código do lado do depurador:

  • Para permitir que o visualizador edite objetos de dados, a fonte do objeto VisualizerObjectSource deve herdar e sobrescrever os métodos TransferData ou CreateReplacementObject.

  • Se você precisar oferecer suporte a multisegmentação em seu visualizador, poderá usar os seguintes Target Framework Monikers (TFMs) no arquivo de projeto do lado do depurador.

    <TargetFrameworks>net20;netstandard2.0;netcoreapp2.0</TargetFrameworks>

    Estes são os únicos TFMs suportados.

Considerações especiais do lado do depurador para o .NET 5.0+

Importante

Etapas adicionais podem ser necessárias para que um visualizador funcione a partir do .NET 5.0 devido a preocupações de segurança relacionadas ao método de serialização binária subjacente usado por padrão. Leia esta secção antes de continuar.

  • Se o visualizador implementar o método TransferData, use o método GetDeserializableObject, recém-adicionado que está disponível na versão mais recente do VisualizerObjectSource. O IDeserializableObject retornado ajuda a determinar o formato de serialização do objeto (binário ou JSON) e a desserializar o objeto subjacente para que possa ser utilizado.

  • Se o lado do depurador retornar dados para o lado do depurador como parte da TransferData chamada, serialize a resposta para o fluxo do lado do depurador por meio do Serialize método.

Conteúdo relacionado

  • Last updated on