Preencher conjuntos de dados usando TableAdapters em aplicativos .NET Framework
Observação
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 estão desconectados do banco de dados. As tecnologias são especialmente úteis para aplicativos que permitem aos usuários modificar dados e persistir as alterações de volta ao banco de dados. Embora os conjuntos de dados tenham provado ser uma tecnologia muito bem-sucedida, recomendamos que os 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 que você especificar. 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 nenhuma tabela específica.
Observação
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 TableAdapters | Saiba como usar os designers para criar e configurar TableAdapters. |
| Criar consultas parametrizadas do TableAdapter | Saiba como permitir que os usuários forneçam argumentos para procedimentos ou consultas do TableAdapter. |
| aceder diretamente à base 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 a TableAdapters. |
| Ler dados XML em um conjunto de dados | Saiba como trabalhar com dados XML em um conjunto de dados. |
Visão geral do TableAdapter
TableAdapters são componentes gerados pelo designer que se conectam a um banco de dados, executam consultas ou procedimentos armazenados e preenchem sua DataTable com os dados retornados. TableAdapters também envia dados atualizados do seu aplicativo de volta para o banco de dados. Você pode executar quantas consultas quiser em um TableAdapter, desde que ele retorne dados que estejam em conformidade com o esquema de sua tabela associada. O diagrama a seguir mostra como TableAdapters interagem com bancos de dados e outros objetos na memória:
Embora os TableAdapters sejam projetados com o Dataset Designer, 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 tiveres um dataset 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 DataTable associado
Ao criar um TableAdapter, você usa a consulta inicial ou o procedimento armazenado para definir o esquema do DataTableassociado do TableAdapter. Execute essa consulta inicial ou procedimento armazenado chamando o método Fill do TableAdapter, que preenche o DataTableassociado do TableAdapter. 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 Dataset Designer também removerá a coluna da tabela de dados associada. Se quaisquer consultas adicionais no TableAdapter usarem instruções SQL que retornem colunas que não estão na consulta principal, o Dataset 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 TableAdapter Wizard. Por exemplo, TableAdapters que são configurados para buscar valores de várias tabelas (usando um JOIN), valores escalares, exibições ou os resultados de funções agregadas 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 o InsertCommand, UpdateCommande DeleteCommand propriedades manualmente na janela Properties.
Consultas do TableAdapter
TableAdapters pode conter várias consultas para preencher suas tabelas de dados associadas. Pode definir tantas consultas quanto o seu aplicativo requer para um TableAdapter, desde que cada consulta retorne dados que estejam em conformidade com o mesmo esquema que a tabela de dados associada. Esse recurso permite que um TableAdapter carregue resultados diferentes com base em critérios diferentes.
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 comece 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 uma tabela de dados do TableAdapter, os dados existentes são limpos e somente 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 mantê-las. Portanto, certifique-se de salvar quaisquer alterações nos dados na tabela antes de executar outra consulta que preencha a tabela. Para obter mais informações, consulte Atualizar Dados Usando um TableAdapter.
Herança de TableAdapter
TableAdapters estendem a funcionalidade de 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 para a classe DataAdapter. Converter um TableAdapter para a classe DataAdapter resulta num erro de InvalidCastException. Para alterar a classe base de um TableAdapter, especifique uma classe que deriva da classe Component na propriedade Base Class do TableAdapter no Dataset Designer.
Métodos e propriedades de TableAdapter
A classe TableAdapter não é um tipo .NET, o que significa que você não pode procurá-la no Pesquisador de Objetos ou na documentação de referência. Visual Studio cria-lo em tempo de design quando você usa um dos assistentes descritos anteriormente. O nome que o Visual Studio atribui a um TableAdapter que você 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 é nomeado OrdersTableAdapter. Para alterar o nome da classe do TableAdapter, use a propriedade Name na janela Propriedades do Dataset Designer.
Os métodos comumente usados e propriedades de um TableAdapter são os seguintes:
| 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 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, consulte Atualizar Dados com um TableAdapter. |
TableAdapter.GetData |
Devolve 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 Fill. |
Método de atualização TableAdapter
TableAdapters usam comandos de dados para ler e gravar a partir do banco de dados. Use a consulta Fill (principal) inicial 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 originalmente configurado, 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 você normalmente executa. Por exemplo, quando você chama o método Fill do adaptador, o adaptador executa o comando data 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.
Observação
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 instrução SELECT tabela, o designer pode não conseguir gerar esses comandos. Nesse caso, você pode receber um erro ao executar o método TableAdapter.Update.
AdaptadorDeTabela GerarMétodosDbDireto
Além de InsertCommand, UpdateCommande DeleteCommand, TableAdapters são criados com os seguintes métodos que você pode executar 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 seu código em vez de chamar TableAdapter.Update para manipular 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. Consultas extras que são adicionadas ao TableAdapter são consultas autônomas, que não geram esses métodos.
Suporte a TableAdapter para tipos anuláveis
TableAdapters suportam tipos anuláveis Nullable<T> e T?. Para obter mais informações sobre tipos anuláveis no Visual Basic, consulte Nullable value types (Visual Basic). Para obter mais informações sobre tipos anuláveis em C#, consulte Nullable value types (C#).
Referência do 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 arrastas 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 databinding, 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 cria-o durante o tempo de design como parte do processo de criação de conjuntos de dados.
A tabela a seguir lista métodos e propriedades usados com freqüência da classe TableAdapterManager:
| Membro | Descrição |
|---|---|
Método UpdateAll |
Salva todos os dados de todas as tabelas de dados. |
BackUpDataSetBeforeUpdate propriedade |
Determina se uma cópia de backup do conjunto de dados deve ser criada antes de executar o TableAdapterManager.UpdateAllmethod.Boolean. |
tableNameTableAdapter propriedade |
Representa um adaptador de tabela. O TableAdapterManager gerado contém uma propriedade para cada TableAdapter que gerencia. Por exemplo, um conjunto de dados com as tabelas "Customers" e "Orders" é gerado com um TableAdapterManager que contém as propriedades CustomersTableAdapter e OrdersTableAdapter. |
UpdateOrder propriedade |
Controla a ordem dos comandos individuais de inserção, atualização e exclusão. 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, em seguida, 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á-las 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.