dotConnect for Oracle Documentation
Devart.Data.Oracle Namespace / OracleConnection Class / ConnectionString Property

In This Topic
    ConnectionString Property (OracleConnection)
    In This Topic
    Gets or sets the string used to open an Oracle server database.
    Public Shadows Property ConnectionString As String
    public new string ConnectionString {get; set;}

    Property Value

    The connection string that includes the source database name, and other parameters needed to establish the initial connection. The default value is an empty string ("").

    The ConnectionString property can be set only when the connection is closed; setting ConnectionString of an opened connection closes this connection. Many of the connection string values have corresponding 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. OracleConnection 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 "Home = OraClient12Home1", and then reset the connection string to "Data Source=ora; User ID = Scott; Password = tiger", the Home property is no longer set to 'OraClient11g_Home1'.

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

    The ConnectionString property format is the same as for common ADO.NET connection strings. Connection string consists of pairs of parameter name and parameter value connected by the equal sign (=). Each pair should be separated from the previous one by a semicolon. Parameter values may be specified inside single or double qotes, (for example, name='value' or name="value"). Either single or double quotes may be used in a value if it is set using another type of quotes, for example, name="value's" or name= 'value"s', but not name= 'value's' or name= ""value"". If a semicolon is a part of a value, the value must be quoted. All blank characters, except those placed within a value or within quotes, are ignored. No escape sequences are supported. The value type is irrelevant. Parameter names are case insensitive. Arguments names may occur only once in the connection string.

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

    Name Description
    ClientId Specifies the client identifier for the connection.
    Connect Mode Allows opening a session with administrative privileges - as SYSDBA or SYSOPER or etc.
    Connection Class Connection class for Oracle's Database Resident Connection Pooling (DRCP). You need to set also OCI Session Pooling = true for using DRCP. DRCP is supported starting with Oracle 11g.
    Connection Lifetime 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. The default value is 0.
    Connection Timeout Time (in seconds) to wait while trying to establish a connection before terminating the attempt and generating an error. A value of 0 indicates no limit. The default value is 15 seconds.
    Data Source -or- Server -or- Host The name of TNS alias of Oracle database to which to connect. For more information refer to Server property.
    Default Command Timeout The time in seconds to wait while trying to execute a command before terminating the attempt and generating an error. 0 indicates no limit.
    Default Fetch Size The default value of the OracleCommand.FetchSize property of OracleCommand instances, created via the CreateCommand method.
    DescribeStoredProcedure -or- Describe Stored Procedure Enables or disables additional check queries, performed when executing an OracleCommand with CommandType equal to CommandType.StoredProcedure. See more details in OracleConnectionStringBuilder.DescribeStoredProcedure.
    Direct If true, dotConnect for Oracle can operate without an Oracle client installed. The default value is false. See Using Direct Mode for more information.
    Enlist Determines whether the connection is automatically enlisted in the current distributed transaction. The default value is true. This parameter is not available in Mobile Edition. This parameter is not supported in .NET Standard 1.3 compatible assembly.
    HA Events Allows dotConnect for Oracle to proactively remove connections to cooresponding Oracle database service, service member, instance, or node from the pool when this service, service member, instance, or node goes down.
    Home The Oracle Home that will be used. This parameter is not supported in .NET Standard compatible assemblies.
    Initialization Command Specifies a database-specific command that should be executed immediately after establishing the connection. You can specify a sequence of several commands in this parameter.
    License Key Specify your license key in this parameter. This is required only when using .NET Standard compatible assemblies. See Licensing .NET Standard (.NET Core) Projects for more information.
    Lob Block Size Specifies the size of a block (in megabytes) to read/write CLOB or NCLOB data from/to database. This option is supported in OCI mode only. Applicable only for Unicode Oracle servers. Default value is 0, which means that the whole value is sent in one block. If you get errors when reading/writing huge LOB values, try setting this property to 8, it is the safest value.
    Max Pool Size The maximum number of connections allowed in the pool. Setting the Max Pool Size value of the ConnectionString can affect performance. The default value is 100.
    Min Pool Size The minimum number of connections allowed in the pool. The default value is 0.
    Number Mappings

    Sets the number mappings used for this connection. Each mapping is set as (OracleNumberType, FromPrecision, ToPrecision, SystemType), where:

    - OracleNumberType is one of the values from OracleNumberType enumeration;
    FromPrecision and ToPrecision set the minimal and maximal precisions of the Oracle number type to map with this mapping;
    SystemType is a .NET type to which Oracle number type should be mapped.

    Several mappings should be separated by commas and covered by a common parentheses. For example, this property may be set as:
    Number Mappings = (Integer, 1, 1, System.Boolean)
    Number Mappings = ((Integer, 1, 5, System.Int16), (FLOAT,12,15,System.Decimal), (NUMBER,7,9,System.Single))

    Oci Session Pooling If true, enables the OCI Session Pooling feature. In this mode the dotConnect for Oracle pool is disabled.
    Oci Session Pool Allow Waiting If true, new connections wait for an existing one to close if Max Size is reached; otherwise an exception is thrown.
    Oci Session Pool Connection Lifetime This attribute specifies the lifetime of the connection in seconds. Before the Connection is placed back into the pool, the lifetime of the connection is checked. If the lifetime of the connection exceeds this property value, the connection is closed and disposed. If this property value is 0, the connection lifetime is never checked.
    Oci Session Pool Increment Allows applications to set the next increment for sessions to be started if the current number of sessions is less than Max Size. The valid values are 1 and above.
    Oci Session Pool Max Size Specifies the maximum number of sessions that can be opened in the session pool. Once this value is reached, no more sessions are opened. The valid values are 1 and above.
    Oci Session Pool Min Size Specifies the minimum number of sessions in the session pool. This number of sessions are started initially. After this, sessions are opened only when necessary.
    Oci Session Pool Password If set, defines password for proxy user.
    Oci Session Pool User Id If set, defines user name for proxy user. Available only when OCI Session Pooling is enabled. If you want to have proxy connections without OCI Session Pooling, use the Open(OracleConnection) overload that accepts another OracleConnection as argument.
    OraMts If set to true, Oracle Services for Microsoft Transaction Server (OraMTS) is used for distributed transactions; otherwise OraMTS is not used. This parameter is not supported in .NET Standard 1.3 compatible assembly.
    Pass Parameters By Name Pass parameters by name to the stored procedure calls. If set to true, parameters will be passed by name regardless of individual OracleCommand.PassParametersByName values. Default value is false.
    Password The password for the Oracle login account. Leave blank if you want to use Integrated Security connections (OS authentication).
    Pooling If true, by default, the OracleConnection object is drawn from the appropriate pool or is created and added to the appropriate pool.
    Port Number of a port to communicate with listener on the server to use in OracleConnection.Direct mode. The default value is 1521.
    Run Once Command Specifies a database-specific command that should be executed immediately after establishing the connection. Unlike Initialization Command, it is not executed when a connection is taken from the pool.
    Service Name Alias to an Oracle database instance (or many instances) to use in the OracleConnection.Direct mode. The default value is empty string. When Service Name is specified and implies several database instances, dotConnect for Oracle connects to the first instance provided by Oracle listener. Note that the Direct mode has limited support for RAC, it supports RAC with Connect Time Connection Failover (CTCF) only.
    SID Unique name for an Oracle database instance to use in the OracleConnection.Direct mode. The default value is empty string.
    SSH Authentication Type Client authentication method. See SshAuthenticationType for additional information.
    SSH Cipher List List of ciphers that client agrees to use. See OracleConnectionStringBuilder.SshCipherList for additional information.
    SSH Host Name or ip address of SSH server.
    SSH Host Key The location of the public key on the client side to verify the server host key during establishing connection.
    SSH Passphrase Passphrase for the client key.
    SSH Password User password on SSH server.
    SSH Port Number of port on SSH server to connect.
    SSH Private Key Location of the private key to use.
    SSH Strict Host Key Check Indicates whether the host key is verified during establishing connection.
    SSH User User id on SSH server.
    SSL Cert An SSL Certificate, provided as Base64 string.
    SSL ServerCertDN Specifies parameters for the server certificate check.
    SSL WalletPath Determines the location of the Oracle Wallet to get a certificate for connecting to Oracle in the Direct mode.
    Statement Cache Purge Determines whether to clear the OCI statement cache when closing the connection or putting it to the pool. The default value is false.
    Statement Cache Size This attribute enables or disables statement caching. Its value specifies the maximum number of statements that can be cached for a connection. By default this attribute is set to 0 (disabled). Statement caching starts if this parameter is set to a value more than 0. It should not be more than MAX_OPEN_CURSORS parameter in an Oracle database.
    Transaction Scope Local If there are several connections with the same connection string (which includes "Transaction Scope Local=true;") within a scope of TransactionScope, our provider will use only one connection internally. The default value is false. Not available in Mobile Edition. This parameter is not supported in .NET Standard 1.3 compatible assembly.
    Trim Fixed Char Specifies whether to trim trailing spaces when reading data from fixed-length string data types (CHAR, NCHAR). It affects all command objects of this connection. Behaviour of data reader depends on Trim Fixed Char value at the moment of opening data reader. The default value is true.
    Unicode Specifies whether dotConnect for Oracle uses UTF8 or UTF16 mode API calls. Default value is false in the assemblies for Full .NET Framework, but true in .NET Standard compatible assemblies.
    Use Performance Monitor Enables dotConnect for Oracle performance counters that allow you to conveniently measure the frequency of connecting/disconnecting to the data source, the number of active connections, pooled connections, etc. via Windows Performance Monitor or programmatically. See Performance Counters Support for more information. This parameter is not supported in .NET Standard compatible assemblies.
    User ID -or- User The Oracle login account. Leave blank if you want to use Integrated Security connections (OS authentication).
    Validate Connection Specifies whether to validate connections that are being got from the pool.
    The following example creates an OracleConnection and sets some of its properties in the connection string.
    public void CreateOraConnection()
            string oracleConnectionString1 = "User ID=Scott; Password=tiger; Data Source=ORA"; 
            OracleConnection oracleConnection1 = new OracleConnection(oracleConnectionString1); 
            string oracleConnectionString2 = 
                    "User ID=Scott; Password=tiger; Direct = true; Host=ORA; Service Name=SID; Port=1521;"; 
            OracleConnection oracleConnection2 = new OracleConnection(oracleConnectionString2); 
    Public Sub CreateOraConnection()
            Dim OracleConnectionString1 As String = "User ID=Scott; Password=tiger; Data Source=ORA"
            Dim OracleConnection1 As New OracleConnection(OracleConnectionString1)
            Dim OracleConnectionString2 As String = _
                    "User ID=Scott; Password=tiger; Direct = true; Host=ORA; Service Name=SID; Port=1521;"
            Dim OracleConnection2 As New OracleConnection(OracleConnectionString2)
    End Sub

    Target Platforms: Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

    See Also