The DataAdapter

only for RuBoard

In Chapter 2, you looked at the DataSet as a collection of DataTable object s. You used the DataTable s in the DataSet to populate one or more server controls on an ASP.NET Web Form. The DataAdapter is the bridge between the DataSet and the data store.

Unlike the past model of connection-based data processing, the DataAdapter works on a disconnected message-based model, revolving around and delivering chunks of info - rmation in a disconnected fashion. The DataAdapter is made up of four command methods , a TableMappings collection, a Command collection, and an Exception collection (for OleDbErrors). Like the other objects in the Managed Providers, the DataAdapter comes in two stock flavors, the SqlDataAdapter and the OleDbDataAdapter . Figure 3.4 illustrates the DataAdapter Object Model.

Figure 3.4. The `DataAdapter` Object Model.

The primary function of a DataAdapter is to retrieve data from a data store and push it into a DataTable in the DataSet . To complete this task, the DataAdapter requires two pieces of information, or parameters:

A Managed Connection
A Select Command

The DataAdapter constructor can accept either the command and connection values as text, or a Managed Command object as a single parameter. Listing 3.7 demonstrated constructing a DataAdapter with text values, while Listing 3.8 demonstrates constructing the DataAdapter with a single Managed Command.

Listing 3.8 Creating a `SqlDataAdapter` with Connection and Command Text Values

 [VB] 01: <%@ Page Language="VB" %> 02: <%@ Import Namespace="System.Data" %> 03: <%@ Import Namespace="System.Data.SqlClient" %> 04: <script runat="server"> 05:  Sub Page_Load(Sender As Object, E As EventArgs) 06:   Dim myDataAdapter As SqlDataAdapter 07:   Dim myDataSet As New DataSet 08:   myDataAdapter = New SqlDataAdapter("SELECT * FROM Customers", "server=localhost;  database=Northwind; uid=sa; pwd=;") 09:   myDataAdapter.Fill(myDataSet, "Customers") 10:   myDataGrid.DataSource = myDataSet.Tables("Customers").DefaultView 11:   myDataGrid.DataBind() 12:  End Sub 13: </script> [C#] 01: <%@ Page Language="C#" %> 02: <%@ Import Namespace="System.Data" %> 03: <%@ Import Namespace="System.Data.SqlClient" %> 04: <script runat="server"> 05:  void Page_Load(Object sender, EventArgs e){ 06:   SqlDataAdapter myDataAdapter; 07:   DataSet myDataSet = new DataSet(); 08:   myDataAdapter = new SqlDataAdapter("SELECT * FROM Customers", "server=localhost;  database=Northwind; uid=sa; pwd=;"); 09:   myDataAdapter.Fill(myDataSet, "Customers"); 10:   myDataGrid.DataSource = myDataSet.Tables["Customers"].DefaultView; 11:   myDataGrid.DataBind(); 12:  } 13: </script> [VB & C#] 14: <html> 15: <body> 16: <form runat="server" method="post"> 17:  <asp:DataGrid runat="server" id="myDataGrid" /> 18: </form> 19: </body> 20: </html>

In Listing 3.8 you create an instance of the SqlDataAdapter class. When instantiating the class, on line 8 you pass in the command and connection values as text. The DataAdapter uses these values to create SqlCommand and SqlConnection objects behind the scenes. These objects are used to connect to the database and retrieve the appropriate data.

In Listing 3.9 you achieve the same result as in Listing 3.8, using explicit SqlCommand and SqlConnection objects.

Listing 3.9 Creating an `SqlDataAdapter` with Connection and Command Objects

 [VB] 01: <%@ Page Language="VB" %> 02: <%@ Import Namespace="System.Data" %> 03: <%@ Import Namespace="System.Data.SqlClient" %> 04: <script runat="server"> 05:  Sub Page_Load(Sender As Object, E As EventArgs) 06:   Dim myConnection As SqlConnection 07:   Dim myCommand As SqlCommand 08:   Dim myDataAdapter As SqlDataAdapter 09:   Dim myDataSet As New DataSet 10:   myConnection = New SqlConnection("server=localhost; database=Northwind; uid=sa;  pwd=;") 11:   myCommand = New SqlCommand("SELECT * FROM Customers", myConnection) 12:   myDataAdapter = New SqlDataAdapter(myCommand) 13:   myDataAdapter.Fill(myDataSet, "Customers") 14:   myDataGrid.DataSource = myDataSet.Tables("Customers") 15:   myDataGrid.DataBind() 16:  End Sub 17: </script> [C#] 01: <%@ Page Language="C#" %> 02: <%@ Import Namespace="System.Data" %> 03: <%@ Import Namespace="System.Data.SqlClient" %> 04: <script runat="server"> 05:  void Page_Load(Object sender, EventArgs e){ 06:   SqlConnection myConnection; 07:   SqlCommand myCommand; 08:   SqlDataAdapter myDataAdapter; 09:   DataSet myDataSet = new DataSet(); 10:   myConnection = new SqlConnection("server=localhost; database=Northwind; uid=sa;  pwd=;"); 11:   myCommand = new SqlCommand("SELECT * FROM Customers", myConnection); 12:   myDataAdapter = new SqlDataAdapter(myCommand); 13:   myDataAdapter.Fill(myDataSet, "Customers"); 14:   myDataGrid.DataSource = myDataSet.Tables["Customers"]; 15:   myDataGrid.DataBind(); 16:  } 17: </script> [VB & C#] 18: <html> 19: <body> 20: <form runat="server" method="post"> 21:  <asp:DataGrid runat="server" id="myDataGrid" /> 22: </form> 23: </body> 24: </html>

In Listing 3.9 you explicitly create SqlCommand and SqlConnection objects. The SqlConnection object is used when constructing the SqlCommand object, and the SqlCommand object is passed into the SqlDataAdapter when it is instantiated .

While this might seem logical, it is more efficient to create the DataAdapter using the text values. The DataAdapter will manage the creation and destruction of the connection and command objects it requires. The explicit creation of these objects is only useful if you will be using either or both of them again, separate of the DataAdapter .

`DataAdapter.Fill()` Method

In Listings 3.8 and 3.9, you used various techniques and languages to create an instance of the Managed Provider DataAdapter . In one fashion or another, you created the DataAdapter and passed it values for the SelectCommand and Connection properties (either as inline values or as objects). Once the DataAdapter was created, the Fill() method of the DataAdapter was called.

The DataAdapter. Fill() method is like the switch that makes it go. Up until the Fill() method is called, the DataAdapter is idle. When the Fill() method is called, the connection to the database is made, and the SQL statement is executed. The results from the execution are filled into a DataSet , specified as a parameter of the Fill() method.

Specifying only a DataSet to fill the result set will cause a new DataTable object to be created in the DataSet . The DataTable is then accessible by its index value.

  DataAdapter.  Fill(  [DataSet]  )  DataGrid.  DataSource =  DataSet.  Tables(0)

Optionally, you can also pass in a string value representing the name you would like assigned to the DataTable that is created. This makes your code easier to follow and more readable, as you can then access the DataTable by name rather than by its index value.

  DataAdapter.  Fill(  [DataSet],  "  [Table Name]  ")  DataGrid.  DataSource =  DataSet.  Tables("  [Table Name]  ")

On line 13 of Listing 3.9 you invoke the Fill() method of the DataAdapter and fill the results of the executed SQL statement into an empty DataSet , creating a new DataTable named "Customers".

When the Fill() method is invoked, the bridge to the data store is extended. Then the data is retrieved and brought back to the calling application in the form of an XML file. This XML file is materialized as a DataTable in the DataSet you specified. The DataTable schema (table/column/primary key definitions) will be created automatically based on the schema of the database. Figure 3.5 illustrates the process when you're invoking the DataAdapter.Fill() method.

Figure 3.5. Invoking the `Fill()` method of the `DataAdapter` class causes a bridge to be extended to the data store and the results to be returned to the calling application in the form of an XML file. The XML file is materialized as a `DataTable` in a `DataSet` .

While the Fill() method will create the DataTable dynamically, it can also fill an existing DataTable that you create explicitly, as shown in Listing 3.10.

Listing 3.10 Using the DataAdapter with an Existing DataTable

 [VB] 01: <%@ Page Language="VB" %> 02: <%@ Import Namespace="System.Data" %> 03: <%@ Import Namespace="System.Data.SqlClient" %> 04: <script runat="server"> 05:  Sub Page_Load(Sender As Object, E As EventArgs) 06:   Dim myDataAdapter As SqlDataAdapter 07:   Dim myDataSet As New DataSet 08: 09:   myDataSet.Tables.Add(New DataTable("Customers")) 10:   myDataSet.Tables("Customers").Columns.Add("CompanyName",  System.Type.GetType("System.String")) 11:   myDataSet.Tables("Customers").Columns.Add("ContactName",  System.Type.GetType("System.String")) 12:   myDataSet.Tables("Customers").Columns.Add("Region",  System.Type.GetType("System.String")) 13: 14:   myDataAdapter = New SqlDataAdapter("SELECT CompanyName, ContactName, Region FROM  Customers", "server=localhost; database=Northwind; uid=sa; pwd=;") 15:   myDataAdapter.Fill(myDataSet, "Customers") 16:   myDataGrid.DataSource = myDataSet.Tables("Customers") 17:   myDataGrid.DataBind() 18:  End Sub 19: </script> [C#] 01: <%@ Page Language="C#" %> 02: <%@ Import Namespace="System.Data" %> 03: <%@ Import Namespace="System.Data.SqlClient" %> 04: <script runat="server"> 05:  void Page_Load(Object sender, EventArgs e){ 06:   SqlDataAdapter myDataAdapter; 07:   DataSet myDataSet = new DataSet(); 08: 09:   myDataSet.Tables.Add(new DataTable("Customers")); 10:   myDataSet.Tables["Customers"].Columns.Add("CompanyName",  System.Type.GetType("System.String")); 11:   myDataSet.Tables["Customers"].Columns.Add("ContactName",  System.Type.GetType("System.String")); 12:   myDataSet.Tables["Customers"].Columns.Add("Region",  System.Type.GetType("System.String")); 13: 14:   myDataAdapter = new SqlDataAdapter("SELECT CompanyName, ContactName, Region FROM  Customers", "server=localhost; database=Northwind; uid=sa; pwd=;"); 15:   myDataAdapter.Fill(myDataSet, "Customers"); 16:   myDataGrid.DataSource = myDataSet.Tables["Customers"]; 17:   myDataGrid.DataBind(); 18:  } 19: </script> [VB & C#] 20: <html> 21: <body> 22: <form runat="server" method="post"> 23:  <asp:DataGrid runat="server" id="myDataGrid" /> 24: </form> 25: </body> 26: </html>

In Listing 3.10 you create a DataTable explicitly on lines 9 “12. Using the Fill() method of the DataAdapter you fill this newly created DataTable with the results from the SQL statement execution. This is done by calling the Fill() method and passing in the DataSet and DataTable name for the DataTable you just created. If data already exists in the DataTable , then the Fill() method will update, or add rows to the DataTable . You can use the same DataAdapter , change its SelectCommand.CommandText property, and invoke the Fill() method again. In Listing 3.11 you use the DataAdapter to return two different result sets from similar SQL statements. You use the Fill() method to add the records to the same DataTable in the DataSet .

Listing 3.11 Using the `Fill()` Method to Add Records to a `DataTable`

 [VB] 01: <%@ Page Language="VB" %> 02: <%@ Import Namespace="System.Data" %> 03: <%@ Import Namespace="System.Data.SqlClient" %> 04: <script runat="server"> 05:  Sub Page_Load(Sender As Object, E As EventArgs) 06:   Dim myDataAdapter As SqlDataAdapter 07:   Dim myDataSet As New DataSet 08: 09:   myDataSet.Tables.Add(New DataTable("Customers")) 10:   myDataSet.Tables("Customers").Columns.Add("CompanyName",  System.Type.GetType("System.String")) 11:   myDataSet.Tables("Customers").Columns.Add("ContactName",  System.Type.GetType("System.String")) 12:   myDataSet.Tables("Customers").Columns.Add("Region",  System.Type.GetType("System.String")) 13: 14:   myDataAdapter = new SqlDataAdapter("GetCustomersByCountry", "server=localhost;  database=Northwind; uid=sa; pwd=;") 15:   myDataAdapter.SelectCommand.CommandType = CommandType.StoredProcedure 16:   myDataAdapter.SelectCommand.Parameters.Add(new SqlParameter("@country",  SqlDbType.VarChar, 50)) 17:   myDataAdapter.SelectCommand.Parameters("@country").Value = "Canada" 18:   myDataAdapter.Fill(myDataSet, "Customers") 19: 20:   myDataAdapter.SelectCommand.Parameters("@country").Value = "Spain" 21:   myDataAdapter.Fill(myDataSet, "Customers") 22: 23:   myDataGrid.DataSource = myDataSet.Tables("Customers") 24:   myDataGrid.DataBind() 25:  End Sub 26: </script> [C#] 01: <%@ Page Language="C#" %> 02: <%@ Import Namespace="System.Data" %> 03: <%@ Import Namespace="System.Data.SqlClient" %> 04: <script runat="server"> 05:  void Page_Load(Object sender, EventArgs e){ 06:   SqlDataAdapter myDataAdapter; 07:   DataSet myDataSet = new DataSet(); 08: 09:   myDataSet.Tables.Add(new DataTable("Customers")); 10:   myDataSet.Tables["Customers"].Columns.Add("CompanyName",  System.Type.GetType("System.String")); 11:   myDataSet.Tables["Customers"].Columns.Add("ContactName",  System.Type.GetType("System.String")); 12:   myDataSet.Tables["Customers"].Columns.Add("Region",  System.Type.GetType("System.String")); 13: 14:   myDataAdapter = new SqlDataAdapter("GetCustomersByCountry", "server=localhost;  database=Northwind; uid=sa; pwd=;"); 15:   myDataAdapter.SelectCommand.CommandType = CommandType.StoredProcedure; 16:   myDataAdapter.SelectCommand.Parameters.Add(new SqlParameter("@country",  SqlDbType.VarChar, 50)); 17:   myDataAdapter.SelectCommand.Parameters["@country"].Value = "Canada"; 18:   myDataAdapter.Fill(myDataSet, "Customers"); 19: 20:   myDataAdapter.SelectCommand.Parameters["@country"].Value = "Spain"; 21:   myDataAdapter.Fill(myDataSet, "Customers"); 22: 23:   myDataGrid.DataSource = myDataSet.Tables["Customers"]; 24:   myDataGrid.DataBind(); 25:  } 26: </script> [VB & C#] 27: <html> 28: <body> 29: <form runat="server" method="post"> 30:  <asp:DataGrid runat="server" id="myDataGrid" /> 31: </form> 32: </body> 33: </html>

In Listing 3.11 you use the DataAdapter to select a small set of records from the database (line 14) with the stored procedure from Listing 3.6. On line 15 you specify that the SelectCommand property of the DataAdapter is a stored procedure. On line 16 you add a parameter for the expected "@country" parameter in the stored procedure. On line 17 you set the value of the parameter to "Canada." Using the Fill() method you add those records to the Customers DataTable on line 18. On line 20 you change the parameter's value to "Spain." Since you are using the same DataAdapter to execute the second Fill() method, you do not need to set the ConnectionString property, or recreate the parameter you are using. Using the Fill() method, on line 18, you add the new result set to the existing records in the Customers table. Figure 3.6 shows the result of executing the code in Listing 3.11.

Figure 3.6. The `DataAdapter.Fill()` method can be used to add records to a `DataTable` , or update existing records.

As you've learned, the DataAdapter works on a disconnected message-based model. You can reuse the DataAdapter to fill additional DataTable s in the same DataSet , or in other DataSets , because there's no physical link between the DataAdapter and the DataSet or DataTable . You only need to change the SelectCommand property of the DataSet (if you want to use a new SQL statement), or change a parameter value (if you want to use the same SQL statement), and call the Fill() method, passing it the new DataSet and DataTable name (see Listing 3.12).

Listing 3.12 Adding a Second `DataTable` to a `DataSet`

 [VB] 01: <%@ Page Language="VB" %> 02: <%@ Import Namespace="System.Data" %> 03: <%@ Import Namespace="System.Data.SqlClient" %> 04: <script runat="server"> 05:  Sub Page_Load(Sender As Object, E As EventArgs) 06:   Dim myDataAdapter As SqlDataAdapter 07:   Dim myDataSet As New DataSet 08: 09:   myDataAdapter = new SqlDataAdapter("GetCustomersByCountry", "server=localhost;  database=Northwind; uid=sa; pwd=;") 10:   myDataAdapter.SelectCommand.CommandType = CommandType.StoredProcedure 11:   myDataAdapter.SelectCommand.Parameters.Add(new SqlParameter("@country",  SqlDbType.VarChar, 50)) 12:   myDataAdapter.SelectCommand.Parameters("@country").Value = "Canada" 13:   myDataAdapter.Fill(myDataSet, "Canada_Customers") 14: 15:   myDataAdapter.SelectCommand.Parameters("@country").Value = "Spain" 16:   myDataAdapter.Fill(myDataSet, "Spain_Customers") 17: 18:   myDataGrid.DataSource = myDataSet.Tables("Canada_Customers") 19:   myDataGrid.DataBind() 20: 21:   myOtherDataGrid.DataSource = myDataSet.Tables("Spain_Customers") 22:   myOtherDataGrid.DataBind() 23:  End Sub 24: </script> [C#] 01: <%@ Page Language="C#" %> 02: <%@ Import Namespace="System.Data" %> 03: <%@ Import Namespace="System.Data.SqlClient" %> 04: <script runat="server"> 05:  void Page_Load(Object sender, EventArgs e){ 06:   SqlDataAdapter myDataAdapter; 07:   DataSet myDataSet = new DataSet(); 08: 09:   myDataAdapter = new SqlDataAdapter("GetCustomersByCountry", "server=localhost;  database=Northwind; uid=sa; pwd=;"); 10:   myDataAdapter.SelectCommand.CommandType = CommandType.StoredProcedure; 11:   myDataAdapter.SelectCommand.Parameters.Add(new SqlParameter("@country",  SqlDbType.VarChar, 50)); 12:   myDataAdapter.SelectCommand.Parameters["@country"].Value = "Canada"; 13:   myDataAdapter.Fill(myDataSet, "Canada_Customers"); 14: 15:   myDataAdapter.SelectCommand.Parameters["@country"].Value = "Spain"; 16:   myDataAdapter.Fill(myDataSet, "Spain_Customers"); 17: 18:   myDataGrid.DataSource = myDataSet.Tables["Canada_Customers"]; 19:   myDataGrid.DataBind(); 20: 21:   myOtherDataGrid.DataSource = myDataSet.Tables["Spain_Customers"]; 22:   myOtherDataGrid.DataBind(); 23:  } 24: </script> [VB & C#] 25: <html> 26: <form runat="server" method="post"> 27: <body> 28:  <asp:DataGrid runat="server" id="myDataGrid" /> 29:  <asp:DataGrid runat="server" id="myOtherDataGrid" /> 30: </form> 31: </body> 32: </html>

In Listing 3.12 you use the same data access code from Listing 3.11. You use the Fill() method to create a new DataTable named Canada_Customers . Then, by resetting the parameter value you retrieve another set of data from the database. Using the Fill() method you create a second DataTable named Spain_Customers . Finally you bind each of these DataTable s to a separate DataGrid . The resulting page is shown in Figure 3.7.

Figure 3.7. The `DataAdapter` can be used to create multiple `DataTables` in one or more `DataSets` . This is allowed because the `DataAdapter` is not explicitly tied to a single `DataSet` or `DataTable` .

only for RuBoard

Figure 3.4. The DataAdapter Object Model.

Listing 3.8 Creating a SqlDataAdapter with Connection and Command Text Values

Listing 3.9 Creating an SqlDataAdapter with Connection and Command Objects

DataAdapter.Fill() Method

Figure 3.5. Invoking the Fill() method of the DataAdapter class causes a bridge to be extended to the data store and the results to be returned to the calling application in the form of an XML file. The XML file is materialized as a DataTable in a DataSet .