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:

• Para WPF: visão geral da associação de dados - WPF .NET
• Para UWP: visão geral da associação de dados - aplicativos UWP
• Para Xamarin.Forms: associação de dados Xamarin.Forms - Xamarin

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:

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.

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

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.

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.

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.

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

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

• 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
    • Consulte Binding.Source
  • Caminho de Associação: esse é o caminho da propriedade para a associação
    • Consulte Binding.Path
  • Destino: esse é o tipo e o nome da propriedade onde o valor da associação será definido.
    • Consulte BindingExpressionBase.Target e BindingExpressionBase.TargetProperty
  • Tipo de destino: esse é o tipo esperado da propriedade de destino da associação.
    • Consulte BindingExpressionBase.TargetProperty
  • 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.

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:

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:

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.

Conteúdo relacionado

• XAML Hot Reload