You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
title: Configure new TableAdapters in .NET Framework apps
3
-
description: Create and configure a ADO.NET TableAdapter in .NET Framework applications with Visual Studio and enable communication between your app and a database.
4
-
ms.date: 12/15/2023
2
+
title: Configure New TableAdapters in .NET Framework Apps
3
+
description: Create and configure an ADO.NET TableAdapter in .NET Framework applications with Visual Studio and enable communication between your apps and a database.
4
+
ms.date: 07/02/2025
5
5
ms.topic: how-to
6
6
helpviewer_keywords:
7
7
- table adapters, creating
@@ -13,104 +13,145 @@ author: ghogen
13
13
ms.author: ghogen
14
14
manager: mijacobs
15
15
ms.subservice: data-tools
16
+
#customer intent: As a developer, I want to create an ADO.NET TableAdapter in my .NET Framework app, so I can enable communication between my app and a database.
16
17
---
17
18
18
19
# Create and configure TableAdapters in .NET Framework applications
TableAdapters provide communication between your application and a database. They connect to the database, run queries or stored procedures, and either return a new data table or fill an existing <xref:System.Data.DataTable> with the returned data. TableAdapters can also send updated data from your application back to the database.
23
+
**TableAdapters** enable communication between your application and a database. They connect to the database, run queries or stored procedures, and either return a new data table or fill an existing <xref:System.Data.DataTable> class instance with the returned data. TableAdapters can also send updated data from your application back to the database.
23
24
24
-
TableAdapters are created for you when you perform one of the following actions:
25
+
TableAdapters are created when you perform one of the following actions:
25
26
26
27
- Drag database objects from **Server Explorer** into the **Dataset Designer**.
28
+
- Drag the `TableAdapter` object from the **Toolbox** to an empty region in the **Dataset Designer** surface, and then configure the data source.
29
+
- Run the **Data Source Configuration Wizard**, and select the **Database** or **Web Service** data source type:
27
30
28
-
- Run the Data Source Configuration Wizard, and select either the **Database** or **Web Service**data source type.
31
+
:::image type="content" source="./media/data-source-configuration-wizard.png" border="false" alt-text="Screenshot that shows how to select the data source type in the Data Source Configuration Wizard in Visual Studio.":::
29
32
30
-
33
+
For an introduction to TableAdapters, see [Fill datasets by using TableAdapters](fill-datasets-by-using-tableadapters.md).
31
34
32
-
You can also create a new TableAdapter and configure it with a data source by dragging a TableAdapter from the **Toolbox** to an empty region in the **Dataset Designer** surface.
35
+
## Prerequisites
33
36
34
-
For an introduction to TableAdapters, see [Fill datasets by using TableAdapters](../data-tools/fill-datasets-by-using-tableadapters.md).
37
+
To complete the procedures in this article, the following prerequisites must be satisfied:
Run the **TableAdapter Configuration Wizard** to create or edit TableAdapters and their associated DataTables. You can configure an existing TableAdapter by right-clicking on it in the **Dataset Designer**.
43
+
## Access the TableAdapter Configuration Wizard
41
44
42
-
45
+
You can use the **TableAdapter Configuration Wizard** to create new TableAdapters or edit existing instances, and configure their associated data tables.
43
46
44
-
If you drag a new TableAdapter from the Toolbox when the **Dataset Designer**is in focus, the wizard starts and prompts you to specify which data source the TableAdapter should connect to. On the next page, the wizard asks what kind of commands it should use to communicate with the database, either SQL statements or stored procedures. (You don't see this screen if you're configuring a TableAdapter that is already associated with a data source.)
47
+
- To configure an existing TableAdapter with the wizard, right-click the TableAdapter instance in the **Dataset Designer** and select **Configure**:
45
48
46
-
- You have the option to create a new stored procedure in the underlying database if you have the correct permissions for the database. If you don't have these permissions, this option isn't available.
49
+
:::image type="content" source="./media/table-adapter-configuration-wizard.png" alt-text="Screenshot that shows how to access the Table Adapter Configuration Wizard in Visual Studio." lightbox="./media/table-adapter-configuration-wizard.png":::
47
50
48
-
-You can also choose to run existing stored procedures for the **SELECT**, **INSERT**, **UPDATE**, and **DELETE** commands of the TableAdapter. The stored procedure that's assigned to the **Update**command, for example, is run when the `TableAdapter.Update()` method is called.
51
+
-To create a new TableAdapter with the wizard, drag the `TableAdapter` object from the **Toolbox**to an empty region in the **Dataset Designer** surface.
49
52
50
-
Map parameters from the selected stored procedure to the corresponding columns in the data table. For example, if your stored procedure accepts a parameter named `@CompanyName` that it passes to the `CompanyName` column in the table, set the **Source Column** of the `@CompanyName` parameter to `CompanyName`.
53
+
## Use the wizard
51
54
52
-
> [!NOTE]
53
-
> The stored procedure that's assigned to the `SELECT` command is run by calling the method of the TableAdapter that you name in the next step of the wizard. The default method is `Fill`, so the code that's typically used to run the `SELECT` procedure is `TableAdapter.Fill(tableName)`. If you change the default name from `Fill`, substitute `Fill` with the name you assign, and replace "TableAdapter" with the actual name of the TableAdapter (for example, `CustomersTableAdapter`).
55
+
For TableAdapter configuration, the **TableAdapter Configuration Wizard** guides you through the following tasks:
54
56
55
-
- Selecting the **Create methods to send updates directly to the database** option is equivalent to setting the `GenerateDBDirectMethods` property to true. The option is unavailable when the original SQL statement doesn't provide enough information or the query isn't an updatable query. This situation can occur, for example, in **JOIN** queries and queries that return a single (scalar) value.
57
+
1. Configure required settings for the TableAdapter.
56
58
57
-
The **Advanced Options** in the wizard enable you to:
59
+
- Specify the data source type for the TableAdapter connection.
58
60
59
-
- Generate `INSERT`, `UPDATE`, and `DELETE` statements based on the `SELECT` statement that's defined on the **Generate SQL statements** page
60
-
- Use optimistic concurrency
61
-
- Specify whether to refresh the data table after `INSERT` and `UPDATE` statements are run
61
+
- Identify the commands to use for communication with the database, either SQL statements or stored procedures. If the TableAdapter is already associated with a data source, you don't see this option in the wizard.
62
62
63
-
## Configure a TableAdapter's Fill method
63
+
1. Create stored procedures, as needed.
64
64
65
-
Sometimes you might want to change the schema of the TableAdapter's table. To do this, you modify the TableAdapter's primary `Fill` method. TableAdapters are created with a primary `Fill` method that defines the schema of the associated data table. The primary `Fill` method is based on the query or stored procedure you entered when you originally configured the TableAdapter. It's the first (topmost) method under the data table in the DataSet Designer.
65
+
Create a new stored procedure in the underlying database, if you have the correct permissions for the database. If you don't have the necessary permissions, this option isn't available in the wizard.
66
66
67
-
67
+
1. Run existing stored procedures, as needed.
68
+
69
+
Procedures are available for the **SELECT**, **INSERT**, **UPDATE**, and **DELETE** commands of the TableAdapter. For example, the stored procedure assigned to the **UPDATE** command runs when you call the `TableAdapter.Update()` method.
70
+
71
+
1. Map parameters from the selected stored procedure to the corresponding columns in the data table. For example, if your stored procedure accepts a parameter named `@CompanyName` that it passes to the `CompanyName` column in the data table, set the **Source Column** of the `@CompanyName` parameter to `CompanyName`.
72
+
73
+
> [!NOTE]
74
+
> For the **SELECT** command, the stored procedure runs when you call the TableAdapter `Fill` method, by default. You [specify a name for the Fill() method](#configure-the-tableadapterfill-method) in the subsequent page in the wizard. When you use the default method, the typical code to run the stored procedure for the **SELECT** command is `TableAdapter.Fill(<TableName>)`. You replace the `<TableName>` portion with the name of the data table.
75
+
>
76
+
> If you change the default method name from `Fill`, you need to update the code for the procedure. Replace `Fill` with the new method name and use the actual name of the TableAdapter. For example, for a TableAdapter named `CustomersTableAdapter` and a data table named `CustomersTable`, if you change the `Fill` method name to `AddData`, update the code to `CustomersTableAdapter.AddData(CustomersTable)`.
77
+
78
+
- Choose whether to enable the **Create methods to send updates directly to the database** option. When this option is enabled, it's equivalent to setting the `GenerateDBDirectMethods` property to true. The option isn't available when the original SQL statement doesn't provide enough information or the query isn't an updatable query. For example, when **JOIN** queries and other queries return a single (scalar) value.
79
+
80
+
1. Configure your preferences for the **Advanced Options**.
81
+
82
+
- Generate **INSERT**, **UPDATE**, and **DELETE** commands based on the **SELECT** command defined on the **Generate SQL statements** page.
83
+
84
+
- Use optimistic concurrency.
85
+
86
+
- Refresh the data table after **INSERT** and **UPDATE** commands run.
87
+
88
+
## Configure the TableAdapter.Fill() method
89
+
90
+
In some scenarios, you might want to change the schema of the TableAdapter's data table. To complete the action, you modify the TableAdapter's primary `Fill` method. TableAdapters are created with a primary `Fill` method that defines the schema of the associated data table. The primary `Fill` method is based on the query or stored procedure you entered when you originally configured the TableAdapter. It's the first (topmost) method under the data table in the **Dataset Designer**.
91
+
92
+
:::image type="content" source="../data-tools/media/tableadapter.gif" border="false" alt-text="Diagram that illustrates how to use a TableAdapter with multiple queries.":::
68
93
69
94
Any changes that you make to the TableAdapter's main `Fill` method are reflected in the schema of the associated data table. For example, removing a column from the query in the main `Fill` method also removes the column from the associated data table. Additionally, removing the column from the main `Fill` method removes the column from any additional queries for that TableAdapter.
70
95
71
-
You can use the TableAdapter Query Configuration Wizard to create and edit additional queries for the TableAdapter. These additional queries must conform to the table schema, unless they return a scalar value. Each additional query has a name that you specify.
96
+
You can use the **TableAdapter Query Configuration Wizard** to create and edit additional queries for the TableAdapter. These additional queries must conform to the table schema, unless they return a scalar value. Each additional query has a name that you specify.
72
97
73
-
The following example shows you how to call an additional query named `FillByCity`:
98
+
The following example shows how to call an additional query named `FillByCity`:
### To start the TableAdapter Query Configuration Wizard with a new query
104
+
## Create a query with the wizard
105
+
106
+
You can create a new query with the **TableAdapter Query Configuration Wizard** by following these steps:
78
107
79
108
1. Open your dataset in the **Dataset Designer**.
80
109
81
-
2. If you're creating a new query, drag a **Query** object from the **DataSet** tab of the **Toolbox** onto a <xref:System.Data.DataTable>, or select **Add Query** from the TableAdapter's shortcut menu. You can also drag a **Query** object onto an empty area of the **Dataset Designer**, which creates a TableAdapter without an associated <xref:System.Data.DataTable>. These queries can only return single (scalar) values, or run `UPDATE`, `INSERT`, or `DELETE` commands against the database.
110
+
1. Create a new query with one of the following actions:
111
+
112
+
- In the **Dataset Designer**, right-click the TableAdapter and select **Add Query**.
113
+
- Drag the `Query` object from the **DataSet** tab of the **Toolbox** onto a <xref:System.Data.DataTable> in the **Dataset Designer** surface.
114
+
- Drag the `Query` object from the **Toolbox** to an empty region in the **Dataset Designer** surface, which creates a TableAdapter without an associated <xref:System.Data.DataTable>.
115
+
116
+
These queries can return single (scalar) values only, or run **UPDATE**, **INSERT**, or **DELETE** commands against the database.
117
+
118
+
1. On the **Choose Your Data Connection** screen, select an existing connection or create a new connection for the query.
82
119
83
-
3. On the **Choose Your Data Connection** screen, select, or create the connection that the query will use.
120
+
> [!NOTE]
121
+
> This screen appears only when the designer can't determine the connection to use, or when no connections are available.
84
122
85
-
> [!NOTE]
86
-
> This screen only appears when the designer can't determine the proper connection to use, or when no connections are available.
123
+
1. On the **Choose a Command Type** screen, configure the command by selecting from the following methods that fetch data from the database:
87
124
88
-
4. On the **Choose a Command Type** screen, select from the following methods of fetching data from the database:
125
+
-**Use SQL statements**: You enter a SQL statement to select the data from your database.
89
126
90
-
-**Use SQL statements** enables you to type a SQL statement to select the data from your database.
127
+
-**Create new stored procedure**: The wizard creates a new stored procedure (in the database) based on the specified **SELECT** command.
128
+
129
+
-**Use existing stored procedures**: You execute an existing stored procedure when you run the query.
91
130
92
-
-**Create new stored procedure** enables you to have the wizard create a new stored procedure (in the database) based on the specified `SELECT` statement.
131
+
## Configure a query with the wizard
93
132
94
-
-**Use existing stored procedures** enables you to run an existing stored procedure when running the query.
133
+
To edit an existing TableAdapter query with the **TableAdapter Query Configuration Wizard**, right-click the query, and select **Configure**. The right-click action produces a different result depending on which type of query you select:
95
134
96
-
### To start the TableAdapter Query Configuration wizard on an existing query
135
+
- For the main query of a TableAdapter, both the TableAdapter and the <xref:System.Data.DataTable> schema are reconfigured.
97
136
98
-
-If you're editing an existing TableAdapter query, right-click the query, and then choose **Configure** from the shortcut menu.
137
+
-On an additional query on a TableAdapter, only the selected query is reconfigured.
99
138
100
-
> [!NOTE]
101
-
> Right-clicking the main query of a TableAdapter reconfigures the TableAdapter and <xref:System.Data.DataTable> schema. Right-clicking an additional query on a TableAdapter, however, configures the selected query only. The **TableAdapter Configuration Wizard** reconfigures the TableAdapter definition, while the **TableAdapter Query Configuration Wizard** reconfigures the selected query only.
139
+
The **TableAdapter Configuration Wizard** reconfigures the TableAdapter definition, while the **TableAdapter Query Configuration Wizard** reconfigures only the selected query.
102
140
103
-
### To add a global query to a TableAdapter
141
+
##Add a global query to a TableAdapter
104
142
105
-
-Global queries are SQL queries that return either a single (scalar) value or no value. Typically, global functions perform database operations such as inserts, updates, and deletes. They also aggregate information, such as a count of customers in a table or the total charges for all items in a particular order.
143
+
Global queries are SQL queries that return either a single (scalar) value or no value. Typically, global functions perform database operations like inserts, updates, and deletes. They also aggregate information, such as a count of customers in a table or the total charges for all items in a particular order.
106
144
107
-
You add global queries by dragging a **Query** object from the **DataSet** tab of the **Toolbox**onto an empty area of the **Dataset Designer**.
145
+
1. Add a global query by dragging the `Query` object from the **DataSet** tab of the **Toolbox**to an empty region in the **Dataset Designer** surface.
108
146
109
-
- Provide a query that performs the desired task, for example,`SELECT COUNT(*) AS CustomerCount FROM Customers`.
147
+
1. Enter a query that performs a specific task, such as`SELECT COUNT(*) AS CustomerCount FROM Customers`.
110
148
111
-
> [!NOTE]
112
-
> Dragging a **Query** object directly onto the **Dataset Designer** creates a method that returns only a scalar (single) value. While the query or stored procedure you select might return more than a single value, the method that's created by the wizard only returns a single value. For example, the query might return the first column of the first row of the returned data.
149
+
> [!NOTE]
150
+
> Dragging a `Query` object directly onto the **Dataset Designer** surface creates a method that returns a scalar (single) value only.
151
+
> While the query or stored procedure you select might return more than a single value, the method created by the wizard returns a single value only. For example, the query might return the first column of the first row of the returned data.
113
152
114
153
## Related content
115
154
116
155
-[Fill datasets by using TableAdapters](../data-tools/fill-datasets-by-using-tableadapters.md)
0 commit comments