System.Data.Common.DbConnectionStringBuilder Class

Provides a base class for strongly typed connection string builders.

See Also: DbConnectionStringBuilder Members


public class DbConnectionStringBuilder : IDictionary, System.ComponentModel.ICustomTypeDescriptor


The System.Data.Common.DbConnectionStringBuilder class provides the base class from which the strongly typed connection string builders (System.Data.SqlClient.SqlConnectionStringBuilder, System.Data.OleDb.OleDbConnectionStringBuilder, and so on) derive. The connection string builders let developers programmatically create syntactically correct connection strings, and parse and rebuild existing connection strings.

The System.Data.Common.DbConnectionStringBuilder has been defined in a database-agnostic manner. Because of the addition of the System.Data.Common namespace, developers require a base class against which they can program in order to build connection strings that can work against an arbitrary database. Therefore, the System.Data.Common.DbConnectionStringBuilder class lets users assign arbitrary key/value pairs and pass the resulting connection string to a strongly typed provider. All the data providers that are included as part of the .NET Framework provide a strongly typed class that inherits from System.Data.Common.DbConnectionStringBuilder: System.Data.SqlClient.SqlConnectionStringBuilder, System.Data.OracleClient.OracleConnectionStringBuilder, System.Data.Odbc.OdbcConnectionStringBuilder, and System.Data.OleDb.OleDbConnectionStringBuilder.

The developer can build, assign, and edit connection strings for any arbitrary provider. For providers that support specific key/value pairs, the connection string builder provides strongly typed properties corresponding to the known pairs. In order to support providers that require the ability to support unknown values, developers can also supply arbitrary key/value pairs.

The System.Data.Common.DbConnectionStringBuilder class implements the System.ComponentModel.ICustomTypeDescriptor interface. This means that the class works with Visual Studio designers at design time. When developers use the designer to build strongly typed DataSets and strongly typed connections within Visual Studio, the strongly typed connection string builder class will display the properties associated with its type and will also have converters that can map common values for known keys.

Developers needing to create connection strings as part of applications can use the System.Data.Common.DbConnectionStringBuilder class or one of its strongly typed derivatives to build and modify connection strings. The System.Data.Common.DbConnectionStringBuilder class also makes it easy to manage connection strings stored in an application configuration file.

Developers can create connection strings using either a strongly typed connection string builder class, or they can use the System.Data.Common.DbConnectionStringBuilder class. The System.Data.Common.DbConnectionStringBuilder performs no checks for valid key/value pairs. Therefore, it is possible using this class to create invalid connection strings. The System.Data.SqlClient.SqlConnectionStringBuilder supports only key/value pairs that are supported by SQL Server; trying to add invalid pairs will throw an exception.

Both the DbConnectionStringBuilder.Add(string, object) method and DbConnectionStringBuilder.Item(string) property handle tries to insert malicious entries. For example, the following code correctly escapes the nested key/value pair:

[Visual Basic]


Dim builder As New System.Data.Common.DbConnectionStringBuilder
builder("Data Source") = "(local)"
builder("integrated sSecurity") = True
builder("Initial Catalog") = "AdventureWorks;NewValue=Bad"



System.Data.Common.DbConnectionStringBuilder builder = 
    new System.Data.Common.DbConnectionStringBuilder();
builder["Data Source"] = "(local)";
builder["integrated Security"] = true;
builder["Initial Catalog"] = "AdventureWorks;NewValue=Bad";

The result is the following connection string that handles the invalid value in a safe manner:


data source=(local);integrated security=True;
initial catalog="AdventureWorks;NewValue=Bad"


Namespace: System.Data.Common
Assembly: System.Data (in System.Data.dll)
Assembly Versions:
Since: .NET 2.0