Información general sobre TableAdapter

Artículo
10/07/2008

Actualización: noviembre 2007

Los TableAdapters comunican la aplicación con una base de datos. Más específicamente, un TableAdapter se conecta con una base de datos, ejecuta consultas o procedimientos almacenados, y devuelve una nueva tabla de datos rellena con los datos devueltos o rellena una DataTable existente con los datos devueltos. Los TableAdapters también se utilizan para devolver los datos actualizados desde la aplicación a la base de datos.

Los usuarios de versiones anteriores de Visual Studio pueden pensar en un TableAdapter como un DataAdapter que lleva integrado un objeto de conexión y la capacidad de contener varias consultas. Cada consulta agregada a un TableAdapter se expone como un método público al que se llama simplemente como a cualquier otro método o función de un objeto.

Además de la funcionalidad estándar del control DataAdapter, los objetos TableAdapter proporcionan métodos con tipo adicionales que encapsulan consultas que comparten un esquema común con el control DataTable con tipo asociado. Dicho de otra forma, puede tener tantas consultas como desee en un TableAdapter, siempre y cuando devuelvan datos que cumplan el mismo esquema.

En la versión anterior de Visual Studio, se utilizaron Adaptadores de datos ADO.NET para comunicar una aplicación con una base de datos. Aunque los adaptadores de datos siguen siendo un componente principal de .Proveedores de datos de .NET Framework (ADO.NET), los objetos TableAdapter son componentes generados por el diseñador que mejoran la funcionalidad de los controles DataAdapter. Estos objetos suelen contener los métodos Fill y Update para obtener y actualizar los datos en una base de datos.

Los TableAdapter se crean con el Diseñador de DataSet dentro de los conjuntos de datos con establecimiento inflexible de tipos. Con Asistente para la configuración de orígenes de datos puede crear objetos TableAdapter durante la creación de un nuevo conjunto de datos. También puede crearlos en conjuntos de datos existentes con el Asistente para la configuración de TableAdapter o arrastrando los objetos de base de datos del Explorador de servidores al Diseñador de DataSet. Para obtener más información, vea Cómo: Crear TableAdapters.

Aunque los objetos TableAdapter se diseñan con el Diseñador de DataSet, las clases TableAdapter generadas no se generan como clases anidadas de DataSet. Se encuentran en un espacio de nombres separado y específico para cada conjunto de datos. Por ejemplo, si tiene un conjunto de datos denominado NorthwindDataSet, los TableAdapter asociados al control DataTable en NorthwindDataSet estarían en el espacio de nombres NorthwindDataSetTableAdapters. Para tener acceso a un TableAdapter determinado mediante programación, debe declarar una nueva instancia del TableAdapter. Por ejemplo:

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

customersTableAdapter.Fill(northwindDataSet.Customers)

NorthwindDataSet northwindDataSet = new NorthwindDataSet();

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

customersTableAdapter.Fill(northwindDataSet.Customers);

Esquema de DataTable asociado

Al crear un objeto TableAdapter, se utiliza la consulta inicial o el procedimiento almacenado para definir el esquema de DataTable asociado al TableAdapter. Esta consulta inicial o procedimiento almacenado se ejecuta llamando al método principal Fill del TableAdapter (que rellena la DataTable asociada al TableAdapter). Cualquier cambio realizado en la consulta principal del TableAdapter se refleja en el esquema de la tabla de datos asociada. Por ejemplo, al quitar una columna de la consulta principal, se quita la columna de la tabla de datos asociada. Si alguna consulta adicional del TableAdapter utiliza instrucciones SQL que devuelven columnas que no están en la consulta principal, el diseñador intentará sincronizar los cambios de columna entre la consulta principal y cualquier consulta adicional. Para obtener más información, vea Cómo: Editar TableAdapters.

Comandos de actualización de TableAdapter

La funcionalidad de actualización de un objeto TableAdapter depende de la cantidad de información disponible, en función de la consulta principal proporcionada en el Asistente de TableAdapter. Por ejemplo, los TableAdapter configurados para obtener valores de varias tablas (consultas JOIN), valores escalares, vistas o los resultados de funciones de agregado no se crean inicialmente con la capacidad de enviar actualizaciones a la base de datos subyacente. Sin embargo, puede configurar manualmente los comandos INSERT, UPDATE y DELETE en la ventana Propiedades.

Consultas de TableAdapter

A diferencia de los adaptadores de datos estándar, los TableAdapter pueden contener varias consultas que rellenan las tablas de datos asociadas. Puede definir tantas consultas para un TableAdapter como requiera la aplicación, con tal de que cada consulta devuelva datos que cumplan el mismo esquema que la tabla de datos asociada. De esta forma se habilita la carga de datos que satisface distintos criterios. Por ejemplo, si la aplicación contiene una tabla de clientes, puede crear una consulta para rellenar la tabla con todos los clientes cuyo nombre comience con una letra determinada y otra consulta para rellenar la tabla con todos los clientes del mismo estado o provincia. Para rellenar una tabla Customers con clientes de un estado concreto, puede crear una consulta FillByState que toma un parámetro para el valor del estado: SELECT * FROM Customers WHERE State = @State. Ejecute la consulta llamando al método FillByState y pasando un valor del parámetro como: CustomerTableAdapter.FillByState("WA"). Para obtener más información, vea Cómo: Crear consultas de TableAdapter.

Además de consultas que devuelven datos del mismo esquema como tabla de datos del TableAdapter, también puede agregar consultas que devuelvan valores escalares (únicos). Por ejemplo, la creación de una consulta que devuelve un recuento de clientes (SELECT Count(*) From Customers) es una consulta válida para CustomersTableAdapter, aunque los datos devueltos no cumplan el esquema de la tabla.

Propiedad ClearBeforeFill

El objeto TableAdapter agrega una propiedad no disponible en la clase base DataAdapter. De manera predeterminada, cada vez que ejecuta una consulta para rellenar la tabla de datos del TableAdapter, se borran los datos y sólo se cargan en la tabla los resultados de la consulta. Establezca la propiedad ClearBeforeFill del TableAdapter en false si desea agregar o combinar los datos devueltos de una consulta con los datos existentes en una tabla de datos. Sin tener en cuenta si borra los datos, es necesario enviar explícitamente las actualizaciones a la base de datos, si lo desea. Por tanto, recuerde guardar los cambios realizados en los datos de la tabla antes de ejecutar otra consulta que rellene la tabla. Para obtener más información, vea Cómo: Actualizar datos utilizando un TableAdapter.

Herencia de TableAdapter

Los TableAdapter amplían la funcionalidad de los adaptadores de datos estándar encapsulando un control DataAdapter. De manera predeterminada, el objeto TableAdapter hereda de Component y no se puede convertir a la clase DataAdapter. Convertir un TableAdapter a un control DataAdapter produce un InvalidCastException. Para cambiar la clase base de un TableAdapter, en el Diseñador de DataSet se escribe una clase que derive de Component en la propiedad Base Class del TableAdapter.

Métodos y propiedades de TableAdapter

La clase TableAdapter no forma parte de .NET Framework y como tal, no puede buscarla en la documentación ni en el Explorador de objetos. Se crea en tiempo de diseño cuando utiliza uno de los asistentes anteriormente mencionados. El nombre asignado a un TableAdapter en el momento de su creación se basa en el nombre de la tabla con la que está trabajando. Por ejemplo, si se crea un TableAdapter basado en una tabla de una base de datos denominada Orders, los TableAdapter se denominan en consecuencia OrdersTableAdapter. Se puede cambiar el nombre de clase del TableAdapter utilizando la propiedad Name en el Diseñador de DataSet.

A continuación se muestran los métodos y propiedades de TableAdapter más utilizados:

Miembro	Descripción
TableAdapter.Fill	Rellena la tabla de datos asociada del TableAdapter con los resultados del comando SELECT del TableAdapter. Para obtener más información, vea Cómo: Llenar un conjunto de datos con datos.
TableAdapter.Update	Envía los cambios de vuelta a la base de datos y devuelve un entero que representa el número de filas a las que afecta la actualización. Para obtener más información, vea Cómo: Actualizar datos utilizando un TableAdapter.
TableAdapter.GetData	Devuelve una nueva DataTable rellena con datos.
TableAdapter.Insert	Crea una nueva fila en la tabla de datos. Para obtener más información, vea Cómo: Agregar filas a un DataTable.
TableAdapter.ClearBeforeFill	Determina si se vacía una tabla de datos antes de llamar a uno de los métodos Fill.

Método de actualización de TableAdapter

Los TableAdapter utilizan comandos de datos para leer y escribir en la base de datos. La consulta (principal) Fill inicial de TableAdapter se utiliza como base para crear el esquema de la tabla de datos asociada, así como los comandos InsertCommand, UpdateCommand y DeleteCommand asociados al método TableAdapter.Update. Esto significa que al llamar al método Update de TableAdapter se ejecutan las instrucciones creadas cuando el TableAdapter se configuró originalmente, y no se agregó ninguna de las consultas adicionales al Asistente para la configuración de consultas de TableAdapter.

Cuando utiliza un TableAdapter, éste realiza las mismas operaciones con los comandos que realizaría habitualmente. Por ejemplo, cuando se llama al método Fill del adaptador, éste ejecuta el comando de datos en la propiedad SelectCommand y utiliza un lector de datos (por ejemplo, SqlDataReader) para cargar el conjunto de resultados en la tabla de datos. De igual forma, cuando se llama al método Update del adaptador, se ejecuta el comando adecuado (en las propiedades UpdateCommand, InsertCommand y DeleteCommand) para cada registro modificado de la tabla de datos.

Nota:
Si hay bastante información en la consulta principal, se crean los comandos InsertCommand, UpdateCommand y DeleteCommand de manera predeterminada cuando se genera el TableAdapter. Si la consulta principal de TableAdapter es más que una instrucción SELECT de una única tabla, es posible que el diseñador no pueda generar los comandos InsertCommand, UpdateCommand y DeleteCommand. Si no se han generado estos comandos, puede recibir un error al ejecutar el método TableAdapter.Update.

Si hay bastante información en la consulta principal, se crean los comandos InsertCommand, UpdateCommand y DeleteCommand de manera predeterminada cuando se genera el TableAdapter. Si la consulta principal de TableAdapter es más que una instrucción SELECT de una única tabla, es posible que el diseñador no pueda generar los comandos InsertCommand, UpdateCommand y DeleteCommand. Si no se han generado estos comandos, puede recibir un error al ejecutar el método TableAdapter.Update.

TableAdapter GenerateDbDirectMethods

Además de con los comandos InsertCommand, UpdateCommand y DeleteCommand, los TableAdapters se crean con métodos que se pueden ejecutar directamente en la base de datos. Se puede llamar a estos métodos (TableAdapter.Insert, TableAdapter.Update y TableAdapter.Delete) para manipular los datos directamente en la base de datos.

Si no desea crear estos métodos directos, establezca la propiedad GenerateDbDirectMethods del TableAdapter en false (en la ventana Propiedades). Las consultas adicionales agregadas al objeto TableAdapter son consultas independientes y no generan estos métodos.

Compatibilidad del objeto TableAdapter con los tipos que aceptan valores NULL

Los TableAdapters admiten tipos que aceptan valores NULL Nullable(Of T) y T?. Para obtener más información sobre los tipos que aceptan valores NULL, vea Tipos de valor que aceptan valores NULL. Para obtener más información sobre los tipos que aceptan valores NULL en C#, vea Utilizar tipos que aceptan valores NULL (Guía de programación de C#).

Vea también

Compartir a través de