Compartilhar via

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

Nota

Conjuntos de dados e classes relacionadas são tecnologias herdadas do .NET Framework do início dos anos 2000 que permitem que os aplicativos trabalhem com dados na memória enquanto os aplicativos são desconectados do banco de dados. As tecnologias são especialmente úteis para aplicativos que permitem que os usuários modifiquem dados e persistam as alterações no banco de dados. Embora os conjuntos de dados tenham se mostrado uma tecnologia muito bem-sucedida, recomendamos que novos aplicativos .NET usem Entity Framework Core. O Entity Framework fornece uma maneira mais natural de trabalhar com dados tabulares como modelos de objeto e tem uma interface de programação mais simples.

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. TableAdapters também pode executar adições, atualizações e exclusões no banco de dados para persistir as alterações feitas no conjunto de dados. Além disso, você pode emitir comandos globais que não estão relacionados a qualquer tabela específica.

Nota

Os designers do Visual Studio geram TableAdapters. Se você estiver criando conjuntos de dados programaticamente, use a classe .NET DataAdapter.

Para obter informações detalhadas sobre operações tableAdapter, você pode pular diretamente para um destes artigos:

Artigo Descrição
Criar e configurar adaptadores de tabela Saiba como usar os designers para criar e configurar TableAdapters.
Criar consultas TableAdapter parametrizadas Saiba como permitir que os usuários forneçam argumentos para procedimentos ou consultas do TableAdapter.
Acesse diretamente o banco de dados com um TableAdapter Saiba como usar os métodos DbDirect de TableAdapters.
desativar restrições ao preencher um conjunto de dados Saiba como trabalhar com restrições de chave estrangeira ao atualizar dados.
Estender a funcionalidade de um TableAdapter Saiba como adicionar código personalizado ao TableAdapters.
Ler dados XML em um conjunto de dados Saiba como trabalhar com dados XML em um conjunto de dados.

Visão geral de TableAdapter

TableAdapters são componentes gerados pelo designer que se conectam a um banco de dados, executam consultas ou procedimentos armazenados e preenchem seus DataTable com os dados retornados. Os TableAdapters também enviam dados atualizados do aplicativo de volta para o banco de dados. Você pode executar quantas consultas desejar em um TableAdapter, desde que retorne dados que estejam em conformidade com o esquema de sua tabela associada. O diagrama a seguir mostra como o TableAdapters interage com bancos de dados e outros objetos na memória:

Diagrama que mostra o fluxo de dados TableAdapter em um aplicativo cliente.

Embora Os TableAdapters sejam projetados com o Designer de Conjunto de Dados, as classes TableAdapter não são geradas como classes aninhadas de DataSet. Em vez disso, eles estão localizados em namespaces separados que são específicos para cada conjunto de dados. Por exemplo, se você tiver um conjunto de dados chamado NorthwindDataSet, os TableAdapters associados a objetos DataTable no NorthwindDataSet estarão no namespace NorthwindDataSetTableAdapters. Para acessar um TableAdapter específico programaticamente, declare uma nova instância da classe TableAdapter. Por exemplo:

NorthwindDataSet northwindDataSet = new NorthwindDataSet();

NorthwindDataSetTableAdapters.CustomersTableAdapter customersTableAdapter = 
    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. Para executar essa consulta inicial ou procedimento armazenado, chame o método Fill do TableAdapter, que preenche o DataTableassociado. Todas as alterações feitas na consulta principal do TableAdapter são refletidas no esquema da tabela de dados associada. Por exemplo, se você remover uma coluna da consulta principal, o Designer de Conjunto de Dados também removerá a coluna da tabela de dados associada. Se quaisquer consultas adicionais no TableAdapter usarem instruções SQL que retornam colunas que não estão na consulta principal, o Designer de Conjunto de Dados 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 TableAdapter. Por exemplo, 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 de volta para o banco de dados subjacente. No entanto, você pode configurar as propriedades InsertCommand, UpdateCommande DeleteCommand manualmente na janela Propriedades do.

Consultas TableAdapter

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 que estejam em conformidade com o mesmo esquema da tabela de dados associada. Essa funcionalidade permite que um TableAdapter carregue resultados diferentes com base em critérios diferentes.

Diagrama que mostra um TableAdapter com várias consultas.

Por exemplo, se seu 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 uma determinada letra. Você pode criar outra consulta que preencha a tabela com todos os clientes localizados no mesmo estado. Para preencher uma tabela Customers com clientes em um determinado estado, crie 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, por exemplo: 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. Se você quiser adicionar ou mesclar os dados que uma consulta retorna aos dados existentes em uma tabela de dados, defina a propriedade ClearBeforeFill do TableAdapter como false. Independentemente de limpar os dados, você deve enviar explicitamente as atualizações de volta para o banco de dados se quiser persistê-las. Portanto, certifique-se de salvar todas 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 de TableAdapter

Os TableAdapters estendem a funcionalidade dos adaptadores de dados padrão encapsulando uma classe de 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, especifique uma classe que deriva da classe 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, o que significa que você não pode pesquisá-la no Pesquisador de Objetos ou na documentação de referência. O Visual Studio o cria em tempo de design quando você usa um dos assistentes descritos anteriormente. O nome que o Visual Studio atribui a um TableAdapter criado é 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 é nomeado OrdersTableAdapter. Para alterar o nome da classe do TableAdapter, use a propriedade Name na janela Propriedadesdo Designer do Conjunto de Dados.

Os métodos e as propriedades comumente usados de um TableAdapter são os seguintes:

Membro Descrição
TableAdapter.Fill Popula a tabela de dados associada do TableAdapter com os resultados do comando SELECT do TableAdapter.
TableAdapter.Update Envia alterações de volta ao banco de dados e retorna um inteiro que representa o número de linhas afetadas pela atualização. Para obter mais informações, confira Atualizar dados usando um TableAdapter.
TableAdapter.GetData Retorna um novo DataTable preenchido com dados.
TableAdapter.Insert Cria uma nova linha na tabela de dados. Para obter mais informações, consulte Inserir novos registros em um banco de dados.
TableAdapter.ClearBeforeFill Determina se uma tabela de dados é esvaziada antes de chamar um dos métodos de Fill.

Método de atualização do TableAdapter

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

Quando você usa um TableAdapter, ele efetivamente executa as mesmas operações com os comandos que normalmente você executa. Por exemplo, quando você chama o método Fill do adaptador, o adaptador executa o comando de dados em sua 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, InsertCommande DeleteCommand) para cada registro alterado na tabela de dados.

Nota

Se a consulta principal contiver informações suficientes, o designer criará os comandos InsertCommand, UpdateCommande DeleteCommand por padrão quando o designer gerar o TableAdapter. No entanto, se a consulta principal do TableAdapter for mais do que uma única tabela SELECT instrução, o designer poderá não ser capaz de gerar esses comandos. Nesse caso, você pode receber um erro ao executar o método TableAdapter.Update.

TableAdapter GenerateDbDirectMethods

Além de InsertCommand, UpdateCommande DeleteCommand, os TableAdapters são criados com os seguintes métodos que podem ser executados diretamente no banco de dados: TableAdapter.Insert, TableAdapter.Updatee TableAdapter.Delete. Você pode chamar esses métodos 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 para False na janela Propriedades. Consultas extras adicionadas ao TableAdapter são consultas autônomas, que não geram esses métodos.

Suporte do TableAdapter para tipos que permitem valor nulo

Os TableAdapters dão suporte a tipos anuláveis Nullable<T> e T?. Para obter mais informações sobre tipos anuláveis no Visual Basic, consulte tipos de valor anuláveis (Visual Basic). Para obter mais informações sobre tipos anuláveis em C#, consulte tipos de valor anuláveis (C#).

Referência de TableAdapterManager

Por padrão, o Visual Studio gera uma classe TableAdapterManager 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 membro da classe. Se você não usar a vinculação de dados, deverá declarar manualmente a variável.

Como a classe TableAdapterManager não é um tipo .NET, ela não aparece na documentação de referência. O Visual Studio o cria no momento do design como parte do processo de criação do dataset.

A tabela a seguir lista métodos e propriedades usados com frequência da classe TableAdapterManager:

Membro Descrição
método UpdateAll Salva todos os dados de todas as tabelas de dados.
Propriedade BackUpDataSetBeforeUpdate Determina se é necessário criar uma cópia de backup do conjunto de dados antes de executar o TableAdapterManager.UpdateAllmethod.Boolean.
Propriedade tableNameTableAdapter Representa um TableAdapter. O TableAdapterManager gerado contém uma propriedade para cada TableAdapter que ele gerencia. Por exemplo, um conjunto de dados com uma tabela Clientes e Pedidos é gerado com um TableAdapterManager que contém propriedades CustomersTableAdapter e OrdersTableAdapter.
Propriedade UpdateOrder Controla a ordem dos comandos de inserção, atualização e exclusão individuais. Defina essa propriedade como um dos valores na enumeração TableAdapterManager.UpdateOrderOption.

Por padrão, o UpdateOrder é definido como InsertUpdateDelete, o que significa que inserções, atualizações e exclusões são executadas para todas as tabelas no conjunto de dados.

Segurança

Quando você usa comandos de dados com uma propriedade CommandType definida como Text, verifique cuidadosamente as informações enviadas de um cliente antes de passá-los para o banco de dados. Usuários mal-intencionados podem tentar enviar (injetar) instruções SQL modificadas ou extras para obter acesso não autorizado ao banco de dados. Antes de transferir a entrada do usuário para um banco de dados, sempre verifique se as informações são válidas. Uma prática recomendada é usar consultas parametrizadas ou procedimentos armazenados quando possível.

Conteúdo relacionado