Visualizadores de dados personalizados do depurador do Visual Studio (.NET)
Importante
A partir do Visual Studio 2022 versão 17.9, os visualizadores podem ser escritos em .NET 6.0+ que são executados fora do processo usando o novo modelo VisualStudio.Extensibility. Incentivamos os autores de visualizadores a fazer referência à nova documentação em Criar visualizadores de depurador do Visual Studio, a menos que desejem oferecer suporte a versões mais antigas do Visual Studio ou desejem enviar seus visualizadores personalizados como parte de uma DLL de biblioteca.
Um visualizador é uma parte da interface do usuário do depurador do Visual Studio que exibe uma variável ou um objeto de maneira apropriada ao seu tipo de dados. Por exemplo, um visualizador do bitmap interpreta uma estrutura do bitmap e exibe o gráfico que ele representa. Alguns visualizadores permitem modificar, bem como exibir, os dados. No depurador, um visualizador é representado por um ícone de lupa 
. Você pode selecionar o ícone em uma DataTip, uma janela Inspeção do depurador ou uma caixa de diálogo QuickWatch e, em seguida, selecionar o visualizador adequado ao objeto correspondente.
Além dos visualizadores internos padrão, mais visualizadores podem estar disponíveis para download na Microsoft, em terceiros e na comunidade. Você também pode escrever seus 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, confira os seguintes artigos:
- Passo a passo: Escrever um visualizador em C#
- Passo a passo: Escrever um visualizador em Visual Basic
- Instalar um visualizador
- Na documentação do Natvis, confira o elemento UIVisualizer. Confira também o exemplo do Visualizador de depurador nativo do SQLite.
Observação
Não há suporte para visualizadores personalizados em 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 com exceção de Object ou Array.
A arquitetura de um visualizador de depurador tem duas partes:
O lado do depurador é executado no depurador do Visual Studio e cria e exibe a interface do usuário do visualizador.
Como o Visual Studio é executado no .NET Framework Runtime, esse componente precisa ser escrito para o .NET Framework. Por esse motivo, não é possível escrevê-lo para o .NET Core.
O lado a ser depurado é executado dentro do processo que o Visual Studio está depurando (o lado a ser depurado). O objeto de dados a ser visualizado (por exemplo, um objeto String) existe no processo no depurador. O lado do depurado envia o objeto para o lado do depurador, que o exibe na interface do usuário que você cria.
O runtime para o qual você compila esse componente deve corresponder àquele que o processo do depurado será executado, ou seja, .NET Framework ou .NET Core.
O lado do depurador recebe o objeto de dados de um provedor de objeto que implementa a interface IVisualizerObjectProvider. O lado do depurado envia o objeto por meio da origem do objeto, que é derivada de VisualizerObjectSource.
O provedor do objeto também pode enviar dados de volta para a origem do objeto, que permite escrever um visualizador que pode editar dados. Substitua o provedor de objetos para se comunicar com o avaliador de expressão e a origem do objeto.
O lado do depurado e o lado do depurador se comunicam entre si por meio de métodos Stream que serializam um objeto de dados em um Stream e desserializam o Stream de volta em um objeto de dados.
Você poderá 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 atributo DebuggerTypeProxy. Para obter detalhes, consulte Usar o atributo DebuggerTypeProxy.
Os visualizadores personalizados podem ter considerações de segurança. Confira Considerações de segurança do visualizador.
Criar a interface do usuário do lado do depurador
Para criar a interface do usuário do visualizador no lado do depurador, você cria uma classe que herda de DialogDebuggerVisualizer e substitui 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.
Use os métodos IVisualizerObjectProvider para obter o objeto visualizado no lado do depurador.
Crie uma classe que herda de DialogDebuggerVisualizer.
Observação
Devido aos problemas de segurança descritos na seção abaixo, a partir do Visual Studio 2022 versão 17.11, os visualizadores não poderão especificar a política de formatador Legacy no construtor da classe base. A partir de agora, os visualizadores só poderão usar a serialização JSON para se comunicar entre o depurador e os componentes do lado do depurador.
Substitua o método Microsoft.VisualStudio.DebuggerVisualizers.DialogDebuggerVisualizer.Show para exibir sua interface. Use os métodos IDialogVisualizerService para exibir os formulários, as caixas de diálogo e os controles do Windows na interface.
Aplique DebuggerVisualizerAttribute, dando a ele o visualizador para exibir (DialogDebuggerVisualizer).
Considerações especiais do lado do depurador para .NET 5.0+
Visualizadores personalizados transferem dados entre os lados do depurado e do depurador por meio da serialização binária usando a classe BinaryFormatter por padrão. No entanto, esse tipo de serialização está sendo reduzido no .NET 5 e superior devido a preocupações de segurança em relação às vulnerabilidades não corrigíveis. Além disso, ele foi marcado como completamente obsoleto no ASP.NET Core 5 e seu uso será gerado conforme descrito na Documentação do ASP.NET Core. Esta seção descreve as etapas que você deve seguir para garantir que o visualizador ainda tenha suporte nesse cenário.
Por motivos de compatibilidade, o método Show que foi substituído na seção anterior ainda usa um IVisualizerObjectProvider. No entanto, começando no Visual Studio 2019 versão 16.10, ele é, na verdade, do tipo IVisualizerObjectProvider3. Por esse motivo, converta o objeto
objectProviderna interface atualizada.Ao enviar objetos, como comandos ou dados, para o lado do depurado, use o método
IVisualizerObjectProvider2.Serializepara passá-lo para um fluxo; ele determinará o melhor formato de serialização a ser usado com base no runtime do processo do depurado. Em seguida, passe o fluxo para o métodoIVisualizerObjectProvider2.TransferData.Se o componente do visualizador do lado do depurado precisar retornar algo para o lado do depurador, isso estará localizado no objeto Stream retornado pelo método TransferData. Use o
IVisualizerObjectProvider2.GetDeserializableObjectFrommétodo para obter uma IDeserializableObject instância dele e processá-la 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 depurado do .NET 5.0+ para saber quais outras alterações são necessárias no lado do depurado quando o uso da Serialização Binária não tem suporte.
Observação
Se quiser obter mais informações sobre o problema, consulte o Guia de segurança do BinaryFormatter.
Para criar a origem do objeto do visualizador do lado do depurador
No código do lado do depurado, edite o DebuggerVisualizerAttribute, dando a ele o tipo a ser visualizado (a origem do objeto do lado do depurado) (VisualizerObjectSource). A propriedade Target define a origem do objeto. Se você omitir a origem do objeto, o visualizador usará uma fonte de objeto padrão.
O código do lado do depurado contém a origem do objeto que é visualizado. O objeto de dados pode substituir métodos de VisualizerObjectSource. Uma DLL do lado do depurado será necessária se você quiser criar um visualizador autônomo.
No código do lado do depurado:
Para permitir que o visualizador edite objetos de dados, a origem do objeto precisa herdar de VisualizerObjectSource e substituir os métodos
TransferDataouCreateReplacementObject.Se você precisar dar suporte a vários destinos no visualizador, poderá usar os seguintes TFMs (Monikers da Estrutura de Destino) no arquivo de projeto do lado do depurado.
<TargetFrameworks>net20;netstandard2.0;netcoreapp2.0</TargetFrameworks>Esses são os únicos TFMs com suporte.
Considerações especiais do lado do depurado para .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 em relação ao método de serialização binária subjacente usado por padrão. Leia esta seçã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 que ele retorna ajuda a determinar o formato de serialização do objeto (binário ou JSON) e a desserializar o objeto subjacente para que ele possa ser usado.Se o lado do depurado retornar dados para o lado do depurador como parte da chamada
TransferData, serialize a resposta para o fluxo do lado do depurador por meio do método Serialize.