Register Default Data Connections

• Feb 27, 2023
• 3 minutes to read

This document describes how to provide a Web Dashboard with a set of data connections. These connections are available in the Dashboard Data Source Wizard when users create new data sources.

To create a data connection, add a connection string to the Web.config file or implement a custom data connection provider:

Add a Connection String to Web.config

A connection string should contain the XpoProvider parameter that depends on the database type:

<configuration>
    <connectionStrings>
        <add name="nwindConnection" connectionString="XpoProvider=MSSqlServer; data source=localhost; initial catalog=Northwind; integrated security=SSPI;" />
    </connectionStrings>
</configuration>

See Custom Connection Strings for Data Sources for information on how to specify a custom connection string.

The Web Dashboard control does not pass connection string names to the client. If users create a new data source in the Data Source Wizard, an exception occurs on an attempt to load connection strings. Pass the ConfigFileConnectionStringsProvider instance as the ASPxDashboard.SetConnectionStringsProvider or DashboardConfigurator.SetConnectionStringsProvider method’s parameter to allow users to create new data sources based on available connection strings from the Web.config file:

C#

DashboardConfigurator.SetConnectionStringsProvider(new DevExpress.DataAccess.Web.ConfigFileConnectionStringsProvider());

VB.NET

DashboardConfigurator.SetConnectionStringsProvider(New DevExpress.DataAccess.Web.ConfigFileConnectionStringsProvider())

The Dashboard Data Source Wizard can also display inherited connection strings (for instance, connection strings from machine.config). To remove strings from machine.config, add the clear element before the application’s connection strings:

<connectionStrings>
    <clear/>
    ...
</connectionStrings>

Create a Custom Data Connection Strings Provider

Use the ASPxDashboard.SetConnectionStringsProvider or DashboardConfigurator.SetConnectionStringsProvider method to specify a data connection provider - the type of method depends on the control’s server-side API.

A custom data connection strings provider allows you to add custom logic to your application. To use a custom connection provider, implement the IDataSourceWizardConnectionStringsProvider interface and pass the new provider to the SetConnectionStringsProvider method call.

This example shows how to implement a custom provider of connection strings by implementing the IDataSourceWizardConnectionStringsProvider interface.

C#

using DevExpress.DataAccess.ConnectionParameters;
using DevExpress.DataAccess.Web;

// ...

public class MyDataSourceWizardConnectionStringsProvider : IDataSourceWizardConnectionStringsProvider {
    public Dictionary<string, string> GetConnectionDescriptions() {
        Dictionary<string, string> connections = new Dictionary<string, string>();

        // Customize the loaded connections list.  
        connections.Add("jsonUrlConnection", "JSON URL Connection");
        connections.Add("msSqlConnection", "MS SQL Connection");
        return connections;
    }

    public DataConnectionParametersBase GetDataConnectionParameters(string name) {
        // Return custom connection parameters for the custom connection.
        if (name == "jsonUrlConnection") {
            return new JsonSourceConnectionParameters() { 
                JsonSource = new UriJsonSource(
                    new Uri("https://raw.githubusercontent.com/DevExpress-Examples/DataSources/master/JSON/customers.json")) 
                };
        } else if (name == "msSqlConnection") { 
            return new MsSqlConnectionParameters("localhost", "Northwind", "", "", MsSqlAuthorizationType.Windows);
        } 
        throw new System.Exception("The connection string is undefined.");
    }
}

VB.NET

Imports DevExpress.DataAccess.ConnectionParameters
Imports DevExpress.DataAccess.Web

' ...

Public Class MyDataSourceWizardConnectionStringsProvider
    Implements IDataSourceWizardConnectionStringsProvider
    Public Function GetConnectionDescriptions() As Dictionary(Of String, String)
        Dim connections As New Dictionary(Of String, String)()

        ' Customize the loaded connections list.  
        connections.Add("jsonUrlConnection", "JSON URL Connection")
        connections.Add("msSqlConnection", "MS SQL Connection")
        Return connections
    End Function

    Public Function GetDataConnectionParameters(ByVal name As String) As DataConnectionParametersBase
        ' Return custom connection parameters for the custom connection.
        If name = "jsonUrlConnection" Then
            Return New JsonSourceConnectionParameters() With {.JsonSource = New UriJsonSource(New Uri("https://raw.githubusercontent.com/DevExpress-Examples/DataSources/master/JSON/customers.json"))}
        ElseIf name = "msSqlConnection" Then
            Return New MsSqlConnectionParameters("localhost", "Northwind", "", "", MsSqlAuthorizationType.Windows)
        End If
        Throw New System.Exception("The connection string is undefined.")
    End Function
End Class

After you have implemented a custom provider of connection strings, pass the instance of this class to the ASPxDashboard.SetConnectionStringsProvider method.

C#

using DevExpress.DashboardWeb;
// ...
public partial class WebForm1 : System.Web.UI.Page {
    protected void Page_Load(object sender, EventArgs e) {
        // ...
        ASPxDashboard1.SetConnectionStringsProvider(new MyDataSourceWizardConnectionStringsProvider());
    }
    // ...
}

VB.NET

Imports DevExpress.DashboardWeb
' ...
Partial Public Class WebForm1
    Inherits System.Web.UI.Page
    Protected Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs)
        ' ...
        ASPxDashboard1.SetConnectionStringsProvider(New MyDataSourceWizardConnectionStringsProvider())
    ' ...
    End Sub
End Class