OracleConnectionStringBuilder Class

An OracleConnectionStringBuilder object allows applications to create or modify connection strings.

Supported Only in ADO.NET 2.0-Compliant ODP.NET

Class Inheritance

System.Object

  System.Data.Common.DbConnectionStringBuilder

    Oracle.DataAccess.Client.OracleConnectionStringBuilder

Declaration

// C#
public sealed class OracleConnectionStringBuilder : DbConnectionStringBuilder

Thread Safety

All public static methods are thread-safe, although instance methods do not guarantee thread safety.

Remarks

The following rules must be followed for setting values with reserved characters:

1. Values containing characters enclosed within single quotes

   If the value contains characters that are enclosed within single quotation marks, then the entire value must be enclosed within double quotation marks.

   For example, password = "'scoTT'" where the value is 'scoTT'.

2. Values containing characters enclosed within double quotes

   Values should be enclosed in double quotation marks to preserve the case and to avoid the upper casing of values.

   If the value contains characters enclosed in double quotation marks, then it must be enclosed in single quotation marks.

   For example, password = '"scoTT"' where the value is "scoTT".

3. Values containing characters enclosed in both single and double quotes

   If the value contains characters enclosed in both single and double quotation marks, the quotation mark used to enclose the value must be doubled each time it occurs within the value.

   For example, password = '"sco''TT"' where the value is "sco'TT".

4. Values containing spaces

   All leading and trailing spaces are ignored, but the spaces between the value are recognized. If the value needs to have leading or trailing spaces then it must be enclosed in double quotation marks.

   For example, User ID = Sco TT where the value is <Sco TT>.

   For example, User ID = "Sco TT " where the value is <Sco TT>.

5. Keywords occurring multiple times in a connection string

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

   For example, with "User ID = scott; password = tiger; User ID = david" connection string, User ID value is david.

Example

// C#
 
using System;
using System.Data;
using System.Data.Common;
using Oracle.DataAccess.Client;
using System.Collections;
 
class ConnectionStringBuilderSample
{
  static void Main(string[] args)
  {
    string connString = "user id=scott;password=tiger;Data source=oracle;";
    bool bRet = false;
    
    // Create an instance of OracleConnectionStringBuilder
    OracleConnectionStringBuilder connStrBuilder = 
      new OracleConnectionStringBuilder(connString);
    
    // Add a new key/value to the connection string
    connStrBuilder.Add("pooling", false);
    
    // Modify the existing value
    connStrBuilder["Data source"] = "inst1";
    
    // Remove an entry from the connection string
    bRet = connStrBuilder.Remove("pooling");
 
    //ContainsKey indicates whether or not the specific key exist
    //returns true even if the user has not specified it explicitly
    Console.WriteLine("Enlist exist: " + 
              connStrBuilder.ContainsKey("Enlist"));
 
    //returns false
    connStrBuilder.ContainsKey("Invalid");
 
    // ShouldSerialize indicates whether or not a specific key 
    // exists in connection string inherited from DbConnectionStringBuilder.
    // returns true if the key is explicitly added the user otherwise false;
    // this will return false as this key doesn't exists.
    connStrBuilder.ShouldSerialize("user"); 
 
    // returns false because this key is nott added by user explicitly.
    connStrBuilder.ShouldSerialize("Enlist");
 
    // IsFixedSize [read-only property]
    Console.WriteLine("Connection String is fixed size only: "
                            + connStrBuilder.IsFixedSize);
    Console.WriteLine("Key/Value Pair Count: " + connStrBuilder.Count);
 
    //adding a new key which is not supported by the provider 
    //is not allowed.
    try
    {
      //this will throw an exception.
      connStrBuilder.Add("NewKey", "newValue");
    }
    catch (Exception ex)
    {
      Console.WriteLine(ex.Message);
      Console.WriteLine(ex.StackTrace);
    }
 
    Console.WriteLine("Key/Value Pair Count: " + connStrBuilder.Count);
 
    //modifying a existing key is allowed.
    connStrBuilder.Add("Enlist", false);
    Console.WriteLine("Key/Value Pair Count: " + connStrBuilder.Count);
 
    // Get all the keys and values supported by the provider.
    ICollection keyCollection = connStrBuilder.Keys;
    ICollection valueCollection = connStrBuilder.Values;
 
    IEnumerator keys = keyCollection.GetEnumerator();
    IEnumerator values = valueCollection.GetEnumerator();
    
    while (keys.MoveNext())
    {
      values.MoveNext();
      Console.WriteLine("Key: {0}     Value: {1} \n" 
        ,keys.Current ,values.Current);
    }
  }
}

Requirements

Namespace: Oracle.DataAccess.Client

Assembly: Oracle.DataAccess.dll

ODP.NET Version: ODP.NET for .NET Framework 2.0 or ODP.NET for .NET Framework 4

---

OracleConnectionStringBuilder Members

OracleConnectionStringBuilder members are listed in the following tables.

OracleConnectionStringBuilder Constructors

OracleConnectionStringBuilder constructors are listed in Table 7-5.

OracleConnectionStringBuilder Public Properties

OracleConnectionStringBuilder instance properties are listed in Table 7-6.

OracleConnectionStringBuilder Public Methods

OracleConnectionStringBuilder instance methods are listed in Table 7-7.

---

OracleConnectionStringBuilder Constructors

OracleConnectionStringBuilder constructors instantiate new instances of the OracleConnectionStringBuilder class.

Overload List:

• OracleConnectionStringBuilder()

  This constructor instantiates a new instance of OracleConnectionStringBuilder class.

• OracleConnectionStringBuilder(string)

  This constructor instantiates a new instance of the OracleConnectionStringBuilder class with the provided connection string.

OracleConnectionStringBuilder()

This constructor instantiates a new instance of the OracleConnectionStringBuilder class.

Declaration

// C#
public OracleConnectionStringBuilder();

Remarks

The ConnectionString property is empty after the object is created.

OracleConnectionStringBuilder(string)

This constructor instantiates a new instance of the OracleConnectionStringBuilder class with the provided connection string.

Declaration

// C#
public OracleConnectionStringBuilder(string connectionString);

Parameters

• connectionString

  The connection information.

Exceptions

ArgumentNullException - The connectionString parameter is null.

ArgumentException - The connectionString parameter is invalid.

Remarks

The ConnectionString property of this instance is set to the supplied connection string.

---

OracleConnectionStringBuilder Public Properties

OracleConnectionStringBuilder public properties are listed in Table 7-8.

ConnectionLifetime

This property specifies the value corresponding to the Connection Lifetime attribute in the ConnectionString property.

Declaration

// C#
public int ConnectionLifetime{get; set;}

Property Value

An int that represents the value of the supplied attribute.

Exceptions

OracleException - The specified value is less than zero.

Remarks

When an OracleConnectionStringBuilder instance is created, this property is set to the default value of the corresponding connection string attribute.

ConnectionTimeout

This property specifies the value corresponding to the Connection Timeout attribute in the ConnectionString property.

Declaration

// C#
 public int ConnectionTimeout{get; set;}

Property Value

An int that represents the value of the supplied attribute.

Exceptions

OracleException - The specified value is less than zero.

Remarks

When an OracleConnectionStringBuilder instance is created, this property is set to the default value of the corresponding connection string attribute.

ContextConnection

This property specifies the value corresponding to the Context Connection attribute in the ConnectionString property.

Declaration

// C#
public bool ContextConnection {get; set;}
 

Property Value

A bool that represents the value of the supplied attribute.

DataSource

This property specifies the value corresponding to the Data Source attribute in the ConnectionString property.

Declaration

// C#
public string DataSource{get; set;}

Property Value

A string that represents the value of the supplied attribute.

Exceptions

ArgumentNullException - The specified value is null.

Remarks

When an OracleConnectionStringBuilder instance is created, this property is set to the default value of the corresponding connection string attribute.

DBAPrivilege

This property specifies the value corresponding to the DBA Privilege attribute in the ConnectionString property.

Declaration

// C#
 public string DBAPrivilege{get; set;}

Property Value

A string that represents the value of the supplied attribute.

Possible values are SYSDBA or SYSOPER.

Exceptions

ArgumentNullException - The specified value is null.

OracleException - The specified value is invalid.

Remarks

When an OracleConnectionStringBuilder instance is created, this property is set to the default value of the corresponding connection string attribute.

DecrPoolSize

This property specifies the value corresponding to the Decr Pool Size attribute in the ConnectionString property.

Declaration

// C#
 public int DecrPoolSize{get; set;}

Property Value

An int that represents the value of the supplied attribute.

Exceptions

OracleException - The specified value is less than 1.

Remarks

When an OracleConnectionStringBuilder instance is created, this property is set to the default value of the corresponding connection string attribute.

Enlist

This property specifies the value corresponding to the Enlist attribute in the ConnectionString property.

Declaration

// C#
public string Enlist{get; set;};

Property Value

A string that represents the value of the supplied attribute. Values are case-insensitive. Possible values are: dynamic, true, false, yes, and no.

Exceptions

ArgumentNullException - The specified value is null.

OracleException - The supplied value is not one of following: dynamic, true, false, yes, or no.

Remarks

When an OracleConnectionStringBuilder instance is created, this property is set to the default value of the corresponding connection string attribute.

HAEvents

This property specifies the value corresponding to the HA Events attribute in the ConnectionString property.

Declaration

// C#
 public bool HAEvents{get; set;}

Property Value

A bool that represents the value of the supplied attribute.

Remarks

When an OracleConnectionStringBuilder instance is created, this property is set to the default value of the corresponding connection string attribute.

IncrPoolSize

This property specifies the value corresponding to the Incr Pool Size attribute in the ConnectionString property.

Declaration

// C#
public int IncrPoolSize{get; set;}

Property Value

An int that represents the value of the supplied attribute.

Exceptions

OracleException - The specified value is less than 1.

Remarks

When an OracleConnectionStringBuilder instance is created, this property is set to the default value of the corresponding connection string attribute.

IsFixedSize

Indicates whether or not the Connection String Builder has a fixed size.

Declaration

// C#
public override bool IsFixedSize{get;}
 

Property Value

Returns true if the Connection String Builder has a fixed size; otherwise, returns false.

Remarks

Attributes cannot be added or removed. They can only be modified for connection strings with a fixed size.

Item

This property specifies the value associated with the specified attribute.

Declaration

// C#
public override object this[string keyword]{get; set;}
 

Property Value

An object value corresponding to the attribute.

Exceptions

ArgumentNullException - The specified attribute is null.

OracleException - The specified attribute is not supported or the specified value is invalid.

Keys

This property specifies a collection of attributes contained in the Connection String Builder.

Declaration

// C#
public override ICollection Keys{get;}
 

Property Value

Returns an ICollection that represents the attributes in the Connection String Builder.

LoadBalancing

This property specifies the value corresponding to the Load Balancing attribute in the ConnectionString property.

Declaration

// C#
 public bool LoadBalancing {get; set;}

Property Value

A bool that contains the value of the supplied attribute.

Remarks

When an OracleConnectionStringBuilder instance is created, this property is set to the default value of the corresponding connection string attribute.

MaxPoolSize

This property specifies the value corresponding to the Max Pool Size attribute in the ConnectionString property.

Declaration

// C#
public int MaxPoolSize{get; set;}

Property Value

An int that represents the value of the supplied attribute.

Exceptions

OracleException - The specified value is less than 1.

Remarks

When an OracleConnectionStringBuilder instance is created, this property is set to the default value of the corresponding connection string attribute.

MetadataPooling

This property specifies the value that corresponds to the Metadata Pooling attribute in the ConnectionString property.

Declaration

// C#
public bool MetadataPooling{get; set;};

Property Value

A bool containing the value of the supplied attribute.

Remarks

When an OracleConnectionStringBuilder instance is created, this property is set to the default value of the corresponding connection string attribute.

MinPoolSize

This property specifies the value corresponding to the Min Pool Size attribute in the ConnectionString property.

Declaration

// C#
public int MinPoolSize{get; set;}

Property Value

An int that contains the value of the supplied attribute.

Exceptions

OracleException - The specified value is less than 0.

Remarks

When an OracleConnectionStringBuilder instance is created, this property is set to the default value of the corresponding connection string attribute.

Password

This property specifies the value corresponding to the Password attribute in the ConnectionString property.

Declaration

// C#
public string Password{get; set;}

Property Value

A string that contains the value of the supplied attribute.

Exception

ArgumentNullException - The specified value is null.

PersistSecurityInfo

This property specifies the value corresponding to the Persist Security Info attribute in the ConnectionString property.

Declaration

// C#
public bool PersistSecurityInfo{get; set;}

Property Value

A bool that represents the value of the supplied attribute.

Remarks

When an OracleConnectionStringBuilder instance is created, this property gets set to the default value of the corresponding connection string attribute.

Pooling

This property specifies the value corresponding to the Pooling attribute in the ConnectionString property.

Declaration

// C#
public bool Pooling {get; set;}

Property Value

A bool that represents the value of the supplied attribute.

Remarks

When an OracleConnectionStringBuilder instance is created, this property is set to the default value of the corresponding connection string attribute.

ProxyPassword

This property specifies the value corresponding to the Proxy Password attribute in the ConnectionString property.

Declaration

// C#
public string ProxyPassword {get; set;}

Property Value

A string that represents the value of the supplied attribute.

Exception

ArgumentNullException - The specified value is null.

ProxyUserId

This property specifies the value corresponding to the Proxy User Id attribute in the ConnectionString property.

Declaration

// C#
public string ProxyUserId {get; set;}

Property Value

A string that represents the value of the supplied attribute.

Exception

ArgumentNullException - The specified value is null.

SelfTuning

This property specifies the value corresponding to the Self Tuning attribute in the ConnectionString property.

Declaration

// C#
public bool SelfTuning {get; set;}

Property Value

A bool that represents the value of the supplied attribute.

StatementCachePurge

This property specifies the value corresponding to the Statement Cache Purge attribute in the ConnectionString property.

Declaration

// C#
public bool StatementCachePurge {get; set;}

Property Value

A bool that represents the value of the supplied attribute.

Remarks

When an OracleConnectionStringBuilder instance is created, this property is set to the default value of the corresponding connection string attribute.

StatementCacheSize

This property specifies the value corresponding to the Statement Cache Size attribute in the ConnectionString property.

Declaration

// C#
public int StatementCacheSize{get; set;}

Property Value

An int that represents the value of the supplied attribute.

Exceptions

OracleException - The specified value is less than zero.

Remarks

When an OracleConnectionStringBuilder instance is created, this property is set to the default value of the corresponding connection string attribute.

UserID

This property specifies the value corresponding to the User Id attribute in the ConnectionString property.

Declaration

// C#
public string UserID{get; set;}

Property Value

A string that represents the value of the supplied attribute.

Exception

ArgumentNullException - The specified value is null.

ValidateConnection

This property specifies the value corresponding to the Validate Connection attribute in the ConnectionString property.

Declaration

// C#
public bool ValidateConnection{get; set;}

Property Value

A bool that represents the value of the supplied attribute.

Remarks

When an OracleConnectionStringBuilder instance is created, this property is set to the default value of the corresponding connection string attribute.

Values

This property specifies a collection of values contained in the Connection String Builder.

Declaration

// C#
public override ICollection Values{get;}

Property Value

Returns an ICollection that represents the values in the Connection String Builder.

Remarks

The order of the values in the ICollection is unspecified, but is the same as the associated attributes in the ICollection returned by the Keys property.

---

OracleConnectionStringBuilder Public Methods

OracleConnectionStringBuilder public methods are listed in Table 7-9.

Clear

This method clears the connection string contents.

Declaration

// C#
public override void Clear();

Remarks

All key/value pairs are removed from the OracleConnectionStringBuilder object and the ConnectionString property is set to Empty.

ContainsKey

This method indicates whether or not a specific attribute in the connection string is supported by ODP.NET.

Declaration

// C#
public override bool ContainsKey(string keyword);

Parameters

• keyword

  The attribute being verified.

Return Value

Returns true if the specified attribute exists; otherwise, returns false.

Exceptions

ArgumentNullException - The specified attribute is null.

Remarks

This method indicates if the attribute is part of the provider-supported attributes. It does not indicate if the user added the attribute to the connection string.

Remove

This method removes the entry corresponding to the specified attribute from the connection string.

Declaration

// C#
public override bool Remove(string keyword);

Parameters

• keyword

  The attribute that specifies the entry to be removed.

Return Value

Returns true if the attribute existed in the connection string and the corresponding entry was removed; otherwise, returns false.

Exceptions

ArgumentNullException - The specified attribute is null.

TryGetValue

This method returns the value corresponding to the supplied attribute, as an output parameter.

Declaration

// C#
public override bool TryGetValue(string keyword, out object value);

Parameters

• keyword

  The attribute for which the value is being retrieved.

• value

  The value of the supplied attribute.

  Sets value to the default value if the attribute is not present in the connection string.

Return Value

Returns true if the value that corresponds to the attribute has been successfully retrieved; otherwise, returns false. If the attribute is not present in the connection string, returns false and sets the value to null.

Exceptions

ArgumentNullException - The specified attribute is null.

Remarks

If the function returns false, sets value to null.

If the attribute is not present in the connection string, sets value to the default value.