This documentation is archived and is not being maintained.

OdbcConnection.ConnectionString Property

Note: This namespace, class, or member is supported only in version 1.1 of the .NET Framework.

Gets or sets the string used to open a data source.

[Visual Basic]
Public Overridable Property ConnectionString As String  Implements _
   IDbConnection.ConnectionString
[C#]
public virtual string ConnectionString {get; set;}
[C++]
public: __property virtual String* get_ConnectionString();
public: __property virtual void set_ConnectionString(String*);
[JScript]
public function get ConnectionString() : String;
public function set ConnectionString(String);

Property Value

The ODBC driver connection string that includes settings, such as the data source name, needed to establish the initial connection. The default value is an empty string (""). The maximum length is 1024 characters.

Implements

IDbConnection.ConnectionString

Remarks

The ConnectionString property is designed to match ODBC connection string format as closely as possible. The ConnectionString can be set only when the connection is closed, and once set it is passed, unchanged, to the Driver Manager and the underlying driver. Therefore, the syntax for the ConnectionString needs to exactly match what the Driver Manager and underlying driver support.

You can use the ConnectionString property to connect to a variety of data sources, including an ODBC data source name (DSN). The following example illustrates several possible connection strings.

"Driver={SQL Server};Server=MyServer;Trusted_Connection=yes;Database=Northwind;"
"Driver={Microsoft ODBC for Oracle};Server=ORACLE8i7;Persist Security Info=False;Trusted_Connection=yes"
"Driver={Microsoft Access Driver (*.mdb)};DBQ=c:\bin\nwind.mdb"
"Driver={Microsoft Excel Driver (*.xls)};DBQ=c:\bin\book1.xls"
"Driver={Microsoft Text Driver (*.txt; *.csv)};DBQ=c:\bin"
"DSN=dsnname"
Note   The .NET Framework Data Provider for ODBC does not support the Persist Security Info keyword that is supported by other .NET Framework data providers. However, the ConnectionString property behaves as though Persist Security Info were set to false. This means that it is not possible to retrieve the password from the ConnectionString property if the connection has been opened. When the ConnectionString property is read from an OdbcConnection object that has been opened, the connection string is returned minus the password. It is not possible to alter this behavior; therefore, if the application requires the password, store it separately before calling Open.

Many of the settings specified in the string have corresponding read-only properties (for example, SERVER=MyServer, which corresponds to the DataSource property). All of these properties are updated after the connection is opened, except when an error is detected. In this case, none of the properties are updated. OdbcConnection properties (such as Database) return only default settings or those settings specified in the ConnectionString.

In the Microsoft .NET Framework version 1.0, validation of the connection string does not occur until an application calls the Open method. It is the responsibility of the underlying ODBC driver to validate the connection string. If the connection string contains invalid or unsupported properties, the driver may raise an OdbcException at runtime.

However, in the .NET Framework version 1.1, some basic validation of the connection string occurs as soon as you set the ConnectionString property. At that time, the data provider verifies that the connection string meets the "keyword=value;..." format, but it does not verify whether keywords or values are valid. The remaining verification is performed by the underlying ODBC driver when the application calls the Open method.

An ODBC connection string has the following syntax:

connection-string ::= empty-string[;] | attribute[;] | attribute; connection-string
empty-string ::=
attribute ::= attribute-keyword=attribute-value | DRIVER=[{]attribute-value[}]
attribute-keyword ::= DSN | UID | PWD
 | driver-defined-attribute-keyword
attribute-value ::= character-string
driver-defined-attribute-keyword ::= identifier

where character-string has zero or more characters; identifier has one or more characters; attribute-keyword is not case-sensitive; attribute-value may be case-sensitive; and the value of the DSN keyword does not consist solely of blanks.

Because of connection string and initialization file grammar, keywords and attribute values that contain the characters []{}(),;?*=!@ not enclosed with braces should be avoided. The value of the DSN keyword cannot consist only of blanks and should not contain leading blanks. Because of the grammar of the system information, keywords and data source names cannot contain the backslash (\) character.

Applications do not have to add braces around the attribute value after the DRIVER keyword unless the attribute contains a semicolon (;), in which case the braces are required. If the attribute value that the driver receives includes braces, the driver should not remove them but they should be part of the returned connection string.

A DSN or connection string value enclosed with braces ({}) containing any of the characters []{}(),;?*=!@ is passed intact to the driver. However, when using these characters in a keyword, the Driver Manager returns an error when working with file DSNs, but passes the connection string to the driver for regular connection strings. Avoid using embedded braces in a keyword value.

The connection string may include any number of driver-defined keywords. Because the DRIVER keyword does not use information from the system, the driver must define enough keywords so that a driver can connect to a data source using only the information in the connection string. The driver defines which keywords are required to connect to the data source.

If any keywords are repeated in the connection string, the driver uses the value associated with the first occurrence of the keyword. If the DSN and DRIVER keywords are included in the same connection string, the Driver Manager and the driver use whichever keyword appears first.

To include an equal sign (=) in a keyword or value, it must be preceded by another equal sign. For example, in the hypothetical connection string

"key==word=value"

the keyword is "key=word" and the value is "value".

Note   If an ODBC driver supports connection strings longer than 1024 characters, you can use a data source name (DSN) to exceed the maximum length limitation.

Example

[Visual Basic, C#, C++] The following example creates an OdbcConnection and sets some of its properties in the connection string.

[Visual Basic] 
Public Sub CreateOdbcConnection()
    Dim myConnString As String = _
       "DRIVER={SQL Server};SERVER=MyServer;Trusted_connection=yes;DATABASE=northwind;"
    Dim myConnection As New OdbcConnection(myConnString)
    myConnection.Open()
    MessageBox.Show("ServerVersion: " + myConnection.ServerVersion _
       + ControlChars.NewLine + "DataSource: " + myConnection.DataSource)
    myConnection.Close()
End Sub

[C#] 
public void CreateOdbcConnection() 
{
   string myConnString = "DRIVER={SQL Server};SERVER=MyServer;Trusted_connection=yes;DATABASE=northwind;";
   OdbcConnection myConnection = new OdbcConnection(myConnString);
   myConnection.Open();
   MessageBox.Show("ServerVersion: " + myConnection.ServerVersion
      + "\nDataSource: " + myConnection.DataSource);
   myConnection.Close();
}

[C++] 
public:
    void CreateOdbcConnection()
    {
        String* myConnString = S"DRIVER= {SQL Server};SERVER=MyServer;Trusted_connection=yes;DATABASE=northwind;";
        OdbcConnection* myConnection = new OdbcConnection(myConnString);
        myConnection->Open();
        MessageBox::Show(String::Concat(S"ServerVersion: ", myConnection->ServerVersion, S"\nDataSource: ", myConnection->DataSource));
        myConnection->Close();
    };

[JScript] No example is available for JScript. To view a Visual Basic, C#, or C++ example, click the Language Filter button Language Filter in the upper-left corner of the page.

Requirements

Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family

See Also

OdbcConnection Class | OdbcConnection Members | System.Data.Odbc Namespace

Show: