Visão geral de vinculação de dados

Como mencionado anteriormente e indicado pela seta na figura acima, o fluxo de dados de uma associação pode ir do alvo da associação para a fonte da associação (por exemplo, o valor da fonte modifica quando o usuário edita o valor de um TextBox) e/ou da fonte da associação para o alvo da associação (por exemplo, o conteúdo de sua TextBox é atualizado com a mudança na fonte da associação) se a fonte da associação fornece as notificações adequadas.

Você pode querer que sua aplicação permita usuários modificar os dados e propagá-los de volta para o objeto fonte. Ou você não quer permitir que usuários atualizem a fonte de dados. Você pode controlar isto ao definir a propriedade Mode do seu objeto Binding. A seguinte figura ilustra os diferentes tipos de fluxo de dados:

• Associação OneWay faz com que as mudanças na propriedade fonte sejam automaticamente atualizadas na propriedade alvo, porém mudanças na propriedade alvo não são propagadas de volta para a propriedade fonte. Este tipo de associação é adequado se o controle sendo associado é implicitamente somente leitura. Por exemplo, você pode associar uma fonte como um mostrador de cotação de ações ou talvez sua propriedade alvo não tenha nenhuma interface de controle disponível para realizar mudanças, tais como uma cor de fundo de uma tabela. Não há necessidade de monitorar as mudanças da propriedade alvo, usando o modo de associação OneWay evita o overhead do modo de associação TwoWay.

• A associação TwoWay faz com que mudanças em tanto a propriedade fonte quanto a propriedade alvo sejam automaticamente atualizadas na outra. Este tipo de associação é apropriado para formulários editáveis ou outros cenários UI totalmente interativos. O padrão da maioria das propriedades é associação OneWay, mas algumas propriedades de dependência (tipicamente propriedades de controles editáveis pelo usuário tais como a propriedade Text do TextBox e a propriedade IsCheckeddo CheckBox) tem como padrão a associação TwoWay. Uma maneira de determinar programaticamente se uma propriedade de dependência é associada em direção única ou bidirecionalmente por padrão é definir o meta-dado da propriedade usando GetMetadata e especificando o valor booleano da propriedade BindsTwoWayByDefault.

• OneWayToSource é o inverso da associação OneWay; só atualiza a propriedade fonte quando a propriedade alvo é modificada. Um cenário exemplo é se você só precisa reavaliar o valor da fonte de um UI.

• Não é ilustrado na figura a associação OneTime, que faz com que a propriedade fonte inicialize a propriedade alvo, mas mudanças subsequentes não são propagadas. Isso significa que se o contexto de dados passa por uma alteração ou o objeto em que as alterações de contexto de dados, em seguida, a alteração não será refletida na propriedade de destino. Este tipo de associação é apropriado se você está usando dados onde tanto um estado atual momentâneo é apropriado para o usuário ou os dados são realmente estáticos. Este tipo de associação também é útil se você quer inicializar sua propriedade alvo com alguns valores da propriedade fonte e o contexto de dados não é conhecido de antemão. Isto é essencialmente uma forma mais simples da associação OneWay que fornece uma performance melhor em casos onde o valor da fonte não é modificado.

Note que para detectar mudanças (aplicáveis a associações OneWay e TwoWay), a fonte deve implementar uma propriedade de mecanismo de notificação de mudança adequado tal como o INotifyPropertyChanged. Consulte Como: implementar notificação de alteração de propriedade para um exemplo de uma implementação INotifyPropertyChanged.

A página da propriedade Mode fornece mais informações sobre modos de associação de dados e um exemplo de como especificar a direção da associação.

Associações que são TwoWay ou OneWayToSource escutam por mudanças na propriedade alvo e propaga-las de volta para a fonte. Isto é conhecido como atualização da fonte. Por exemplo, você pode editar o texto de uma CaixaDeTexto para modificar o valor da fonte subjacente. Como descrito na seção anterior, a direção do fluxo de dados é determinado pelo valor da propriedade Mode da associação.

Entretanto, o valor da fonte é atualizado enquanto você está editando o texto ou depois de você terminar o texto e você aponta seu mouse fora da CaixaTexto? A propriedade UpdateSourceTrigger da associação determina qual gatilho atualiza a fonte. Os pontos nas setas para direita na seguinte figura ilustra o papel da propriedadeUpdateSourceTrigger:

Se o valor UpdateSourceTrigger é PropertyChanged, então o valor apontado pela seta para direita do TwoWay ou as associações OneWayToSource são atualizadas assim que a propriedade alvo é modificada. Entretanto, se o valor UpdateSourceTrigger é LostFocus, então o valor somente é atualizado com o novo valor quando o alvo perde o foco.

Similar a propriedade Mode, diferentes propriedades de dependência possuem valores padrão diferentes UpdateSourceTrigger. O valor da maioria das propriedades de dependência é PropertyChanged, enquanto a propriedade Text tem o valor padrão de LostFocus. Isto significa que a fonte é usualmente atualizada sempre que a propriedade alvo é modificada, o que é bom para CheckBox e outros controles simples. Entretanto, para textos campos, atualizar depois de cada teclada pode diminuir a performance e impedir o usuário da oportunidade de voltar e corrigir erros de digitação antes de enviar os novos valores. É por isso que a propriedade Text tem valor padrão LostFocus ao invés de PropertyChanged.

Veja a página da propriedade UpdateSourceTrigger para informação sobre como encontrar o valor padrão de UpdateSourceTrigger de uma propriedade de dependência.

A seguinte tabela fornece um cenário exemplo para cada valor UpdateSourceTrigger usando o TextBox como um exemplo:

Para um exemplo, consulte Como: controlar quando o texto de TextBox atualiza a fonte.

Perceba que no exemplo anterior, a fonte da associação é especificado definindo a propriedade DataContext no elemento DockPanel. O Button então herda o valor DataContext do DockPanel, que é o elemento pai. Para reiterar, o objeto fonte da associação é um dos quatro componentes necessários de uma associação. Portanto, sem o objeto fonte sendo especificando, a associação não fará nada.

Existem várias maneiras de especificar o objeto fonte da associação. Usar a propriedade DataContext no elemento pai é útil quando você está associando propriedades de elementos múltiplos à mesma fonte. Entretanto, as vezes pode ser mais apropriado especificar a fonte da associação em declarações individuais de associação. No exemplo anterior, ao invés de usar a propriedade DataContext, você pode especificar a fonte da associação definindo a propriedade Source diretamente na declaração da associação do botão, como no seguinte exemplo:

<DockPanel.Resources>
  <c:MyData x:Key="myDataSource"/>
</DockPanel.Resources>
<Button Width="150" Height="30"
        Background="{Binding Source={StaticResource myDataSource},
                             Path=ColorName}">I am bound to be RED!</Button>

Ao invés de definir a propriedade DataContext em um elemento diretamente, herdando o valor DataContext de um ancestral (como o botão no primeiro exemplo), e explicitamente especificando a fonte da associação ao definir a propriedade Source no Binding (como o botão no último exemplo), você também pode usar a propriedade ElementName da propriedade RelativeSource para especificar a fonte da associação. A propriedade ElementName é útil quando você está associando a outros elementos em sua aplicação, como quando você está usando uma barra deslisante para ajustar a largura de um botão. A propriedade RelativeSourceé útil quando a associação é especificada em um ControlTemplate ou um Style. Para obter mais informações, consulte Como: Especificar a Fonte de Associação.

Se sua fonte da associação é um objeto, você pode usar a propriedade Path para especificar o valor a ser usado em sua associação. Se você está associando dados XML , você usa a propriedade XPath para especificar o valor. Em alguns casos, pode ser aplicável usar a propriedade Path mesmo quando seus dados são XML. Por exemplo, se você quer acessar a propriedade Nome de um XmlNode retornado (como um resultado de um pedido XPath), você deve usar a propriedade Path conjuntamente com a propriedade XPath.

Para mais informações sobre sintaxe e exemplos, consulte as páginas das propriedades Path e XPath.

Note que embora tenhamos enfatizado que Path para o valor a ser usado é um dos quatro componentes necessários para uma associação, nos cenários em que você quer associar um objeto inteiro, o valor a ser usado seria o mesmo que o objeto fonte da associação. Nesses casos, é aplicável não especificar um Path. Considere o exemplo a seguir:

<ListBox ItemsSource="{Binding}"
         IsSynchronizedWithCurrentItem="true"/>

O exemplo acima usa a sintaxe de associação vazia: {Binding}. Neste caso, o ListBox herda o Contexto de Dados de um elemento DockPanel pai (não mostrado nesse exemplo). Quando o caminho não é especificado, o padrão é associar ao objeto inteiro. Em outras palavras, neste exemplo, o caminho oi deixado de fora porque estamos associando a propriedade ItemsSource ao objeto inteiro. (Consulte a seção Associando a Coleções para uma discussão aprofundada.)

Ao invés de associar a uma coleção, este cenário também é útil quando você quer associar a um objeto inteiro ao invés de somente uma única propriedade de um objeto. Por exemplo, seu objeto fonte é do tipo string e você simplesmente quer associar a string. Outro cenário comum é quando você quer associar um elemento a um objeto com várias propriedades.

Note que você pode precisar aplicar uma lógica personalizada para que os dados tenham significado para a propriedade alvo associada. A lógica personalizada pode ser na forma de um conversor personalizado (se o conversor padrão de tipos não existir). Consulte Conversão de Dados para informações sobre conversores.

Antes de entrar em outras funcionalidades e usos de associação de dados, seria útil introduzir a classe BindingExpression. Como você viu nas seções anteriores, a classe Binding é a classe de alto nível para a declaração de uma associação; a classe Binding fornece várias propriedade que permitem você especificar as características de uma associação. Uma classe relacionada, BindingExpression, é o objeto subjacente que mantém a conexão entre a fonte e o alvo. Uma associação contém todas informações que podem ser compartilhadas através de várias expressões de associação. Uma BindingExpression é uma expressão de instância que não pode ser compartilhada e contém todas as informações de instância da Binding.

Por exemplo, considere o seguinte, onde myDataObject é uma instância da classe MyData , myBinding é o objeto Binding fonte, e a classe MyData é a classe definida que contém a propriedade string MyDataProperty. Este exemplo associa o conteúdo texto de um mytext, uma instância de TextBlock, ao MyDataProperty.

//make a new source
  MyData myDataObject = new MyData(DateTime.Now);      
  Binding myBinding = new Binding("MyDataProperty");
  myBinding.Source = myDataObject;
  myText.SetBinding(TextBlock.TextProperty, myBinding);

Você pode usar o mesmo objeto myBinding para criar outras associações. Por exemplo, você pode usar o objeto myBinding para associar o conteúdo texto a uma caixa de checar ao MyDataProperty. Naquele cenário, haverá duas instâncias de BindingExpression compartilhando o objeto myBinding.

Um objeto BindingExpression pode ser obtido por meio do valor de retorno da chamada de GetBindingExpression em um objeto associado a dados. Os seguintes tópicos demonstram alguns usos da classe BindingExpression:

• Como: obter o objeto de ligação a partir de uma propriedade de destino acoplado

• Como: controlar quando o texto de TextBox atualiza a fonte

Você pode enumerar sobre qualquer coleção que implemente a interface IEnumerable. Entretanto, para definir associações dinâmicas para que inserção e deleção na coleção atualizem a UI automaticamente, a coleção deve implementar a interface INotifyCollectionChanged. Esta interface expõe um evento que deve ser levantado sempre que a coleção subjacente é modificada.

WPF fornece a classe ObservableCollection<T>, que é uma implementação embutida de uma coleção de dados que expõe a interface INotifyCollectionChanged . Note que para suportar completamente a transferência de valores de dados de objetos fontes para objetos alvo, cada objeto em sua coleção que suporta propriedades associáveis deve também implementar a interface INotifyPropertyChanged. Para maiores informações, acesse Visão geral sobre associação de fontes.

Antes de implementar sua própria coleção, considere usar ObservableCollection<T> ou uma das classes de coleção existentes, como uma List<T>, Collection<T>, e BindingList<T>, entre muitas outras. Se você tem um cenário avançado e quer implementar sua própria coleção, considere usar IList, que fornece uma coleção de objetos não genéricos que podem ser acessados individualmente por um índice e portanto a melhor performance.

Uma vez que seu ItemsControl está associado a uma coleção de dados, você pode querer ordenar, filtrar ou agrupar os dados. Para fazê-lo, use visualização de coleções, que são classes que implementam a interface ICollectionView.

Esta seção contém as subseções a seguir.

• O Que são Visualização de Coleções?
• Como Criar uma Visualização
• Classificação
• Filtro
• Agrupamento
• Ponteiros do Item atual
• Cenário de Associação Master-Detail

O Que são Visualização de Coleções?

Como Criar uma Visualização

<Window.Resources>


...


<CollectionViewSource 
      Source="{Binding Source={x:Static Application.Current}, Path=AuctionItems}"   
      x:Key="listingDataView" />


...


</Window.Resources>

<ListBox Name="Master" Grid.Row="2" Grid.ColumnSpan="3" Margin="8"
    ItemsSource="{Binding Source={StaticResource listingDataView}}">


...


</ListBox>

Classificação

private void AddSorting(object sender, RoutedEventArgs args)
{
    // This sorts the items first by Category and within each Category,
    // by StartDate. Notice that because Category is an enumeration,
    // the order of the items is the same as in the enumeration declaration
    listingDataView.SortDescriptions.Add(
        new SortDescription("Category", ListSortDirection.Ascending));
    listingDataView.SortDescriptions.Add(
        new SortDescription("StartDate", ListSortDirection.Ascending));
}

Filtro

listingDataView.Filter += new FilterEventHandler(ShowOnlyBargainsFilter);

private void ShowOnlyBargainsFilter(object sender, FilterEventArgs e)
{
    AuctionItem product = e.Item as AuctionItem;
    if (product != null)
    {
        // Filter out products with price 25 or above
        if (product.CurrentPrice < 25)
        {
            e.Accepted = true;
        }
        else
        {
            e.Accepted = false;
        }
    }
}

Agrupamento

// This groups the items in the view by the property "Category"
PropertyGroupDescription groupDescription = new PropertyGroupDescription();
groupDescription.PropertyName = "Category";
listingDataView.GroupDescriptions.Add(groupDescription);

Ponteiros do Item atual

<Button Content="{Binding }" />
<Button Content="{Binding Path=/}" />
<Button Content="{Binding Path=/Description}" /> 

<Button Content="{Binding /Offices/}" />

Cenário de Associação Master-Detail

<ListBox Name="Master" Grid.Row="2" Grid.ColumnSpan="3" Margin="8"
    ItemsSource="{Binding Source={StaticResource listingDataView}}">


...


</ListBox>


...


<ContentControl Name="Detail" Grid.Row="3" Grid.ColumnSpan="3" 
        Content="{Binding Source={StaticResource listingDataView}}" 
        ContentTemplate="{StaticResource detailsProductListingTemplate}" 
        Margin="9,0,0,0"/>

O modelo de associação de dados de WPF permite você associar ValidationRules com o seu objeto Binding. Por exemplo, o exemplo a seguir vincula um TextBox para uma propriedade chamada StartPrice e adiciona um ExceptionValidationRule o objeto para o Binding.ValidationRules propriedade.

<TextBox Name="StartPriceEntryForm" Grid.Row="2" Grid.Column="1"
    Style="{StaticResource textStyleTextBox}" Margin="8,5,0,5">
  <TextBox.Text>
    <Binding Path="StartPrice" UpdateSourceTrigger="PropertyChanged">
      <Binding.ValidationRules>
        <ExceptionValidationRule />
      </Binding.ValidationRules>
    </Binding>
  </TextBox.Text>
</TextBox>

A ValidationRule objeto verifica se o valor de uma propriedade é válido. WPFtem os seguintes dois tipos internos ValidationRule objetos:

• A ExceptionValidationRule verifica se há exceções geradas durante a atualização da propriedade de origem de ligação. No exemplo anterior, StartPrice é do tipo número inteiro. Quando o usuário imputa um valor que não pode ser convertido para inteiro, uma exceção é gerada, fazendo a associação ser marcada como inválida. Uma sintaxe alternativa a configuração do ExceptionValidationRule explicitamente é definir o ValidatesOnExceptions propriedade para true em seu Binding ou MultiBinding objeto.

• A DataErrorValidationRule objeto verifica erros que são gerados por objetos que implementam o IDataErrorInfo interface. Para obter um exemplo de usar esta regra de validação, consulte DataErrorValidationRule. Uma sintaxe alternativa a configuração do DataErrorValidationRule explicitamente é definir o ValidatesOnDataErrors propriedade para true em seu Binding ou MultiBinding objeto.

Você também pode criar sua própria regra de validação derivando da classe ValidationRule e implementando o método Validate. O seguinte exemplo mostra a regra usada pelo Add Product Listing "Start Date" TextBox da seção O Que é Associação de Dados?:

class FutureDateRule : ValidationRule
{
    public override ValidationResult Validate(object value, CultureInfo cultureInfo)
    {
        DateTime date;
        try
        {
            date = DateTime.Parse(value.ToString());
        }
        catch (FormatException)
        {
            return new ValidationResult(false, "Value is not a valid date.");
        }
        if (DateTime.Now.Date > date)
        {
            return new ValidationResult(false, "Please enter a date in the future.");
        }
        else
        {
            return ValidationResult.ValidResult;
        }
    }
}

O StartDateEntryForm TextBox usa este FutureDateRule, como mostrado no seguinte exemplo:

<TextBox Name="StartDateEntryForm" Grid.Row="3" Grid.Column="1" 
    Validation.ErrorTemplate="{StaticResource validationTemplate}" 
    Style="{StaticResource textStyleTextBox}" Margin="8,5,0,5">
    <TextBox.Text>
        <Binding Path="StartDate" UpdateSourceTrigger="PropertyChanged" 
            Converter="{StaticResource dateConverter}" >
            <Binding.ValidationRules>
                <src:FutureDateRule />
            </Binding.ValidationRules>
        </Binding>
    </TextBox.Text>
</TextBox>

Note que porque o valor UpdateSourceTrigger é PropertyChanged, o sistema de associação atualiza o valor da fonte em cada tecla pressionada, o que significa que também verifica cada regra na coleção ValidationRules em cada tecla pressionada. Discutiremos isto mais tarde na seção Processo de Validação.

Se um usuário entra com um valor inválido, você pode querer fornecer algum feedback sobre o erro na aplicação UI. Uma maneira de fornecer tal feedback é definir a propriedade Validation.ErrorTemplate anexa para um ControlTemplate personalizado. Como visto na seção anterior, o StartDateEntryFormTextBox usa um ErrorTemplate chamado validationTemplate. O seguinte exemplo mostra a definição do validationTemplate:

<ControlTemplate x:Key="validationTemplate">
  <DockPanel>
    <TextBlock Foreground="Red" FontSize="20">!</TextBlock>
    <AdornedElementPlaceholder/>
  </DockPanel>
</ControlTemplate>

O elemento AdornedElementPlaceholder especifica onde o controle sendo adornado deve ser colocado.

Adicionalmente, você também pode usar um ToolTip para exibir a mensagem de erro. Ambos os StartDateEntryForm e o StartPriceEntryFormTextBoxes usam o estilo textStyleTextBox, que cria um ToolTip que exibe a mensagem de erro. O seguinte exemplo mostra a definição de textStyleTextBox. O anexado a propriedadeValidation.HasError é true quando uma ou mais das ligações nas propriedades do elemento acoplado estão em erro. 

<Style x:Key="textStyleTextBox" TargetType="TextBox">
  <Setter Property="Foreground" Value="#333333" />
  <Setter Property="MaxLength" Value="40" />
  <Setter Property="Width" Value="392" />
  <Style.Triggers>
    <Trigger Property="Validation.HasError" Value="true">
      <Setter Property="ToolTip"
        Value="{Binding RelativeSource={RelativeSource Self},
                        Path=(Validation.Errors)[0].ErrorContent}"/>
    </Trigger>
  </Style.Triggers>
</Style>

Com o ErrorTemplate personalizado e o ToolTip, e StartDateEntryForm TextBox parece com o seguinte quando há um erro de validação:

Se seu Binding possui regras de validação associadas mas você não especificou um ErrorTemplate no controle associado, um ErrorTemplate padrão será usado para notificar usuários quando há erro de validação. O ErrorTemplate padrão é um padrão de controle que define uma borda vermelha em uma camada adornada. Com o ErrorTemplate padrão e o ToolTip, o UI do StartPriceEntryForm TextBox parece com o seguinte quando há um erro de validação:

Para um exemplo de como fornecer a lógica para validar todos os controles em uma caixa de diálogo, consulte a seção Caixas de Diálogo Personalizadas em Visão geral de caixas de diálogo.

Normalmente, a validação ocorre quando o valor de um destino é transferido para a propriedade de origem da ligação. Isso ocorre na TwoWay e OneWayToSource ligações. Para reiterar, o que causa uma atualização da fonte depende do valor da propriedade UpdateSourceTrigger, como descrito na seção O Que Causa Atualização de Fonte.

A seguir descreve o validação processo. Observe que, se um erro de validação ou outro tipo de erro ocorrer a qualquer momento durante esse processo, o processo é interrompido.

1. O mecanismo de ligação verifica se há qualquer personalizado ValidationRule objetos definidos cuja ValidationStep for definido como RawProposedValue para que Binding, caso em que ele chama o Validate método em cada ValidationRule até que um deles é executado em um erro ou passam por todas elas.

2. O mecanismo de ligação, em seguida, chama o conversor, se houver.

3. Se o conversor for bem-sucedida, o mecanismo de ligação verifica se há qualquer personalizado ValidationRule objetos definidos cuja ValidationStep for definido como ConvertedProposedValue para que Binding, caso em que ele chama o Validate método em cada ValidationRule que tem ValidationStep definido como ConvertedProposedValue até que um deles é executado em um erro ou passam por todas elas.

4. O mecanismo de ligação define a propriedade source.

5. O mecanismo de ligação verifica se há qualquer personalizado ValidationRule objetos definidos cuja ValidationStep for definido como UpdatedValue para que Binding, caso em que ele chama o Validate método em cada ValidationRule que tem ValidationStep definido como UpdatedValue até que um deles é executado em um erro ou passam por todas elas. Se um DataErrorValidationRule está associada uma ligação e seu ValidationStep é definida como padrão, UpdatedValue, o DataErrorValidationRule é verificado neste momento. Também é o ponto quando as vinculações que têm o ValidatesOnDataErrors definido como true são verificados.

6. O mecanismo de ligação verifica se há qualquer personalizado ValidationRule objetos definidos cuja ValidationStep for definido como CommittedValue para que Binding, caso em que ele chama o Validate método em cada ValidationRule que tem ValidationStep definido como CommittedValue até que um deles é executado em um erro ou passam por todas elas.

Se um ValidationRule não passa a qualquer momento durante todo esse processo, o mecanismo de ligação cria um ValidationError de objeto e adiciona-lo para o Validation.Errors coleção do elemento acoplado. Antes da ligação engine executa o ValidationRule objetos em qualquer etapa determinada, ele remove qualquer ValidationError que foi adicionado para o Validation.Errorsanexado a propriedade do elemento acoplado durante esta etapa.  Por exemplo, se um ValidationRule cujo ValidationStep for definido como UpdatedValue falha, na próxima vez que o processo de validação ocorre, o mecanismo de ligação remove que ValidationError imediatamente antes ele chama qualquer ValidationRule que tem ValidationStep definido como UpdatedValue.

Quando Validation.Errors não está vazio, o Validation.HasErroranexado a propriedade do elemento é definido como true.  Além disso, se o NotifyOnValidationError propriedade da Binding for definido como true, e em seguida, o mecanismo de ligação gera o Validation.Erroranexado evento no elemento. 

Observe também que uma transferência de valor válido em qualquer direção (de destino para fonte ou a origem para destino) limpa a Validation.Errorsanexado a propriedade. 

Se a ligação tem um ExceptionValidationRule associados a ele, ou a possuía a ValidatesOnExceptions propriedade estiver definida como true e uma exceção é acionada quando o mecanismo de ligação define a origem, o mecanismo de ligação verifica para ver se há um UpdateSourceExceptionFilter. Você tem a opção de usar o callback UpdateSourceExceptionFilter para fornecer um manipulador personalizado para lidar com exceções. Se um UpdateSourceExceptionFilter não for especificado na Binding, o mecanismo de ligação cria um ValidationError com a exceção e o adiciona para o Validation.Errors coleção do elemento acoplado.