DbConnectionStringBuilder.ConnectionString Property (System.Data.Common)

ConnectionString Property

Switch on low bandwidth view

Collapse All

Language Filter

This page is specific to

Microsoft Visual Studio 2008/.NET Framework 3.5

Other versions are also available for the following:

.NET Framework Class Library

DbConnectionStringBuilder..::.ConnectionString Property

Gets or sets the connection string associated with the DbConnectionStringBuilder.

Namespace: System.Data.Common
Assembly: System.Data (in System.Data.dll)

Syntax

Visual Basic (Declaration)

Public Property ConnectionString As String

Visual Basic (Usage)

Dim instance As DbConnectionStringBuilder
Dim value As String

value = instance.ConnectionString

instance.ConnectionString = value

public string ConnectionString { get; set; }

Visual C++

public:
property String^ ConnectionString {
    String^ get ();
    void set (String^ value);
}

JScript

public function get ConnectionString () : String
public function set ConnectionString (value : String)

Property Value

Type: System..::.String
The current connection string, created from the key/value pairs that are contained within the DbConnectionStringBuilder. The default value is an empty string.

Exceptions

Exception	Condition
ArgumentException	An invalid connection string argument has been supplied.

Remarks

This property returns a semicolon-delimited list of key/value pairs stored within the collection maintained by the DbConnectionStringBuilder. Each pair contains the key and value, separated by an equal sign. The following example illustrates a typical connection string.

"Persist Security Info=False;Integrated Security=SSPI;Initial Catalog=AdventureWorks;Data Source=(local)"

Data providers may expect specific keys and values for each connection string property. , These values are documented individually. The DbConnectionStringBuilder class does not validate the key/value pairs associated with its connection string, although classes that inherit from it can.

The ConnectionString property of the DbConnectionStringBuilder class acts generally as a mechanism for creating and parsing semicolon-delimited lists of key/value pairs separated with equal signs. It provides no validation or other support specific to connection strings. If you add items to the DbConnectionStringBuilder collection, the ConnectionString property will reflect the changes. If you assign a value to the ConnectionString property, the DbConnectionStringBuilder will try to parse the value, using the semicolon and equal-sign delimiters.

Examples

The following example demonstrates possible behaviors of the ConnectionString property. The example:

Creates a connection string by adding key/value pairs, one at a time, to an empty DbConnectionStringBuilder.
Assigns a complete connection string to the ConnectionString property of the DbConnectionStringBuilder instance, and modifies a single key/value pair within the string.
Assigns an arbitrary set of key/value pairs to the ConnectionString property (that is, a string that is not anything remotely like a connection string), and modifies one of the values.
Assigns an invalid connection string to the ConnectionString property, demonstrating the exception that is thrown.

Note:
This example includes a password to demonstrate how DbConnectionStringBuilder works with connection strings. In your applications, we recommend that you use Windows Authentication. If you must use a password, do not include a hard-coded password in your application.

Visual Basic

Sub Main()
    ' Create a new DbConnctionStringBuilder, and add items
    ' to the internal collection of key/value pairs.
    Dim builder As New DbConnectionStringBuilder()
    builder.Add("Data Source", "c:\MyData\MyDb.mdb")
    builder.Add("Provider", "Microsoft.Jet.Oledb.4.0")
    builder.Add("Jet OLEDB:Database Password", "*******")
    builder.Add("Jet OLEDB:System Database", _
        "c:\MyData\Workgroup.mdb")
    ' Set up row-level locking.
    builder.Add("Jet OLEDB:Database Locking Mode", 1)

    ' Display the contents of the connection string, which
    ' will now contain all the key/value pairs delimited with
    ' semicolons.
    Console.WriteLine(builder.ConnectionString)
    Console.WriteLine()

    ' Clear the DbConnectionStringBuilder, and assign a complete
    ' connection string to it, to demonstrate how
    ' the class parses connection strings.
    builder.Clear()
    builder.ConnectionString = _
        "Data Source=(local);Initial Catalog=AdventureWorks;" & _
        "Integrated Security=SSPI"

    ' The DbConnectionStringBuilder class has parsed the contents, 
    ' so you can work with any individual key/value pair.
    builder("Data Source") = "."
    Console.WriteLine(builder.ConnectionString)
    Console.WriteLine()

    ' Because the DbConnectionStringBuilder class doesn't 
    ' validate its key/value pairs, you can use this class
    ' to store any semicolon-delimited list. The following
    ' snippet places an arbitrary string into the ConnectionString
    ' property, changes one of the values, and then displays the
    ' resulting string.
    builder.Clear()
    builder.ConnectionString = _
        "Value1=10;Value2=20;Value3=30;Value4=40"
    builder("Value2") = 25
    Console.WriteLine(builder.ConnectionString)
    Console.WriteLine()

    builder.Clear()
    Try
        ' Assigning an invalid connection string
        ' throws an ArgumentException.
        builder.ConnectionString = "xxx"

    Catch ex As ArgumentException
        Console.WriteLine("Invalid connection string.")
    End Try

    Console.WriteLine()
    Console.WriteLine("Press Enter to finish.")
    Console.ReadLine()
End Sub

static void Main()
{
    // Create a new DbConnctionStringBuilder, and add items
    // to the internal collection of key/value pairs.
    DbConnectionStringBuilder builder = new
        DbConnectionStringBuilder();
    builder.Add("Data Source", @"c:\MyData\MyDb.mdb");
    builder.Add("Provider", "Microsoft.Jet.Oledb.4.0");
    builder.Add("Jet OLEDB:Database Password", "********");
    builder.Add("Jet OLEDB:System Database",
        @"c:\MyData\Workgroup.mdb");

    // Set up row-level locking.
    builder.Add("Jet OLEDB:Database Locking Mode", 1);
    // Display the contents of the connection string, which
    // will now contain all the key/value pairs delimited with
    // semicolons.
    Console.WriteLine(builder.ConnectionString);
    Console.WriteLine();
    // Clear the DbConnectionStringBuilder, and assign a complete
    // connection string to it, to demonstrate how
    // the class parses connection strings.
    builder.Clear();
    builder.ConnectionString =
        "Data Source=(local);Initial Catalog=AdventureWorks;"
        + "Integrated Security=SSPI";
    // The DbConnectionStringBuilder class has parsed the contents, 
    // so you can work with any individual key/value pair.
    builder["Data Source"] = ".";
    Console.WriteLine(builder.ConnectionString);
    Console.WriteLine();
    // Because the DbConnectionStringBuilder class doesn't 
    // validate its key/value pairs, you can use this class
    // to store any semicolon-delimited list. The following
    // snippet places an arbitrary string into the ConnectionString
    // property, changes one of the values, and then displays the
    // resulting string.
    builder.Clear();
    builder.ConnectionString =
        "Value1=10;Value2=20;Value3=30;Value4=40";
    builder["Value2"] = 25;
    Console.WriteLine(builder.ConnectionString);
    Console.WriteLine();

    builder.Clear();
    try
    {
        // Assigning an invalid connection string
        // throws an ArgumentException.
        builder.ConnectionString = "xxx";
    }
    catch (ArgumentException)
    {
        Console.WriteLine("Invalid connection string.");
    }

    Console.WriteLine();
    Console.WriteLine("Press Enter to finish.");
    Console.ReadLine();
}

Platforms

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Version Information

.NET Framework

Supported in: 3.5, 3.0, 2.0

Reference

DbConnectionStringBuilder Class

DbConnectionStringBuilder Members

System.Data.Common Namespace

Other Resources

Connection Strings (ADO.NET)