Preencher conjuntos de dados usando TableAdapters em aplicativos do .NET Framework

Um componente TableAdapter preenche um conjunto de dados com dados do banco de dados com base em uma ou mais consultas ou procedimentos armazenados especificados. Os TableAdapters também podem executar adições, atualizações e exclusões no banco de dados para persistir as alterações feitas no conjunto de dados. Você também pode emitir comandos globais que não estão relacionados a tabelas específicas.

Para obter informações detalhadas sobre as operações do TableAdapter, você pode pular diretamente para um destes tópicos:

Visão geral de TableAdapter

Os TableAdapters são componentes gerados pelo designer que se conectam a um banco de dados, executam consultas ou procedimentos armazenados e preenchem o DataTable com os dados retornados. Os TableAdapters também enviam dados atualizados de seu aplicativo de volta para o banco de dados. Você pode executar quantas consultas desejar em um TableAdapter, desde que retornem dados em conformidade com o esquema da tabela à qual o TableAdapter está associado. O diagrama a seguir mostra como os TableAdapters interagem com bancos de dados e outros objetos na memória:

Embora os TableAdapters sejam projetados com o Designer de Conjunto de Dados, as classes TableAdapter não são geradas como classes aninhadas do DataSet. Eles estão localizados em namespaces separados específicos para cada conjunto de dados. Por exemplo, se você tiver um conjunto de dados chamado NorthwindDataSet, os TableAdapters associados a DataTables no NorthwindDataSet estarão no namespace NorthwindDataSetTableAdapters. Para acessar um TableAdapter específico programaticamente, você deve declarar uma nova instância do TableAdapter. Por exemplo:

NorthwindDataSet northwindDataSet = new NorthwindDataSet();

NorthwindDataSetTableAdapters.CustomersTableAdapter customersTableAdapter = 
    new NorthwindDataSetTableAdapters.CustomersTableAdapter();

customersTableAdapter.Fill(northwindDataSet.Customers);

Dim northwindDataSet As New NorthwindDataSet()
Dim customersTableAdapter As New NorthwindDataSetTableAdapters.CustomersTableAdapter()

customersTableAdapter.Fill(northwindDataSet.Customers)

Esquema do DataTable associado

Ao criar um TableAdapter, você usa a consulta inicial ou o procedimento armazenado para definir o esquema do DataTable associado do TableAdapter. Você executa essa consulta inicial ou procedimento armazenado chamando o método Fill do TableAdapter (que preenche o DataTable associado do TableAdapter). Todas as alterações feitas na consulta principal do TableAdapter são refletidas no esquema da tabela de dados associada. Por exemplo, remover uma coluna da consulta principal também remove a coluna da tabela de dados associada. Se outras consultas no TableAdapter usarem instruções SQL que retornam colunas que não estão na consulta principal, o designer tentará sincronizar as alterações de coluna entre a consulta principal e as consultas adicionais.

Comandos de atualização do TableAdapter

A funcionalidade de atualização de um TableAdapter depende da quantidade de informações disponíveis na consulta principal no Assistente do TableAdapter. Por exemplo, os TableAdapters configurados para buscar valores de várias tabelas (usando um JOIN), valores escalares, exibições ou os resultados de funções de agregação não são criados inicialmente com a capacidade de enviar atualizações para o banco de dados subjacente. No entanto, você pode configurar os comandos INSERT, UPDATE e DELETE manualmente na janela Propriedades.

consultas TableAdapter

Os TableAdapters pode conter várias consultas para preencher suas tabelas de dados associadas. Você pode definir quantas consultas forem necessárias para um TableAdapter, desde que cada consulta retorne dados em conformidade com o mesmo esquema que a tabela de dados associada. Essa funcionalidade permite que um TableAdapter carregue resultados diferentes com base em critérios diferentes.

Por exemplo, se o aplicativo contiver uma tabela com nomes de clientes, você poderá criar uma consulta que preencha a tabela com cada nome de cliente que começa com determinada letra e outra que preencha a tabela com todos os clientes localizados no mesmo estado. Para preencher uma tabela Customers com clientes em determinado estado, você pode criar uma consulta FillByState que usa um parâmetro para o valor de estado da seguinte maneira: SELECT * FROM Customers WHERE State = @State. Execute a consulta chamando o método FillByState e passando o valor do parâmetro como este: CustomerTableAdapter.FillByState("WA").

Além de adicionar consultas que retornam dados do mesmo esquema que a tabela de dados do TableAdapter, você pode adicionar consultas que retornam valores escalares (únicos). Por exemplo, uma consulta que retorna uma contagem de clientes (SELECT Count(*) From Customers) é válida para um CustomersTableAdapter,, mesmo que os dados retornados não estejam em conformidade com o esquema da tabela.

Propriedade ClearBeforeFill

Por padrão, sempre que você executa uma consulta para preencher a tabela de dados de um TableAdapter, os dados existentes são limpos e apenas os resultados da consulta são carregados na tabela. Defina a propriedade ClearBeforeFill do TableAdapter como false se você quiser adicionar ou mesclar os dados retornados de uma consulta aos dados existentes em uma tabela de dados. Independentemente de você limpar os dados, você precisa enviar explicitamente as atualizações para o banco de dados, se quiser mantê-las. Portanto, lembre-se de salvar as alterações nos dados na tabela, antes de executar outra consulta que preencha a tabela. Para obter mais informações, confira Atualizar dados usando um TableAdapter.

Herança do TableAdapter

Os TableAdapters estendem a funcionalidade dos adaptadores de dados padrão encapsulando uma classe DataAdapter configurada. Por padrão, o TableAdapter herda da classe Component e não pode ser convertido na classe DataAdapter. Converter um TableAdapter na classe DataAdapter resulta em um erro InvalidCastException. Para alterar a classe base de um TableAdapter, você pode especificar uma classe derivada do Component na propriedade Classe Base do TableAdapter no Designer de Conjunto de Dados.

Métodos e propriedades do TableAdapter

A classe TableAdapter não é um tipo .NET. Isso significa que você não pode pesquisar na documentação ou no Navegador de Objetos. Ela é criada em tempo de design, quando você usa um dos assistentes mencionados anteriormente. O nome atribuído a um TableAdapter quando você o cria é baseado no nome da tabela com a qual você está trabalhando. Por exemplo, quando você cria um TableAdapter com base em uma tabela em um banco de dados chamado Orders, o TableAdapter é chamado de OrdersTableAdapter. O nome de classe do TableAdapter pode ser alterado usando a propriedade Name no Designer de Conjunto de Dados.

Veja a seguir os métodos e as propriedades normalmente usados do TableAdapters:

Método de atualização do TableAdapter

Os TableAdapters usam comandos de dados para ler e gravar no banco de dados. Use a consulta inicial (principal) Fill do TableAdapter como base para criar o esquema da tabela de dados associada, bem como os comandos InsertCommand, UpdateCommand e DeleteCommand associados ao método TableAdapter.Update. Chamar um método Update do TableAdapter executa as instruções que foram criadas quando o TableAdapter foi configurado originalmente, não uma das consultas adicionais que você adicionou com o Assistente de Configuração de Consulta do TableAdapter.

Quando você usa um TableAdapter, ele executa efetivamente as mesmas operações com os comandos que normalmente você executaria. Por exemplo, quando você chama o método Fill do adaptador, o adaptador executa o comando de dados na propriedade SelectCommand e usa um leitor de dados (por exemplo, SqlDataReader) para carregar o conjunto de resultados na tabela de dados. Da mesma forma, quando você chama o método Update do adaptador, ele executa o comando apropriado (nas propriedades UpdateCommand, InsertCommand e DeleteCommand) para cada registro alterado na tabela de dados.

TableAdapter GenerateDbDirectMethods

Além de InsertCommand, UpdateCommand e DeleteCommand, os TableAdapters são criados com métodos que você pode executar diretamente no banco de dados. Você pode chamar esses métodos (TableAdapter.Insert, TableAdapter.Update e TableAdapter.Delete) diretamente para manipular dados no banco de dados. Isso significa que você pode chamar esses métodos individuais do código, em vez de chamar TableAdapter.Update para lidar com as inserções, atualizações e exclusões pendentes para a tabela de dados associada.

Se você não quiser criar esses métodos diretos, defina a propriedade GenerateDbDirectMethods do TableAdapter como false (na janela Propriedades). Outras consultas que são adicionadas ao TableAdapter são consultas autônomas. Elas não geram esses métodos.

Suporte do TableAdapter para tipos que permitem valor nulo

Os TableAdapters dão suporte a tipos que permitem valor nulo Nullable(Of T) e T?. Para obter mais informações sobre tipos que permitem valor nulo no Visual Basic, consulte Tipos de valores que permitem valor nulo. Para obter mais informações sobre tipos que permitem valor nulo no C#, confira Usar tipos que permitem valor nulo.

Referência de TableAdapterManager

Por padrão, uma classe TableAdapterManager é gerada quando você cria um conjunto de dados que contém tabelas relacionadas. Para impedir que a classe seja gerada, altere o valor da propriedade Hierarchical Update do conjunto de dados para false. Quando você arrasta uma tabela que tem uma relação para a superfície de design de uma página do Windows Form ou WPF, o Visual Studio declara uma variável de membro da classe. Se você não usa a vinculação de dados, precisa declarar a variável manualmente.

A classe TableAdapterManager não é um tipo .NET. Portanto, você não pode pesquisá-la na documentação. Ela é criada em tempo de design como parte do processo de criação do conjunto de dados.

Estes são os métodos e as propriedades da classe TableAdapterManager usados com frequência:

Segurança

Ao usar comandos de dados com a propriedade CommandType definida como Text, verifique cuidadosamente as informações enviadas de um cliente antes de passá-las para o banco de dados. Usuários maliciosos podem tentar enviar (injetar) instruções SQL modificadas ou adicionais para obter acesso não autorizado ou para danificar o banco de dados. Antes de transferir a entrada de usuário para um banco de dados, sempre verifique se as informações são válidas. A melhor prática é sempre usar consultas parametrizadas ou procedimentos armazenados, quando possível.

Conteúdo relacionado

• Ferramentas do conjunto de dados