OdbcConnection.ConnectionString Property

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

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

public override string ConnectionString { get; set; }

public string ConnectionString { get; set; }

[System.ComponentModel.SettingsBindable(true)]
public override string ConnectionString { get; set; }

member this.ConnectionString : string with get, set

[<System.ComponentModel.SettingsBindable(true)>]
member this.ConnectionString : string with get, set

Public Overrides Property ConnectionString As String

Public Property ConnectionString As 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

Attributes

SettingsBindableAttribute

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"

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.

Applies to

See also

• Connecting to Data Sources