Diagnóstico de vinculação de dados XAML

Os desenvolvedores que trabalham em projetos XAML geralmente precisam detetar e resolver falhas de vinculaçã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 vinculação de dados enquanto você depura seu aplicativo. Exemplos de falhas comuns de vinculação são os seguintes:

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

Como essas associações são calculadas em tempo de execução usando reflexão, o editor XAML nem sempre é capaz de capturá-las, e sua compilação ainda terá êxito. A falha acontece apenas em tempo de execução.

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

• Para WPF: Visão geral da vinculação de dados - WPF .NET
• Para UWP: Visão geral da vinculação de dados - Aplicativos UWP
• Para Xamarin.Forms: Vinculação de Dados Xamarin.Forms - Xamarin
• Para .NET MAUI: Vinculação de Dados no .NET MAUI

Falhas de vinculação sempre foram gravadas na janela de saída de depuração no Visual Studio. Mas é fácil não perceber as falhas de vinculação na saída de depuração, pois ela contém outras informações que fazem com que as falhas de vinculação desapareçam da exibição. Aqui está um exemplo de uma falha de ligação do WPF na janela de resultados de depuração:

A falha de vinculação pode estar a centenas de linhas na parte superior da janela, e o texto não informa exatamente qual vinculação teve a falha, então você precisa pensar sobre isso e pesquisar.

Agora, com a janela da ferramenta Falhas de Vinculação XAML, você pode ver claramente quais associações falharam, juntamente com dados relevantes para cada falha, como o local do arquivo em XAML. Além disso, existem muitos recursos úteis para investigar as falhas, pesquisando, ordenando e até mesmo abrindo o editor XAML com o foco definido no vínculo 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 Vinculação XAML

A janela da ferramenta Falhas de Vinculação XAML está disponível durante a depuração. Para abri-lo, vá para Debug>Windows>XAML Binding Failures.

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

Quando não há falhas de vinculação na janela da ferramenta, o ícone aparece como cinza sem um número ao lado. Isso é útil ao executar seu aplicativo. Se você vir o ícone ficar vermelho com um número, clique nele para ir rapidamente para a janela da ferramenta para ver quais falhas de vinculação ocorreram. Não há necessidade de ficar de olho nas janelas de ferramentas do Visual Studio. Quando uma ligação falha, o estado do ícone mostra-te o estado imediato.

Um ícone semelhante também aparece na janela da ferramenta Live Visual Tree.

A seguir está uma descrição de todos os componentes da janela da ferramenta Falhas de Vinculação XAML.

• A barra de ferramentas na parte superior contém botões da seguinte maneira:
  • Limpar a lista de falhas: Isso é útil se você estiver prestes a mostrar uma nova página em seu aplicativo e quiser ver se alguma falha de vinculação aparece. Quando você inicia uma nova sessão de depuração, a lista é automaticamente limpa.
  • Excluir linhas selecionadas: Se uma falha tiver sido corrigida ou não for relevante, você poderá excluí-la da lista. As linhas eliminadas aparecem novamente se a ligação falhar novamente.
  • Limpar todos os filtros: Se houver filtros na lista, como a procura de texto, este botão limpa-os e mostra a lista completa.
  • Combinar Duplicados: Muitas vezes, a mesma ligação falha várias vezes seguidas quando está dentro de um modelo de item. Quando o botão Combinar Duplicatas é selecionado (com um contorno ao redor), os casos de falhas duplicadas são mostrados numa única linha. A coluna Contagem mostra quantas vezes ocorreu a falha.
• A caixa Falhas de Vinculação de Pesquisa no canto superior permite filtrar as falhas somente àquelas que contêm texto específico.
• As colunas da tabela, em ordem, mostram:
  • Um ícone que indica se a linha se refere a um erro ou a um aviso.
  • Um ícone que mostra colchetes angulares <> se a navegação para o {Binding} com falha em XAML for suportada. Consulte a seção Plataformas Suportadas.
  • Data Context: Este é o nome do tipo para o objeto de origem da ligação
    • Consulte Binding.Source
  • Caminho de vinculação: Este é o caminho da propriedade para a vinculação
    • Consulte Binding.Path
  • Alvo: Esta opção refere-se ao tipo e ao nome da propriedade onde o valor da associação é definido.
    • Consulte BindingExpressionBase.Target e BindingExpressionBase.TargetProperty
  • Tipo de destino: Este é o tipo esperado da propriedade de destino da ligação.
    • Consulte BindingExpressionBase.TargetProperty
  • Descrição: Esta coluna contém mais informações sobre o que exatamente falhou na ligação.
  • Ficheiro, Linha, e Projeto: Se conhecido, este é o local em XAML onde a associação é definida.
• Clicar com o botão direito numa linha ou várias linhas selecionadas mostra um menu contextual, com opções padrão para mostrar/esconder colunas ou agrupá-las. Outras opções são as seguintes:
  • Copie todo o texto de uma linha ou apenas de uma única coluna para a área de transferência.
  • Copiar Erro Original copia o texto que apareceu na janela de saída de depuração.
  • "View Source navega para a origem de ligação em XAML para uma linha selecionada."
  • Reiniciar Colunas anula todas as alterações à visibilidade e ordenação das colunas, devolvendo-te rapidamente ao que foi originalmente mostrado.

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

Depois de clicar duas vezes numa linha ou pressionar Enter para navegar para a fonte, pode pressionar F8 ou Shift+F8 para mover para baixo ou para cima na lista de falhas de associação. Isso é como outros painéis no Visual Studio que mostram uma lista.

Plataformas suportadas

A maioria das plataformas XAML é suportada se as falhas de vinculação forem gravadas na saída de depuração. Algumas plataformas fornecem informações de origem extra para o depurador que permite navegar até a fonte.

Navegar para o código-fonte 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 suportam a navegação até a fonte. Se não houver nenhum ícone de colchete angular na segunda coluna, não há suporte para navegar até a origem, como com a linha realçada na captura de tela a seguir:

Se o valor de definição for Desligado ou Crítico, erros de encadeamento de dados não são registados na saída de depuração e não podem ser detetados. Com o WPF no .NET 5, .NET 6 e posterior, a configuração de saída de vinculação de dados não afeta a lista de falhas.

Conteúdo relacionado

• Recarga a quente XAML