Export (0) Print
Expand All

OracleConnection.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 an Oracle 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 Oracle connection string that includes settings, such as the server name, needed to establish the initial connection. The default value is an empty string ("").

Implements

IDbConnection.ConnectionString

Remarks

The ConnectionString can be set only when the connection is closed.

You can use the ConnectionString property to connect to a database. The following example illustrates a typical connection string.

"Data Source=Oracle8i;Integrated Security=yes"

Many of the settings specified in the string have corresponding read-only properties (for example, Data Source=MyServer, which corresponds to the DataSource property). 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. OracleConnection properties return only default settings or those settings specified in the ConnectionString.

Resetting the ConnectionString on a closed connection resets all connection string values (and related properties), including the password.

The connection string is parsed immediately after being set. If errors in syntax are found when parsing, a runtime exception, such as ArgumentException, is generated. Other errors can be found only when an attempt is made to open the connection.

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.

The following table lists the valid names for values within the ConnectionString.

Name Default Description
Data Source

-or-

Server

  The name or network address of the instance of Oracle to which to connect.
Integrated Security 'false' Whether the connection is to be a secure connection or not.

Recognized values are true (strongly recommended), false, yes, and no.

Password   The password for the Oracle account logging on (Not recommended. To maintain a high level of security, it is strongly recommended that you use the Integrated Security keyword instead.).
Persist Security Info 'false' When set to false or no (strongly recommended), security-sensitive information, such as the password, is not returned as part of the connection if the connection is open or has ever been in an open State. Resetting the connection string resets all connection string values, including the password.

Recognized values are true, false, yes, and no.

Unicode 'false' Specifies whether the .NET Framework Data Provider for Oracle uses UTF16 mode API calls. This keyword is ignored except when not using distributed transactions with Oracle 9i client software. If Unicode is set to true when not using Oracle 9i client software to communicate with an Oracle 9i server, unpredictable results may occur.
User ID   The Oracle login account (Not recommended. To maintain a high level of security, it is strongly recommended that you use the Integrated Security keyword instead.).

The following table lists the valid names for connection pooling values within the ConnectionString.

Name Default Description
Connection Lifetime 0 When a connection is returned to the pool, its creation time is compared with the current time, and the connection is destroyed if that time span (in seconds) exceeds the value specified by Connection Lifetime. This is useful in clustered configurations to force load balancing between a running server and a server just brought online.

A value of zero (0) causes pooled connections to have the maximum connection timeout.

Enlist 'true' When true or yes, the pooler automatically enlists the connection in the creation thread's current transaction context.

Recognized values are true, false, yes, and no.

Max Pool Size 100 The maximum number of connections allowed in the pool. Setting the Max Pool Size value of the ConnectionString can affect performance. If you plan to create and actively use more than 100 connections, you should increase Max Pool Size to a value that approximates the steady state connection usage for the application.
Min Pool Size 0 The minimum number of connections allowed in the pool.
Pooling 'true' When true or yes, the OracleConnection object is drawn from the appropriate pool, or if necessary, is created and added to the appropriate pool.

Recognized values are true, false, yes, and no.

When setting keyword or connection pooling values that require a Boolean value, you can use 'yes' instead of 'true', and 'no' instead of 'false'. Integer values are represented as strings.

Example

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

[Visual Basic] 
Public Sub CreateOracleConnection()
    Dim myConnString As String = _
       "Data Source=Oracle8i;Integrated Security=yes"
    Dim myConnection As New OracleConnection(myConnString)
    myConnection.Open()
    MessageBox.Show("ServerVersion: " + myConnection.ServerVersion _
       + ControlChars.NewLine + "DataSource: " + myConnection.DataSource)
    myConnection.Close()
End Sub

[C#] 
public void CreateOracleConnection() 
{
   string myConnString = "Data Source=Oracle8i;Integrated Security=yes";
   OracleConnection myConnection = new OracleConnection(myConnString);
   myConnection.Open();
   MessageBox.Show("ServerVersion: " + myConnection.ServerVersion
      + "\nDataSource: " + myConnection.DataSource);
   myConnection.Close();
}

[C++] 
public:
 void CreateOracleConnection() 
 {
    String* myConnString = S"Data Source=Oracle8i;Integrated Security=yes";
    OracleConnection* myConnection = new OracleConnection(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

.NET Framework Security: 

See Also

OracleConnection Class | OracleConnection Members | System.Data.OracleClient Namespace

Show:
© 2014 Microsoft