System.Data.SqlClient Namespace   SqlConnection Class

Sets or retrieves the string used to open an SQL Server™ database.

The property is read/write with no default value.

The ConnectionString is similar to an OLE DB connection string, but is not identical. Unlike OLE DB or ADO, the connection string that is returned is the same as the user-set ConnectionString minus security information if Persist Security Info value is set to false ( default ). The SQL Server™ .NET Data Provider does not persist or return the password in a connection string unless you set Persist Security Info to true.

The ConnectionString property can be set only when the connection is closed. Many of the connection string values have corresponding read-only properties. When the connection string is set, all of these properties are updated, except when an error is detected. In this case, none of the properties are updated. SqlConnection properties return only those settings contained in the ConnectionString.

Resetting the ConnectionString on a closed connection resets all connection string values ( and related properties ) including the password. For example, if you set a connection string that includes

"Database=northwind"

and then reset the connection string to

"Data Source=myServer; Integrated Security=SSPI"

the Database property is no longer set to northwind.

The connection string is parsed immediately after being set. If errors in syntax are found when parsing, an SqlException is generated. Other errors, such as invalid or unsupported properties, can be found only when an attempt is made to Open the connection at run time.

• Values may be delimited by single or double quotes, ( for example, name='value' or name="value" ). Either single or double quotes may be used within a connection string by using the other delimiter, for example, name="value's" or name='value"s', but not name='value's' or name=""value"". The value type is irrelevant.
• All blank characters, except those placed within a value or within quotes, are ignored.
• Keyword value pairs must be separated by a semicolon ( ; ). If a semicolon is part of a value, it also must be delimited by quotes.
• Names are not case sensitive. If a given name occurs more than once in the connection string, the value associated with the last occurence is used.
• No escape sequences are supported.

The following table lists the valid name=value pairs that can be used within the ConnectionString.

When setting boolean properties, you can use 'yes' instead of 'true', and 'no' instead of 'false'. Integer values are represented as strings.

NOTE: the SQL Server™ .NET data Provider uses its own protocol to communicate with SQL Server. Therefore, it does not support the use of an ODBC data source name ( DSN ) when connecting to SQL Server™ because it does not add an ODBC layer.

CAUTION: In this release, the application should use caution when constructing a connection string based on user input ( for example when retrieving user ID and password information from a dialog box, and appending it to the connection string ). The application should ensure that a user cannot embed extra connection string parameters in these values ( for example, entering a password as "validpassword;database=somedb" in an attempt to attach to a different database ).

The following example instantiates an SqlConnection, sets some of its parameters in the connection string, and opens the connection.

SqlConnection myConn = new SqlConnection ( );
myConn.ConnectionString = "user id=sa; password=yervzeñun;" +
   "data source=myServer; initial catalog=northwind;"
myConn.Open ( );

Dim myConn As New SqlConnection ( )
myConn.ConnectionString = "user id=sa; password=yervzeñun;" &_
   "data source=myServer; initial catalog=northwind;"
myConn.Open ( )

SqlConnection Members   ConnectionTimeout   Database   DataSource   Connecting to a Database