Use SqlDataSource

• Dec 17, 2021
• 3 minutes to read

The SqlDataSource component is a read-only source to access SQL databases. It supports multiple database engines, which are listed in the following help topic: Supported Data Providers.

Design Time Configuration

WinForms App - Visual Studio Designer

You can add the SQLDataSource component to your WinForms application in the Visual Studio Designer.

Add a Component

Locate the SqlDataSource component in the DX.24.1: Data & Analytics Toolbox section and drop it onto the form:

Set Up a Connection

After you add a component to the form, the Data Source Wizard is invoked automatically. Follow the Wizard pages to set up a connection.

Expand the SqlDataSource smart tag to adjust the data source settings:

The following commands are available:

Configure Connection

Invokes the Connection Editor Wizard. The command is equivalent to the SqlDataSourceUIHelper.ConfigureConnection method.

Manage Queries

Invokes the Query Builder that allows you to manage the collection of queries. The collection is accessible from the SqlDataSource.Queries property.

Manage Relations

This command is available when there are two or more queries in the collection. The command invokes the Master-Detail Relation Editor that allows you to specify data table relations:

Use the SqlDataSource.Relations property to access the relations.

Rebuild Result Schema

This command calls the SqlDataSource.RebuildResultSchema method, which updates the result schema on the client side after the query is executed. This command does not affect the actual database schema on the server. When an XtraReport is bound to SqlDataSource, call the RebuildResultSchema method to update the Field List in the Report Designer.

Request Database Schema

This command calls the SqlDataConnection.GetDBSchema method, which retrieves the database schema from the server.

Tip

Use the SqlDataSourceUIHelper class methods to invoke the dialogs that allow the user to configure conections, manage queries, and specify table relations. Ensure that your application references the DevExpress.DataAccess.v24.1.UI.dll assembly.

Retrieve Data

Call the Fill or FillAsync method to populate the data source. When the SqlDataSource is bound to the XtraReport descendant, this method call is not necessary, because the report populates the data source before document generation starts. However, if a data source does not support schema-only mode, the Fill/FillAsync call is required.

Runtime Configuration

To create the SqlDataSource component and configure it at runtime, do the following:

1. Create an instance of the SqlDataSource class.
2. Specify data connection with the ConnectionName and ConnectionParameters properties. For more information, review the following help topic: Specify Data Connection.
3. Populate the Queries collection. For more information, review the following help topic: Create SQL Queries.
4. Call the RebuildResultSchema method (the method recreates a set of fields that become available after a query / stored procedure is executed on the server).
5. Optional. Add table relationships to the SqlDataSource.Relations collection. Review the following help topic for more information: Manage Table Relations.
6. Assign the SqlDataSource instance to the data-bound control’s property (DataSource or related property).
7. Certain controls require that you call the Fill (FillAsync) method to populate the data source. DevExpress Reports populate the data source automatically before document generation.
8. The Result property contains data retrieved from the database. Use objects from the DevExpress.DataAccess.Sql.DataApi namespace to process the resulting data.

Related Topics

• WinForms Controls - Data Binding
• WinForms Controls - Binding to SQL Data
• Bind a Report to a Database
• Bind a Report to a Microsoft SQL Server Database at Runtime
• WinForms Dashboard - SQL Data Source
• Web Dashboard - SQL Data Source