Compartilhar via


Diagnóstico de vinculação de dados XAML

Os desenvolvedores que trabalham em projetos XAML geralmente precisam detectar e resolver falhas de associação de dados XAML em seus aplicativos. Agora há ferramentas no Visual Studio 2019 versão 16.8 ou posterior e no Visual Studio 2022 para ajudar a encontrar essas falhas irritantes de associação de dados enquanto você depura seu aplicativo. Os exemplos de falhas comuns de associação são os seguintes:

  • Associação a um nome de propriedade que não existe: {Binding Wrong.Name}
  • Associação a um valor do tipo errado, como a associação a um booliano quando uma enumeração é necessária: Visibility="{Binding IsVisible}"

Como essas associações são computadas em runtime usando reflexão, o editor XAML nem sempre é capaz de detectá-las e seu build ainda assim terá êxito. A falha ocorre somente no runtime.

A associação de dados XAML é explicada nestes artigos:

As falhas de associação sempre foram gravadas na janela de saída de depuração no Visual Studio. Mas é fácil perder as falhas de associação dentro da saída de depuração, pois ela contém outras informações de depuração que rolam as falhas de associação para fora da exibição. Aqui está um exemplo de uma falha de associação do WPF na janela de saída de depuração:

Screenshot of the output window containing a binding failure.

A falha de associação pode ter centenas de linhas fora da parte superior da janela e o texto não informa exatamente qual associação teve a falha; portanto, você precisa pensar sobre ela e pesquisar.

Agora, com a janela da ferramenta Falhas de Associação XAML, você pode ver claramente quais associações falharam, juntamente com dados relevantes para cada falha, como o local do arquivo dentro do XAML. Além disso, há muitos recursos úteis para investigar as falhas pesquisando, classificando e até mesmo abrindo o editor XAML com foco definido na associação com falha.

Screenshot of the XAML Binding Failures tool window.

Clicar duas vezes nessas linhas abre o XAML de origem para a associação, conforme mostrado na imagem a seguir:

Screenshot of example bindings in the XAML editor.

Janela da ferramenta Falhas de Associação XAML

A janela da ferramenta Falhas de Associação XAML está disponível durante a depuração. Para abri-la, acesse Depurar>Falhas de Associação XAML do>Windows.

Screenshot of the XAML Binding Failures option in the Debug menu.

Ou selecione o botão Associar falhas na barra de ferramentas do aplicativo. O número ao lado do ícone mostra quantas falhas de associação são mostradas na janela de ferramentas.

Screenshot of the in-app toolbar showing the binding failures button.

Quando não há falhas de associação na janela de ferramentas, o ícone é exibido em cinza sem um número ao lado. Isso é útil durante a execução do aplicativo. Se você vir o ícone ficar vermelho com um número, clique nele para ir rapidamente para a janela de ferramentas para ver quais falhas de associação ocorreram. Não é necessário ficar de olho nas janelas de ferramentas do Visual Studio. Quando uma associação falhar, o ícone informará imediatamente.

Screenshot of the in-app toolbar showing the binding failures button with no failures.

Um ícone semelhante também aparece na janela de ferramentas Árvore visual dinâmica.

Screenshot of the binding failures button within the Live Visual Tree tool window.

Veja a seguir uma descrição de todos os componentes da janela da ferramenta Falhas de Associação XAML.

Screenshot of XAML Binding Failures tool window.

  • A barra de ferramentas na parte superior contém os seguintes botões:
    • Desmarcar a lista de falhas: isso será útil se você estiver prestes a mostrar uma nova página em seu aplicativo e quiser ver se alguma falha de associação será exibida. Quando você inicia uma nova sessão de depuração, a lista é limpa automaticamente.
    • Excluir linhas selecionadas: se uma falha tiver sido corrigida ou não for relevante, você poderá excluí-la da lista. As linhas excluídas aparecerão novamente se a associação falhar novamente.
    • Limpar todos os filtros: se houver filtros na lista, como pesquisar texto, esse botão os limpará e mostrará a lista completa.
    • Combinar Duplicatas: geralmente, a mesma associação falhará muitas vezes em uma linha quando estiver dentro de um modelo de item. Quando o botão Combinar Duplicatas é selecionado (com uma estrutura de tópicos ao seu redor), todas as falhas duplicadas são mostradas como uma única linha. A coluna Contagem mostrará quantas vezes a falha ocorreu.
  • A caixa Pesquisar Falhas de Associação no canto superior permite filtrar as falhas e visualizar somente as que contêm algum texto específico.
  • As colunas da tabela, em ordem, mostram:
    • Um ícone que mostra se a linha é para um erro ou aviso.
    • Um ícone que mostra colchetes angulares <> se houver suporte para navegar até o {Binding} com falha no XAML. Consulte a seção Plataformas Com Suporte.
    • Contexto de Dados: esse é o nome do tipo do objeto de origem da associação
    • Caminho de Associação: esse é o caminho da propriedade para a associação
    • Destino: esse é o tipo e o nome da propriedade onde o valor da associação será definido.
    • Tipo de destino: esse é o tipo esperado da propriedade de destino da associação.
    • Descrição: esta coluna contém mais informações sobre o que exatamente falhou para a associação.
    • Arquivo, Linha e Projeto: se conhecido, esse é o local em XAML no qual a associação é definida.
  • Clicar com o botão direito do mouse em uma linha ou várias linhas selecionadas mostrará um menu de contexto, com opções padrão para mostrar/ocultar colunas ou agrupá-las. As outras opções são as seguintes:
    • Copiar todo o texto de uma linha ou apenas uma única coluna para a área de transferência.
    • Copiar Erro Original copiará o texto que apareceu na janela de saída de depuração.
    • Exibir Fonte irá para a origem da associação em XAML para uma linha selecionada.
    • Redefinir Colunas desfará todas as alterações na visibilidade e classificação da coluna, fazendo com que você volte rapidamente ao que foi mostrado originalmente.

Para classificar a lista, clique em qualquer cabeçalho de coluna. Para classificar novamente por uma coluna adicional, mantenha pressionada a tecla Shift e clique em outro cabeçalho de coluna. Para selecionar quais colunas são exibidas e ocultadas, escolha Mostrar Colunas no menu de atalho. Para alterar a ordem na qual as colunas são exibidas, arraste qualquer cabeçalho de coluna para a esquerda ou para a direita.

Depois de clicar duas vezes em uma linha ou pressionar Enter para navegar até a origem, você poderá pressionar F8 ou Shift+F8 para mover a seleção para baixo ou para cima na lista de falhas de associação. Isso é similar a outros painéis do Visual Studio que mostram uma lista.

Plataformas com Suporte

A maioria das plataformas XAML contam com suporte se as falhas de associação forem gravadas para depurar a saída. Algumas plataformas fornecem informações adicionais de origem para o depurador que permitem navegar até a origem.

Plataforma Com suporte Navegar até a origem com suporte
WPF .NET Framework Sim Não
WPF .NET 5.0 RC2+ Sim Sim
UWP Sim Não
WinUI3 desktop Sim Não
MAUI (Interface do usuário de aplicativo multiplataforma) Sim Não
Xamarin 4.5.0.266-pre3+ Sim Sim
Xamarin anterior à 4.5.0.266-pre3 Não Não

A opção de Recarga Dinâmica de XAML deve estar habilitada no Visual Studio para navegar até a origem para funcionar. Essa opção está na Caixa de diálogo Depuração>das Opções>das Ferramentas:

Screenshot of the XAML Hot Reload options dialog.

Navegar até a origem só funciona para associações definidas em arquivos de origem XAML, não se elas forem criadas por meio de código. Você pode ver claramente quais linhas dão suporte à navegação até a origem. Se não houver nenhum ícone de colchete angular na segunda coluna, não haverá suporte para navegar até a origem, como no caso da linha realçada na captura de tela a seguir:

Screenshot showing a XAML binding failure without a source location.

Para o WPF no .NET Framework, as falhas de associação de dados devem ser mostradas na saída de depuração para o painel Falhas de Associação XAML para detectá-las e mostrá-las. A opção para isso está na caixa de diálogoFerramentas>Opções>Depuração>Janela de Saída>Configurações de Rastreamento WPF. Se a configuração estiver Desativada ou Crítica, os erros de associação de dados não serão gravados na saída de depuração e não poderão ser detectados. Com o WPF no .NET 5, no .NET 6 e posterior, a configuração de saída da associação de dados não afeta a lista de falhas.

Screenshot of WPF output options.