OracleConnection.ConnectionString Property

Definition

Namespace:

System.Data.OracleClient

Assembly:

System.Data.OracleClient.dll

Gets or sets the string used to open an Oracle database.

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

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

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

Public Overrides Property ConnectionString As String

Property Value

String

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

Attributes

SettingsBindableAttribute

Examples

The following example creates an OracleConnection and sets some of its properties in the connection string.

public void CreateOracleConnection()
{
    string connectionString = "Data Source=Oracle8i;Integrated Security=yes";
    using (OracleConnection connection = new OracleConnection(connectionString))
    {
        connection.Open();
        Console.WriteLine("ServerVersion: " + connection.ServerVersion
            + "\nDataSource: " + connection.DataSource);
    }
}

Public Sub CreateOracleConnection()
    Dim connectionString As String = _
       "Data Source=Oracle8i;Integrated Security=yes"

    Using connection As New OracleConnection(connectionString)
        connection.Open()
        Console.WriteLine("ServerVersion: " + connection.ServerVersion _
           + ControlChars.NewLine + "DataSource: " + connection.DataSource)
    End Using
End Sub

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, unless an error is detected, in which 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 parsing reveals errors in syntax, a run-time 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 is 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 unless a quote character is the first or last character in the value, for example, Data Source= my'Server or Data Source= my"Server.

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 more than once in a connection string, the last occurrence is used in the value set.

Keywords are case insensitive.

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. To maintain a high level of security, we strongly recommend 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 using Oracle9i client software.
User ID		The Oracle login account. To maintain a high level of security, we strongly recommend 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 causes pooled connections to have the maximum connection time-out.
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.