Diagnóstico de associaçã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 posteriores e no Visual Studio 2022 para ajudar a encontrar essas falhas de associação de dados irritantes enquanto você depura seu aplicativo. 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 incorreto, como a associação a um booliano quando uma enumeração é necessária: Visibility="{Binding IsVisible}"

Como essas associações são computadas em tempo de execução usando reflection, o editor XAML nem sempre é capaz de detectá-las, e sua compilação ainda será bem-sucedida. A falha ocorre somente em tempo de execução.

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

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

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 estar a centenas de linhas acima do topo da janela, e o texto não informa exatamente qual associação teve a falha, portanto, você precisa refletir sobre isso e investigar.

Agora, com a janela de ferramentas de 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 em XAML. Além disso, há muitos recursos úteis para investigar as falhas pesquisando, classificando e até mesmo abrindo o editor de XAML com o 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>Windows>Falhas de Associação XAML.

Ou, então, selecione o botão Falhas de associação 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 como cinza sem um número ao lado dele. 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 falha, o status do ícone mostra o status imediato.

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 botões da seguinte maneira:
  • Limpar 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 aparece. Quando você inicia uma nova sessão de depuração, a lista é limpada 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.
  • Desmarque 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 falha muitas vezes em sequência quando está 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 mostra 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 indica se a linha representa um erro ou aviso.
  • Um ícone que mostra colchetes angulares <> se houver suporte para navegação até o {Binding} com falha no XAML. Veja a seção Plataformas com suporte.
  • contexto de dados: esse é o nome do tipo do objeto de origem da associação
    • Veja Binding.Source
  • Caminho de Associação: esse é o caminho da propriedade para a associação
    • Veja Binding.Path
  • Destino: essa opção é o tipo e o nome da propriedade em que o valor da associação é definido.
    • Veja BindingExpressionBase.Target e BindingExpressionBase.TargetProperty
  • tipo de destino: esse é o tipo esperado da propriedade de destino da associação.
    • Veja BindingExpressionBase.TargetProperty
  • Descrição: esta coluna contém mais informações sobre o que exatamente falhou na associação.
  • Arquivo, Linha, e Projeto: se conhecido, este é o local em XAML onde a vinculação é definida.
• Clicar com o botão direito do mouse em uma linha ou várias linhas selecionadas mostra um menu de contexto, com opções padrão para mostrar/ocultar colunas ou agrupá-las. Outras opções são as seguintes:
  • Copiar todo o texto de uma linha ou apenas uma coluna para a área de transferência.
  • O recurso Copiar Erro Original copia o texto que apareceu na janela de saída de depuração.
  • A opção "Ver Origem" direciona para a fonte de vinculação em XAML de uma linha selecionada.
  • Redefinir Colunas desfaz 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 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 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 para baixo ou para cima por meio da lista de falhas de associação. Isso é como outros painéis no Visual Studio que mostram uma lista.

Plataformas com suporte

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

Navegar até a origem só funciona para associações definidas em arquivos de origem XAML, não se forem criadas por meio do 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 com a linha realçada na captura de tela a seguir:

Se o valor da configuração estiver Desativado ou Crítico, 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

• Recarga Dinâmica de XAML