Skip to content

MANUAL.md

Latest commit

 

History

History
207 lines (140 loc) · 13.9 KB

MANUAL.md

File metadata and controls

207 lines (140 loc) · 13.9 KB
Raw

Manual do TDataSet Visualizer para Delphi

🌐 English · Português (BR)

O que é: um debug visualizer da IDE do Delphi que permite inspecionar qualquer descendente de TDataSet (incluindo TClientDataSet e TFDMemTable/FireDAC) em uma janela rica com DBGrid enquanto a execução está parada em um breakpoint.

É um pacote somente design-time (BPL). Não há componente de runtime para instalar na sua aplicação.

Dúvidas, sugestões ou relato de bugs: abra uma issue no GitHub

Sumário

  1. Instalação
  2. Como usar
  3. Ferramentas (barra de tarefas e abas)
  4. Recursos
  5. Atalhos de teclado
  6. Limitações e observações
  7. Projeto de demonstração
  8. Contato

1. Instalação

O projeto é distribuído somente como código-fonte. A instalação é feita inteiramente dentro da IDE do Delphi — não há build via linha de comando.

Passo a passo

  1. Abra o .dproj (ou .dpk) correspondente à sua versão do Delphi (veja a tabela abaixo).
  2. No Project Manager, clique com o botão direito no pacote → Build.
  3. Em seguida, clique com o botão direito novamente → Install.

Após a instalação, o item "TDataSet visualizer..." passa a aparecer no menu suspenso de visualizadores do depurador (Watch List / tooltip de avaliação).

Pacotes por versão do Delphi

Versão do Delphi Pacote
Delphi 11 Alexandria, 12 Athens e mais recentes Packages\D11Plus\dxIDEPackage.TDataSetVisualizer.dproj
Delphi 10.1 Berlin Packages\D101Berlin\dxIDEPackage.TDataSetVisualizer.D240.dproj
Delphi 10 Seattle Packages\D10Seattle\dxIDEPackage.TDataSetVisualizer.D230.dproj
Delphi XE7 Packages\XE7\dxIDEPackage.TDataSetVisualizer.D210.dpk

O pacote D11Plus usa {$LIBSUFFIX AUTO}, então um único build atende todas as versões Delphi 11+.

Temas da IDE

A partir do Delphi 10.2 Tokyo (com IDE theming habilitado), o visualizador acompanha o tema da IDE (claro/escuro). Em IDEs mais antigas, ou com o tema desabilitado, ele mantém a paleta clara clássica — com listras zebradas, destaque de células nulas e cores de estado de filtro.

Defines condicionais do pacote

Define Significado
DSV_IDE_THEMING Definido automaticamente no Delphi 10.2+; habilita as chamadas a IOTAIDEThemingServices.
SUPPORT_FIREDAC_DATASETS Inclui FireDAC.Stan.StorageBin para registrar o formato de armazenamento binário do FireDAC.
SUPPORT_ADO_DATASETS Inclui as units ADO (experimental — o formato persistido do ADO não é lido pelo carregador CDS).
SUPPORT_DATASNAP_DATASETS Inclui suporte a DataSnap.

2. Como usar

  1. Com o pacote do visualizador instalado, coloque um breakpoint em um ponto onde o dataset que você quer inspecionar esteja aberto e populado.
  2. Execute a aplicação até parar no breakpoint.
  3. Inspecione a expressão do dataset de uma destas formas:
    • Adicione-a à Watch List, ou
    • Passe o mouse sobre a variável para abrir o tooltip de avaliação.
  4. No menu suspenso do visualizador de depuração, escolha "TDataSet visualizer...".
  5. A janela do visualizador abre acoplada à IDE, já exibindo os dados em um grid, posicionado no registro atual do dataset depurado.

Como funciona internamente

Ao acionar o visualizador sobre uma expressão TDataSet, o depurador chama {Expressão}.SaveToFile() para gravar o dataset em um arquivo temporário. Em seguida, o visualizador cria um dataset local (um TClientDataSet por padrão, ou TFDMemTable para FireDAC) e faz LoadFromFile() para carregar a cópia (snapshot). O arquivo temporário é apagado logo depois.

Importante: como os dados são copiados, evite usar o visualizador em datasets muito grandes ou que contenham informações sensíveis/privilegiadas.

3. Ferramentas (barra de tarefas e abas)

A janela tem três abas:

  • DataSet Visualizer — o grid de dados.
  • FieldDefs — as definições dos campos do dataset.
  • SQL — o texto do comando que originou o dataset, quando disponível (a aba só aparece se houver SQL).

Uma única barra de ferramentas no topo se adapta à aba ativa:

Botão DataSet Visualizer FieldDefs SQL
Refresh (F5) recarrega o dataset recarrega o dataset —
Auto-fit ajusta as colunas do grid de dados ajusta as colunas do FieldDefs —
Find (Ctrl+F) barra de busca sobre o grid de dados barra de filtro sobre o grid FieldDefs —
Filter alterna a caixa de filtro do dataset oculto oculto
Go to (Ctrl+G) salta para um número de registro oculto oculto
Record (Tab) alterna entre grid ↔ visão de registro único oculto oculto
Highlight Nulls tinge as células nulas oculto oculto
Export dados → CSV/JSON/XML/Markdown FieldDefs → CSV/JSON/XML/Markdown texto do comando → TXT

Um traço (—) indica que o botão está desabilitado naquela aba. Ações exclusivas do grid (Filter, Go to, Record, Highlight Nulls) ficam ocultas fora do grid de dados; na aba SQL toda a barra fica desabilitada, exceto Export.

4. Recursos

Visão de registro (Record view)

Mostra a linha atual como uma lista vertical Campo/Valor (um campo por linha), estilo DBeaver — útil para datasets muito largos. Alterne com o botão Record ou pressionando Tab no grid (Tab de novo, ou o botão, volta ao grid). O ícone do botão muda (grid ⇄ detalhe) para indicar o modo atual. Apenas colunas visíveis são listadas; NULLs aparecem com o marcador (null) e BLOBs binários são resumidos como (BLOB: n bytes).

Busca (Find)

Busca dentro do grid ativo. No grid de dados há dois modos:

  • Fields — casa nomes/rótulos de colunas (o título da coluna localizada aparece em negrito).
  • Values — casa o conteúdo das células.

Navegue entre as ocorrências com os botões ▲/▼ ou com Enter / Shift+Enter. Na aba FieldDefs, o mesmo botão abre uma barra flutuante que filtra a lista de campos por nome.

Filtro (Filter)

Alterna a caixa Search by Filter: digite uma expressão de filtro e pressione Enter para aplicá-la (ex.: ESTAB = 1). Desligar o botão desativa o filtro, mas mantém o texto para a próxima vez. Se o dataset depurado já chegar filtrado, o botão começa pressionado e a expressão é reaplicada para que o grid reflita as mesmas linhas.

Marcador de registro atual

A linha em que o dataset depurado está posicionado é tingida de dourado, e o grid abre rolado até ela. O marcador é casado por identidade de registro, então continua acompanhando aquele registro mesmo após reordenar o grid clicando nos cabeçalhos de coluna. (Se o dataset depurado estiver filtrado, o mapeamento pode ser aproximado, pois o snapshot salvo inclui todos os registros.)

Distinção entre NULL e string vazia

Células nulas são desenhadas com um marcador (null) em itálico suave, para diferenciar um NULL real de uma string vazia. O marcador (null) é apenas visual — nunca é incluído ao copiar ou exportar. O botão Highlight Null Cells adicionalmente tinge o fundo da célula inteira.

Seleção múltipla e cópia

O grid permite seleção múltipla (Ctrl+clique / Shift+clique). Clique com o botão direito no grid para copiar:

  • Copy cell (Ctrl+C) — o valor da célula em foco.
  • Copy row(s) — submenu que copia as linhas selecionadas (ou a atual) em um de quatro formatos: CSV, CSV (com cabeçalhos), Markdown ou Markdown (com cabeçalhos). Valores CSV são escapados conforme RFC 4180 e usam o separador de lista do sistema, colando corretamente no Excel; Markdown é ideal para colar em chats/issues ou alimentar uma IA.
  • Copy column — todos os valores da coluna selecionada.

Em todos os formatos, valores NULL são copiados como células vazias.

Outras ações do menu de contexto (botão direito)

  • Filter by this value — filtra o grid para as linhas em que a coluna clicada é igual ao valor da célula clicada, exibindo a caixa de filtro com a expressão gerada. Desligue o botão Filter (ou pressione Esc no grid) para limpar.
  • Column statistics... — abre um resumo da coluna clicada: total e contagem de nulos, mais estatísticas conforme o tipo — mín/máx/média para números, mais antigo/mais recente para datas, contagem de true/false para booleanos, e o valor mais frequente para texto/inteiros.
  • Show/hide columns — o submenu Columns lista cada campo com um checkmark para alternar visibilidade, com atalhos Show All / Hide All; Hide this column oculta a coluna clicada e Hide empty columns remove toda coluna sem dados em nenhuma linha.

Exportação

O nome do arquivo é baseado na expressão do dataset (exportações de FieldDefs recebem o sufixo _FieldDefs). O CSV usa o separador de lista do sistema com aspas RFC 4180; o Markdown gera uma tabela no estilo GitHub; o JSON renderiza números, booleanos e datas com os tipos apropriados. Na aba SQL, Export salva o texto do comando como arquivo .txt.

Salvar e carregar layouts de coluna

O visualizador é recriado do zero a cada abertura, então ajustes de coluna (quais ficam visíveis, larguras) não são persistidos automaticamente. Em vez disso, você salva e carrega sob demanda. Clique com o botão direito no grid e use o submenu Column Layout:

  • Save Layout As... — salva o layout atual (campos visíveis e larguras) em um arquivo .dsvlayout que você nomeia.
  • Load Layout... — aplica um arquivo .dsvlayout salvo anteriormente ao dataset atual.
  • Recent layouts — os últimos 10 arquivos salvos/carregados ficam listados para reuso com um clique.

O layout é casado ao dataset por nome de campo, então carregar um layout funciona mesmo quando a ordem dos campos difere entre sessões; campos ausentes no layout salvo mantêm seu estado atual. A lista de recentes fica no registro do Windows em HKEY_CURRENT_USER\Software\dxIDEPackage TDataSetVisualizer\RecentLayouts.

Nota: larguras de coluna são salvas em pixels absolutos, então carregar um layout em um monitor com DPI diferente daquele em que foi salvo pode escalar levemente as larguras.

Pré-visualização de BLOB/Memo

Ao selecionar uma célula de campo memo ou de imagem (BLOB), um painel de pré-visualização exibe o texto ou a imagem decodificada (são detectados JPEG, PNG, BMP e GIF). A atualização do preview é debounced, evitando travamentos ao rolar rapidamente entre linhas.

5. Atalhos de teclado

Atalho Ação
F5 Recarrega o dataset (Refresh)
Ctrl+F Abre a barra de busca (Find) no grid ativo
Ctrl+G Salta para um número de registro (Go to)
Tab Alterna entre grid e visão de registro único
Ctrl+C Copia a célula em foco
Enter / Shift+Enter Próxima / anterior ocorrência na busca
Esc Limpa o filtro ativo no grid

A IDE consome Ctrl+F, Ctrl+G e F5 antes de chegarem ao frame. O visualizador intercepta essas teclas no nível do message pump e as redireciona — mas apenas enquanto o foco está dentro do frame do visualizador.

6. Limitações e observações

  • Datasets grandes: acima de 10 MB no snapshot temporário, o visualizador avisa e pede confirmação antes de carregar, pois materializar e varrer um dataset muito grande pode congelar a IDE.

  • Dados sensíveis: como os dados são copiados para um arquivo temporário, evite usar o visualizador em datasets com informações privilegiadas.

  • FireDAC: o executável depurado precisa suportar .SaveToFile. Se ocorrer erro ao visualizar um dataset FireDAC:

    1. Inclua FireDAC.Stan.StorageBin em uma cláusula uses da sua aplicação.
    2. Garanta que haja uma chamada a .SaveToFile ligada ao executável, para o linker não remover o método.

    Quando o salvamento falha, o visualizador mostra exatamente essa orientação na mensagem de erro.

  • ADO (dbGo): não é oficialmente suportado. Expressões ADO recaem no carregador de ClientDataSet, que não consegue ler o formato persistido do ADO. Use FireDAC ou ClientDataSet para resultados confiáveis.

7. Projeto de demonstração

Um projeto de exemplo fica em Demo\DataSetDemonstration.dpr. Ele constrói um TClientDataSet (cdsData) aleatório em memória que você pode inspecionar com o visualizador.

  1. Com o pacote do visualizador instalado, abra e execute Demo\DataSetDemonstration.dpr pela IDE.
  2. Defina o número de Records e Columns; opcionalmente marque Add Memo Field, Add Image Field e/ou Add random NULLs, e clique em Generate para (re)construir o dataset. "Add random NULLs" espalha valores NULL pelas linhas, para você ver o display (null) e o destaque de células nulas.
  3. Opcionalmente, digite uma expressão de filtro na caixa Filter e marque Filtered para aplicá-la ao cdsData (o filtro é reaplicado após cada Generate). Isso exercita o comportamento do visualizador quando o dataset inspecionado já chega filtrado. Os nomes dos campos são aleatórios a cada geração, então escreva a expressão contra os nomes exibidos no momento.
  4. Para testar o visualizador de depuração, coloque um breakpoint na linha cdsData.First; do método btnRunClick (unit uMain), e clique em Run!.
  5. Quando o breakpoint disparar, inspecione cdsData — por exemplo, adicione-o à Watch List (ou passe o mouse) e escolha TDataSet visualizer... no menu de visualizadores — para abrir o visualizador sobre o dataset ao vivo.

8. Contato

Sugestões e relatos de bugs são bem-vindos:

🐛 Abra uma issue no GitHub