Preencher conjuntos de dados usando TableAdapters em aplicativos do .NET Framework
Observação
Os conjuntos de dados e as 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 estão desconectados do banco de dados. As tecnologias são bastante úteis em 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, é recomendado que os novos aplicativos .NET usem o Entity Framework Core. O Entity Framework proporciona uma forma mais natural de trabalhar com dados tabulares como modelos de objeto e conta com 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. 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.
Observação
Os TableAdapters são gerados por designers do Visual Studio. Se você estiver criando conjuntos de dados programaticamente, use o DataAdapter, que é uma classe .NET.
Para obter informações detalhadas sobre as operações do TableAdapter, você pode pular diretamente para um destes tópicos:
| Tópico | Descrição |
|---|---|
| Criar e configurar TableAdapters | Como usar os designers para criar e configurar TableAdapters |
| Criar consultas TableAdapter parametrizadas | Como permitir que os usuários forneçam argumentos para procedimentos ou consultas do TableAdapter |
| Acessar o banco de dados diretamente com um TableAdapter | Como usar os métodos Dbdirect do TableAdapters |
| Desabilitar restrições ao preencher um conjunto de dados | Como trabalhar com restrições de chave estrangeira ao atualizar dados |
| Como estender a funcionalidade de um TableAdapter | Como adicionar código personalizado a TableAdapters |
| Ler dados XML em um conjunto de dados | Como trabalhar com XML |
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);
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:
| Membro | DESCRIÇÃO |
|---|---|
TableAdapter.Fill |
Preenche a tabela de dados associada do TableAdapter com os resultados do comando SELECT do TableAdapter. |
TableAdapter.Update |
Envia as alterações para o 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 cheio de dados. |
TableAdapter.Insert |
Cria uma nova linha na tabela de dados. Para obter mais informações, confira Inserir novos registros em um banco de dados. |
TableAdapter.ClearBeforeFill |
Determina se uma tabela de dados é esvaziada, antes de chamar um dos métodos 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 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.
Observação
Se houver informações suficientes na consulta principal, os comandos InsertCommand, UpdateCommand e DeleteCommand serão criados por padrão quando o TableAdapter for gerado. Se a consulta principal do TableAdapter for mais do que uma única instrução SELECT da tabela, é possível que o designer não seja capaz de gerar InsertCommand, UpdateCommand e DeleteCommand. Se esses comandos não forem gerados, você poderá receber um erro ao executar o método TableAdapter.Update.
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:
| 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 method.Boolean TableAdapterManager.UpdateAll. |
propriedade tableName TableAdapter |
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 de Clientes e Pedidos é gerado com um TableAdapterManager que contém as propriedades CustomersTableAdapter e OrdersTableAdapter. |
Propriedade UpdateOrder |
Controla a ordem dos comandos de inserção, atualização e exclusão individuais. Defina como um dos valores na enumeração TableAdapterManager.UpdateOrderOption.Por padrão, o UpdateOrder é definido como InsertUpdateDelete. Isso significa que inserções, atualizações e exclusões são executadas para todas as tabelas no conjunto de dados. |
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.