Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Binding the Windows Forms DataGrid Control to a Data Source

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.

Data Sources for the DataGrid Control

Valid data sources for the DataGrid include:

If your source is a dataset, it might be an object in the form or an object passed to the form by an XML Web service. You can bind to either typed or untyped datasets. For details on adding datasets to a form, see Visual Studio Tools for Creating Datasets. For details about accessing datasets using an XML Web service, see Introduction to Distributed Applications and Data Integration.

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.
  • Any component that implements the IListSource interface.
  • Any component that implements the IBindingList interface.

For details about possible data sources, see Providers of Data to Windows Forms.

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.
    Note   Tables in a dataset are related using a DataRelation object. For details, see Relationships in ADO.NET Datasets.

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

  1. Set the control's DataSource property to the object containing the data items you want to bind to.
  2. If the data source is a dataset, set the DataMember property to the name of the table to bind to.
  3. 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:

    ' Visual Basic
    sqlDataAdapter1.Fill(DsCategories1)
    
    // C#
    sqlDataAdapter1.Fill(DsCategories1);
    
    // C++
    sqlDataAdapter1->Fill(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:

    ' Visual Basic
    Dim ws As New MyProject.localhost.CategoriesService()
    ws.Credentials = System.Net.CredentialCache.DefaultCredentials
    DsCategories1.Merge(ws.GetCategories())
    
    // C#
    MyProject.localhost.CategoriesService ws = new MyProject.localhost.CategoriesService();
    ws.Credentials = System.Net.CredentialCache.DefaultCredentials;
    DsCategories1.Merge(ws.GetCategories());
    
    // C++
    MyProject::localhost::CategoriesService* ws = 
       new MyProject::localhost::CategoriesService();
    ws->Credentials = System::Net::CredentialCache::DefaultCredentials;
    dsCategories1->Merge(ws->GetCategories());
    

    For a more complete example of using an XML Web service in a Windows Form, see Walkthrough: Creating a Distributed Application. For more information on populating datasets, see the "Populating Datasets" subsection of Introduction to Datasets.

  4. (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

  1. Set the control's DataSource property to the object containing the data items you want to bind to.
  2. 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.
  3. Write code to fill the dataset.

To data-bind the DataGrid control programmatically

  1. 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.
  2. 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:

    ' Visual Basic
    DataGrid1.SetDataBinding(DsCustomers1, "Customers")
    
    // C#
    DataGrid1.SetDataBinding(DsCustomers1, "Customers");
    
    // C++
    dataGrid1->SetDataBinding(dsCustomers1, S"Customers");
    

    If the Customers table is the only table in the dataset, you could alternatively bind the grid this way:

    ' Visual Basic
    DataGrid1.SetDataBinding(DsCustomers1, "")
    
    // C#
    DataGrid1.SetDataBinding(DsCustomers1, "");
    
    // C++
    dataGrid1->SetDataBinding(dsCustomers1, S"");
    
  3. (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.

See Also

Introduction to the Windows Forms DataGrid Control | Adding Tables and Columns to the Windows Forms DataGrid Control | DataGrid Control (Windows Forms) | Walkthrough: Simple Data Access in a Windows Form | Walkthrough: Creating a Master-Detail Windows Form | Walkthrough: Creating a Distributed Application | Windows Forms Data Architecture | Accessing Data

Show:
© 2015 Microsoft