Binding the Windows Forms DataGrid Control to a Data Source

Visual Studio .NET 2003

The Windows Forms DataGrid control is specifically designed to display information from a data source. You bind the control at design time by setting the DataSource and DataMember properties, or at run time by calling the SetDataBinding method. Although you can display data from a variety of data sources, the most typical sources are datasets and data views.

You can also bind a DataGrid control to additional structures if the objects in the structure — for example, the elements in an array — expose public properties. The grid will display all the public properties of the elements in the structure. For example, if you bind the DataGrid control to an array of customer objects, the grid will display all the public properties of those customer objects. In some instances, this means that although you can bind to the structure, it might not have practical application. For instance, you can bind to an array of integers, but because the Integer data type does not support a public property, the grid cannot display any data.

You can bind to the following structures if their elements expose public properties:

Any component that implements the IList interface. This includes single-dimension arrays.

Grid Display

A common use of the DataGrid control is to display a single table of data from a dataset. However, the control can also be used to display multiple tables, including related tables. The display of the grid is adjusted automatically according to the data source:

Single table. The table is displayed in a grid.

Multiple tables. The grid can display a tree view that users can navigate to locate the table they want to display.

Multiple related tables. The grid can display a tree view to select tables with, or you can specify that the grid display the parent table. Records in the parent table allow users to navigate to related child rows. Further discussion of how the grid displays related tables can be found in the "Binding Data to the Control" subsection of Introduction to the Windows Forms DataGrid Control.

Binding the Grid

If the data source is available at design time — for example, if the form contains an instance of a dataset or a data view — you can bind the grid to the data source at design time. You can then preview what the data will look like in the grid.

You can also bind the grid programmatically, at run time. This is useful in situations when you want to set a data source based on information you get at run time. For example, the application might allow the user to specify the name of a table to view. It is also necessary in situations where the data source does not exist at design time. This includes data sources such as arrays, collections, untyped datasets, and data readers.

To data-bind the DataGrid control to a single table in the designer

Set the control's DataSource property to the object containing the data items you want to bind to.

If the data source is a dataset, set the DataMember property to the name of the table to bind to.

If the data source is a dataset or a data view based on a dataset table, add code to the form to fill the dataset.

The exact code you use depends on where the dataset is getting data. If the dataset is being populated directly from a database, you typically call the Fill method of a data adapter, as in the following example, which populates a dataset called DsCategories1:

If the dataset is being filled from an XML Web service, you typically create an instance of the service in your code and then call one of its methods to return a dataset. You then merge the dataset from the XML Web service into your local dataset. The following example shows how you can create an instance of an XML Web service called CategoriesService, call its GetCategories method, and merge the resulting dataset into a local dataset called DsCategories1:

(Optional) Add the appropriate table styles and column styles to the grid. If there are no table styles, you will see the table, but with minimal formatting and with all columns visible.

To data-bind the DataGrid control to multiple tables in a dataset in the designer

Set the control's DataSource property to the object containing the data items you want to bind to.

If the dataset contains related tables (that is, if it contains a relation object), set the DataMember property to the name of the parent table.

Write code to fill the dataset.

To data-bind the DataGrid control programmatically

Write code to fill the dataset. For details, see Step 3 of the procedure "To data-bind the DataGrid control to a single table in the designer" above.

Call the DataGrid control's SetDataBinding method, passing it the data source and a data member. If you do not need to explicitly pass a data member, pass an empty string.

Note If you are binding the grid for the first time, you can set the control's DataSource and DataMember properties. However, you cannot reset these properties once they have been set. Therefore, it is recommended that you always use the SetDataBinding method.

The following example shows how you can programmatically bind to the Customers table in a dataset called DsCustomers1: