OdbcConnection.ConnectionString Property

Definition

Namespace:

System.Data.Odbc

Assembly:

System.Data.Odbc.dll

Package:

System.Data.Odbc v9.0.0-rc.2.24473.5

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

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

public override string ConnectionString { get; set; }

member this.ConnectionString : string with get, set

Public Overrides Property ConnectionString As String

Property Value

String

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.

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 as soon as it is set it is passed, unchanged, to the Driver Manager and the underlying driver. Therefore, the syntax for the ConnectionString must exactly match what the Driver Manager and underlying driver support.

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

"Driver={SQL Server};Server=(local);Trusted_Connection=Yes;Database=AdventureWorks;"

"Driver={Microsoft ODBC for Oracle};Server=ORACLE8i7;Persist Security Info=False;Trusted_Connection=Yes"

"Driver={Microsoft Access Driver (*.mdb)};DBQ=c:\bin\Northwind.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 if Persist Security Info were set to false. This means that you cannot 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. You cannot change 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=(local), which corresponds to the DataSource property). 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 run time.

However, in the .NET Framework version 1.1 and later versions, 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 can be case sensitive; and the value of the DSN keyword does not consist only of blanks.

Because of connection string and initialization file grammar, keywords and attribute values should be avoided that contain the characters []{}(),;?*=!@ not enclosed with braces. 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 ({}) that contains any of the characters []{}(),;?*=!@ is passed intact to the driver. However, when you use these characters in a keyword, the Driver Manager returns an error when you work 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, there is no guarantee which value will be selected.

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.

See also

• Connecting to Data Sources