Microsoft KB Archive/313482

= Roadmap for Windows Forms data binding =

Article ID: 313482

Article Last Modified on 5/17/2007

-

APPLIES TO


 * Microsoft .NET Framework 1.1 Service Pack 1
 * Microsoft ADO.NET 1.1
 * Microsoft .NET Framework Software Development Kit 1.0
 * Microsoft .NET Framework Software Development Kit 1.0 Service Pack 2

-



This article was previously published under Q313482



CONTENTS
SUMMARY Overview Architecture QuickStart Samples, Walkthroughs, and Microsoft Knowledge Base Articles
 * Binding to a DataView or a DataViewManager
 * Binding to an Object or a List of Objects
 * Custom Binding

Troubleshooting



SUMMARY
This article provides a roadmap to learn and to master data binding in Windows Forms applications. Roadmap articles provide links to useful information, including online documentation, Microsoft Knowledge Base articles, and Microsoft white papers, to help you learn about a Microsoft product or technology.

For additional information about ADO.NET objects, click the article number below to view the article in the Microsoft Knowledge Base:

313590 INFO: Roadmap for ADO.NET

back to the top

Overview
The Windows Forms object model provides a robust data binding infrastructure that you can use to write both data providers and data consumers. The Windows Forms object model supports both reflection-based data binding and interface-based data binding of data providers. Additionally, the Windows Forms object model supports a number of interfaces to extend existing control behavior and to add various binding behaviors to custom classes.

Windows Forms can bind to the public properties of a class or to any class that supports the IList interface, such as the DataView, the Array, the ArrayList, and the Collection classes. Unlike ASP.NET Web Forms, the Windows Forms object model does not support binding to the DataReader object or the IEnumerable interface because backward scrolling support is required when you bind to anything other than a simple object.

back to the top

Architecture
The Windows Forms object model supports two different binding managers:
 * PropertyManager
 * CurrencyManager

You can use the PropertyManager class to bind simple controls to public properties of a class. However, you cannot use the PropertyManager to bind a complex control, such as a ListBox control, a ComboBox control, or a DataGrid control.

You can use the CurrencyManager class to bind simple or complex controls to an object that supports the IList interface, such as the DataView, the Array, the ArrayList, and the Collection objects.

With a custom class that supports the IBindingList interface, you can sort the list or add and delete items in the list. The controls are bound to the public properties of the object that is returned by the list. This object can support the ICustomTypeDescriptor interface to bind to an indexed property instead of public properties. Additionally, this object can support the IEditableObject interface to provide change support that you can access through the BeginEdit, the EndEdit, and the CancelEdit methods.

Unlike binding to an ADO Recordset object, the IList interface does not keep track of the &quot;current&quot; record. As a result, the IList interface does not include the MoveFirst, the MoveNext, the MovePrevious, and the MoveLast methods. Instead, the CurrencyManager maintains the currency through the Position property, and you can increment and decrement this property to move through records.

If you want to be notified of user navigation, make sure that your application hooks the PositionChanged event of the CurrencyManager. Additionally, if you want to be notified of any user changes (such as additions, deletions, or sorting), make sure that your application hooks the ListChanged event of the IBindingList interface (which the DataView object implements).

In general, do not use the user interface to change data programmatically. Instead, use the bound object (which is typically DataView) to change data.

You can use the Microsoft Visual Studio .NET integrated development environment (IDE) to bind controls at design time to any class that supports the IComponent interface. You can also bind at run time. The act of binding takes two arguments: an object and a property.

The following code binds a TextBox control and a DataGrid control to the same CurrencyManager and DataView: TextBox1.DataBindings.Add(&quot;Text&quot;, ds, &quot;Customers.CustomerID&quot;) DataGrid1.DataSource = ds DataGrid1.DataMember = &quot;Customers&quot; Alternatively, you can use the following code to bind to different CurrencyManager and DataView objects: TextBox1.DataBindings.Add(&quot;Text&quot;, ds.Tables(&quot;Customers&quot;), &quot;CustomerID&quot;) DataGrid1.DataSource = ds.Tables(&quot;Customers&quot;) Each of the preceding code samples displays the same data. Edits and scrolling are not synchronized between examples but are synchronized in them.

You can also traverse DataRelation objects in data binding syntax. In the following code, the second DataGrid uses the CustOrd DataRelation to display the Orders records for the current Customers record that is selected in the first DataGrid: DataGrid1.DataSource = ds DataGrid1.DataMember = &quot;Customers&quot; DataGrid2.DataSource = ds DataGrid2.DataSource = &quot;Customers.CustOrd&quot; To retrieve the underlying CurrencyManager or PropertyManager, use the BindingContext property of the form. This returns the appropriate manager that is cast as the BindingManagerBase base class interface, which you can cast to the appropriate derived class: cm = CType(Me.BindingContext(ds, &quot;Customers&quot;), CurrencyManager) From the CurrencyManager, you can get the underlying bound collection from the List property. If you know the derived type, you can cast the object that is returned to the appropriate derived class: dv = CType(cm.List, DataView)   ' Okay if cm is bound to a DataView. al = CType(cm.List, ArrayList)  ' Okay if cm is bound to an ArrayList. From the PropertyManager, you can get the underlying bound object from the Current property: MyObject = CType(pm.Current, MyClass) When binding to a DataSet and editing bound controls, the bound controls modify the proposed version of the current DataRow. For these changes to be visible, you must commit the proposed version through the CurrencyManager.EndCurrentEdit method. The changes can also be rolled back through the CurrencyManager.CancelCurrentEdit method. This is particularly important when updating through a DataAdapter because any proposed changes that are not committed will not be processed. This also applies to any bound class that supports the IEditableObject interface.

For more information about Windows Forms data binding, see the following topics in the Microsoft Visual Studio .NET Help documentation: Visual Studio .NET Visual Basic and Visual C# Creating Applications Creating Windows Applications Windows Forms Windows Forms Data Architecture
 * Data Binding and Windows Forms
 * Creating a Simple-Bound Control on a Windows Form
 * Providers of Data to Windows Forms
 * Consumers of Data on Windows Forms
 * Navigating Data in Windows Forms
 * Interfaces Related to Data Binding

Binding Class

http://msdn2.microsoft.com/en-us/library/system.windows.forms.binding(vs.71).aspx

BindingContext Class

http://msdn2.microsoft.com/en-us/library/system.windows.forms.bindingcontext(vs.71).aspx

back to the top

QuickStart Samples, Walkthroughs, and Microsoft Knowledge Base Articles
QuickStart sample files provide code samples for your reference. Walkthroughs provide mini-tutorials that walk you through typical application development scenarios. Microsoft Knowledge Base &quot;How To&quot; articles provide step-by-step instructions about how to accomplish specific tasks.

The Visual Studio .NET Help documentation, QuickStart sample files, walkthroughs, and Microsoft Knowledge Base articles in the sections to follow describe how to use Windows Forms data binding.

QuickStart Samples

QuickStart sample files are installed on your computer in one of two locations. If you install the QuickStart sample files as part of Visual Studio .NET, the sample files are located in the following folder:

C:\Program Files\Microsoft Visual Studio .NET\FrameworkSDK\Samples\QuickStart\...

If you install the QuickStart sample files as part of the Microsoft .NET Framework, the sample files are located in the following folder:

C:\Program Files\FrameworkSDK\Samples\QuickStart\...

Walkthroughs

To access walkthroughs, click Index on the Help menu in Visual Studio .NET. In the Look For text box, type Walkthroughs, Windows Forms. A list of data access walkthroughs appears in the index results pane.

Microsoft Knowledge Base Articles

Click here to view a list of How To articles about Windows Forms data binding

back to the top

Binding to a DataView or a DataViewManager
The class that is most commonly bound is the DataView class. Any binding to a DataSet, a DataTable, or a DataViewManager object derives from binding to a DataView class that the other classes provide. If you want to synchronize all of your controls to the same DataView, you must either bind them all to the same DataView object, or you must use compatible binding syntax so that the same DataView object is generated from the DataSource object.

When you bind to a DataViewManager object, you can set filters on multiple DataTable objects in the DataSet simultaneously. When you navigate hierarchically, the DataViewManager generates a DataView object with the appropriate filter for each level in the hierarchy.

Walkthroughs

Walkthrough: Simple Data Access in a Windows Form

http://msdn2.microsoft.com/en-us/library/aa984466(VS.71).aspx

Walkthrough: Displaying Data in a Windows Form Using a Parameterized Query

http://msdn2.microsoft.com/en-us/library/aa984467(VS.71).aspx

Walkthrough: Creating a Master-Detail Windows Form

http://msdn2.microsoft.com/en-us/library/aa984462(VS.71).aspx

Data Binding with Windows Forms and .NET

http://msdn2.microsoft.com/en-us/library/ms973824.aspx

QuickStart Samples

Databinding in Windows Forms

http://samples.gotdotnet.com/quickstart/winforms/doc/winformsdata.aspx

If you installed the QuickStart samples on your computer, the following subfolders contain additional samples:
 * ...\Samples\QuickStart\Winforms\Samples\Data\Comboboxbinding

The sample in this subfolder binds a Windows Forms ComboBox control to an array of a custom class, binds a TextBox control to a typed DataSet, and then uses navigation buttons.
 * ...\Samples\QuickStart\Winforms\Samples\Data\Grid

The sample in this subfolder uses the Visual Design tools to bind a Windows Forms DataGrid control to a typed DataSet and then uses a SqlDataAdapter object to fill the DataSet.
 * ...\Samples\QuickStart\Winforms\Samples\Data\Masterdetails

The sample in this subfolder includes a Web service that exposes methods to return and uses a DataSet to update master/detail tables. This sample includes a client application that reads a DataSet from the Web service and then calls the Web service to process both parent and client changes. The client application binds the typed DataSet to a DataGrid.

NOTE: This sample does not handle all update scenarios. In some update scenarios, you may receive an error message, and the updates may get rolled back.
 * ...\Samples\QuickStart\Winforms\Samples\Data\Simplebinding

The sample in this subfolder binds a TextBox to a DataTable field and implements custom formatting and parsing events.
 * ...\Samples\QuickStart\Winforms\Samples\Data\Update

The sample in this subfolder includes a Web service that returns a single DataTable through a DataSet and processes updates that the client makes. This sample includes a client application that binds the DataTable to a TextBox with navigation buttons and binds a ComboBox control to an array of custom objects.
 * ...\Samples\QuickStart\Winforms\Samples\Data\Webservicebinding

The sample in this subfolder includes a Web service that returns a single DataTable through a DataSet. This sample does not include any update logic. The client application binds the DataTable to a Windows Forms DataGrid control.

Visual Studio .NET Help Documentation

Navigating Data in Windows Forms

http://msdn2.microsoft.com/en-us/library/aa983596(VS.71).aspx

Microsoft Knowledge Base Articles

317041 HOW TO: Retrieve DataView of a Windows Forms Bound Control in Visual Basic .NET

317164 HOW TO: Retrieve DataView of a Windows Forms Bound Control in Visual C# .NET

308070 HOW TO: Implement a Searchable DataGrid by Using ADO.NET and Windows Forms

317951 HOW TO: Hide a Column in a Windows Form DataGrid

308484 HOW TO: Display Parent and Child Records in a Windows Forms DataGrid by Using Visual C# .NET

308052 HOW TO: Display Parent and Child Records in a Windows Forms DataGrid by Using Visual Basic .NET

308454 HOW TO: Display Parent and Child Fields Together in a DataGrid by Using Visual C# .NET

308057 HOW TO: Display Parent and Child Fields Together in a Windows Forms DataGrid by Using Visual Basic .NET

307710 HOW TO: Custom Page a DataGrid Windows Control by Using Visual C# .NET

305271 HOW TO: Custom Page a DataGrid Windows Control by Using Visual Basic .NET

back to the top

Binding to an Object or a List of Objects
When you bind to a simple class (that is, a class that does not support the IList or the ICustomTypeDescriptor interface), the binding manager uses reflection to determine the public properties of the class and to allow binding to those properties.

You cannot bind a DataGrid or the list portion of a ComboBox or a ListBox to an object that does not support the IList interface. If you bind a DataGrid to a list, and if the object that the list returns does not support ICustomTypeDescriptor, the DataGrid binds a column to each public property of the class.

When you edit data in a bound control, the corresponding property of the bound object is updated immediately, unless the object implements the IEditableObject interface. If you change the property of the underlying object programmatically, the bound control is not notified of the changes unless the list object supports the IBindingList interface.

QuickStart Samples

Databinding in Windows Forms

http://samples.gotdotnet.com/quickstart/winforms/doc/winformsdata.aspx

If you installed the QuickStart samples on your computer, the following subfolders contain additional samples:
 * ...\Samples\QuickStart\Winforms\Samples\Data\Comboboxbinding

The sample in this subfolder binds a Windows Forms ComboBox to an array of a custom class, binds a TextBox to a typed DataSet, and then uses navigation buttons.
 * ...\Samples\QuickStart\Winforms\Samples\Data\Simplebinding

The sample in this subfolder binds a TextBox to a DataTable field and implements custom formatting and parsing events.
 * ...\Samples\QuickStart\Winforms\Samples\Data\Update

The sample in this subfolder includes a Web service that returns a single DataTable through a DataSet and processes updates that the client makes. This sample includes a client application that binds the DataTable to a TextBox with navigation buttons and binds a ComboBox list to an array of custom objects.

Microsoft Knowledge Base Articles

313334 HOW TO: Bind an Array of Structures to a Windows Form by Using Visual Basic .NET

317550 HOW TO: Use Visual C# .NET to Format a Windows Forms DataGrid That Is Bound to an Array

317383 HOW TO: Use Visual Basic .NET to Format a Windows Forms DataGrid That Is Bound to an Array

313636 HOW TO: Bind an ArrayList of Structures to a Windows Form by Using Visual C# .NET

313640 HOW TO: Bind an ArrayList or Collection of Objects to a Windows Form by Using Visual Basic .NET

313634 HOW TO: Bind an ArrayList of Objects to a Windows Form by Using Visual C# .NET

313335 HOW TO: Bind an Array of Structures to a Windows Form by Using Visual C# .NET

313639 HOW TO: Bind an Array of Objects to a Windows Form by Using Visual Basic .NET

313638 HOW TO: Bind an ArrayList or Collection of Structures to a Windows Form by Using Visual Basic .NET

313635 HOW TO: Bind an Array of Objects to a Windows Form by Using Visual C# .NET

316303 HOW TO: Bind a DataGrid Control to an ArrayList of Objects or Structures by Using Visual C# .NET

316302 HOW TO: Bind a DataGrid Control to an ArrayList of Objects or Structures by Using Visual Basic .NET

315786 HOW TO: Bind a DataGrid Control to an Array of Objects or Structures by Using Visual C# .NET

315784 HOW TO: Bind a DataGrid Control to an Array of Objects or Structures by Using Visual Basic .NET

back to the top

Custom Binding
You can hook the Windows Forms framework to give your custom classes additional binding behaviors and to change the binding behavior of Windows Forms controls.

Visual Studio .NET Help Documentation

Windows Forms Data Architecture

http://msdn2.microsoft.com/en-us/library/aa984214(VS.71).aspx

Interfaces Related to Data Binding

http://msdn2.microsoft.com/en-us/library/aa983621(VS.71).aspx

Microsoft Knowledge Base Articles

306227 HOW TO: Use a CheckBox Web Control in a DataGrid in Visual Studio .NET

318581 HOW TO: Extend the Windows Form DataGridTextBoxColumn Control to Custom-Format Data

319082 HOW TO: Extend the Windows Form DataGridTextBoxColumn to Display Data From Other Tables by Using Visual Basic .NET

325682 HOW TO: Implement a Custom DataView Class in Visual Basic .NET

back to the top

Troubleshooting
If you experience problems, or if you have questions, you can refer to the MSDN newsgroups where you can share your experiences with your peers. You can also use the Microsoft Knowledge Base to search for articles about specific issues.

MSDN Newsgroups

http://msdn.microsoft.com/newsgroups/

Searching the Knowledge Base

http://support.microsoft.com/search/?adv=1

back to the top

Additional query words: databinding

Keywords: kbarttyperoadmap kbdatabinding kbinfo kbsystemdata KB313482

-

[mailto:TECHNET@MICROSOFT.COM Send feedback to Microsoft]

© Microsoft Corporation. All rights reserved.