DashboardViewer.ConfigureDataConnection Event

Allows you to customize connection settings before the DashboardViewer connects to a data store (database, OLAP cube, etc.).

Namespace: DevExpress.DashboardWin

Assembly: DevExpress.Dashboard.v18.2.Win.dll

Declaration

public event DashboardConfigureDataConnectionEventHandler ConfigureDataConnection
Public Event ConfigureDataConnection As DashboardConfigureDataConnectionEventHandler
Property Description
DataSourceName

Gets the data source name for which the event was raised.

The ConfigureDataConnection event is raised before the connection to a data store is established and allows you to customize connection settings.

To specify connection parameters, you have to cast an object returned by the e.ConnectionParameters property to a proper type, depending on the data source type, as the following table illustrates.

Data Source

Parameter Type

Custom Data Source

To specify a custom connection string, cast an object to the CustomStringConnectionParameters class and assign a custom connection string to the ConnectionString property.

Tip

You can use a custom connection string to get data from an xml file containing valid schema. The string looks as follows: "xpoprovider=InMemoryDataStore;data source=""your_data_file.xml"";read only=True"

SQL Data Source

The base type is the SqlServerConnectionParametersBase class which defines the basic connection parameters: DatabaseName, Password, ServerName and UserName. To specify other data provider parameters, cast an object to any of the following types:

OLAP Data Source

To specify the OLAP connection string, cast an object to the OlapConnectionParameters type and use the ConnectionString property.

Excel Data Source

To specfy a path to a Microsoft Excel workbook/CSV file, cast an object to the ExcelDataSourceConnectionParameters type and use the FileName and Password properties.

Extract Data Source

To specfy a path to a data extract file and a data driver to access the data, cast an object to the ExtractDataSourceConnectionParameters type and use the FileName and DriverName properties.

Entity Framework Data Source

Event does not occur.

Object Data Source

Event does not occur.

Handle the DataLoading event instead.

This event is raised when the dashboard is supplied with data using one of the following data source types:

Note

If the dashboard is supplied with data using the DashboardObjectDataSource data source, the DashboardViewer.DataLoading event is fired instead.

Examples

This example demonstrates how to customize connection settings before the DashboardViewer connects to a database using the DashboardViewer.ConfigureDataConnection event.

In this example, the dashboard's XML definition contains a path to the secured Microsoft Access database. To visualize data from this database file, it is necessary to provide connection parameters; in particular, a user name and password for authentication. The DashboardViewer.ConfigureDataConnection event is used for this purpose. Its Access97ConnectionParameters.UserName and FileConnectionParametersBase.Password parameters are used to provide the user name and password respectively.

using DevExpress.DataAccess.ConnectionParameters;
using DevExpress.DashboardCommon;
using DevExpress.XtraEditors;

namespace Dashboard_ConfigureDataConnection {
    public partial class Form1 : XtraForm {
        public Form1() {
            InitializeComponent();

            // Loads a dashboard from an XML file.
            dashboardViewer1.LoadDashboard(@"..\..\Data\nwindDashboard.xml");
        }

        // Handles the ConfigureDataConnection event.
        private void dashboardViewer1_ConfigureDataConnection(object sender, 
            DashboardConfigureDataConnectionEventArgs e) {

            // Checks the name of the connection for which the event has been raised.
            if (e.DataSourceName == "SQL Data Source 1") {

                // Gets the connection parameters used to establish a connection to the database.
                Access97ConnectionParameters parameters = 
                    (Access97ConnectionParameters)e.ConnectionParameters;

                // Specifies the user name used to access the database file. 
                parameters.UserName = "Admin";

                // Specifies the password used to access the database file.
                parameters.Password = "password";
            }
        }
    }
}

See Also