This documentation is archived and is not being maintained.

OleDbConnection.ConnectionString Property

Gets or sets the string used to open a database.

[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 OLE DB provider connection string that includes the data source name, and other parameters needed to establish the initial connection. The default value is an empty string.

Implements

IDbConnection.ConnectionString

Exceptions

Exception Type Condition
ArgumentException An invalid connection string argument has been supplied or a required connection string argument has not been supplied.

Remarks

The ConnectionString is designed to match OLE DB connection string format as closely as possible with the following exceptions:

  • The "Provider = value " clause is required. However, you cannot use "Provider = MSDASQL" because the .NET Framework Data Provider for OLE DB does not support the OLE DB Provider for ODBC (MSDASQL). To access ODBC data sources, use the OdbcConnection object, which is in the System.Data.Odbc namespace.
  • 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 is set to false (default). The .NET Framework Data Provider for OLE DB does not persist or return the password in a connection string unless you set the Persist Security Info keyword to true (not recommended). To maintain a high level of security, it is strongly recommended that you use the Integrated Security keyword with Persist Security Info set to false.

You can use the ConnectionString property to connect to a variety of data sources, including a Microsoft Data Link (UDL). The following example illustrates several possible connection strings.

"Provider=MSDAORA; Data Source=ORACLE8i7;Persist Security Info=False;Integrated Security=yes"
"Provider=Microsoft.Jet.OLEDB.4.0; Data Source=c:\bin\LocalAccess40.mdb"
"Provider=SQLOLEDB;Data Source=MySQLServer;Integrated Security=SSPI"

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. OleDbConnection 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 "Initial Catalog= northwind", and then reset the connection string to "Provider= SQLOLEDB;Data Source= MySQLServer;IntegratedSecurity=SSPI", the Database property is no longer set to northwind. (The Initial Catalog value of the connection string corresponds to the Database property.)

A preliminary validation of the connection string is performed when the property is set. If values for the Provider, Connect Timeout, Persist Security Info, or OLE DB Services are included in the string, these values are checked. When an application calls the Open method, the connection string is fully validated. If the connection string contains invalid or unsupported properties, a runtime exception, such as ArgumentException, is generated at that time.

The basic format of a connection string consists of a series of keyword/value pairs separated by semicolons. The equal sign (=) connects each keyword and its value. To include values that contain a semicolon, single-quote character, or double-quote character, the value must be enclosed in double quotes. If the value contains both a semicolon and a double-quote character, the value can be enclosed in single quotes. The single quote is also useful if the value begins with a double-quote character. Conversely, the double quote can be used if the value begins with a single quote. If the value contains both single-quote and double-quote characters, the quote character used to enclose the value must be doubled each time it occurs within the value.

To include preceding or trailing spaces in the string value, the value must be enclosed in either single quotes or double quotes. Any leading or trailing spaces around integer, Boolean, or enumerated values are ignored, even if enclosed in quotes. However, spaces within a string literal keyword or value are preserved. Single or double quotes may be used within a connection string without using delimiters (for example, Data Source= my'Server or Data Source= my"Server) unless a quote character is the first or last character in the value.

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".

If a specific keyword in a keyword= value pair occurs multiple times in a connection string, the last occurrence listed is used in the value set.

Keywords are not case sensitive.

To reference a UDL, add a reference to the UDL to the ConnectionString in the form "File Name = myfile.udl". If more than one UDL is specified in the connection string, only the last occurrence is loaded. If you specify a UDL, and subsequently call the OleDbConnection object to retrieve the ConnectionString, the ConnectionString contains the reference to the UDL file, not the contents of the file. Connection strings that contain UDLs are parsed each time the OleDbConnection is opened. Because this can affect performance, a ConnectionString that does not reference a UDL is recommended.

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). If you use the Extended Properties connection string parameter for OLE DB connections, avoid passing user IDs and passwords because you should avoid storing user IDs and passwords in clear text if at all possible, and because the default setting of Persist Security Info= false does not affect the Extended Properties parameter.

Example

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

[Visual Basic] 
Public Sub CreateOleDbConnection()
    Dim myConnString As String = _
       "Provider=SQLOLEDB;Data Source=localhost;Initial Catalog=Northwind;Integrated Security=SSPI;"
    Dim myConnection As New OleDbConnection(myConnString)
    myConnection.Open()
    MessageBox.Show("ServerVersion: " + myConnection.ServerVersion _
       + ControlChars.NewLine + "DataSource: " + myConnection.DataSource)
    myConnection.Close()
End Sub

[C#] 
public void CreateOleDbConnection() 
{
   string myConnString = "Provider=SQLOLEDB;Data Source=localhost;Initial Catalog=Northwind;Integrated Security=SSPI;";
   OleDbConnection myConnection = new OleDbConnection(myConnString);
   myConnection.Open();
   MessageBox.Show("ServerVersion: " + myConnection.ServerVersion
      + "\nDataSource: " + myConnection.DataSource);
   myConnection.Close();
}

[C++] 
public:
 void CreateOleDbConnection() 
 {
    String* myConnString = S"Provider=SQLOLEDB;Data Source=localhost;Initial Catalog=Northwind;Integrated Security=SSPI;";
    OleDbConnection* myConnection = new OleDbConnection(myConnString);
    myConnection->Open();
    MessageBox::Show(String::Format( S"ServerVersion: {0}\nDataSource: {1}", myConnection->ServerVersion, 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

OleDbConnection Class | OleDbConnection Members | System.Data.OleDb Namespace

Show: