Oracle Data Provider for .NET, Managed Driver Configuration
ODP.NET, Managed Driver supports .NET configuration file-based settings in
web.config. It does not support Windows registry based configuration. ODP.NET, Managed Driver settings in .NET configuration files are similar to ODP.NET, Unmanaged Driver settings to make porting easier.
The ODP.NET, Managed Driver configuration file section name is
<oracle.manageddataaccess.client> settings and values are also supported in unmanaged ODP.NET configuration file:
<oracle.unmanageddataaccess.client>. While this documentation section discusses managed ODP.NET configuration, it is also applicable to
<oracle.unmanageddataaccess.client> share numerous common settings with
<oracle.manageddataaccess.client>. Differences between the two are noted on this page. The
<oracle.unmanageddataaccess.client> settings not available in managed ODP.NET are documented in "Oracle Data Provider for .NET, Unmanaged Driver Configuration". A typical .NET config that uses ODP.NET, Managed Driver has some or all of the following subsections nested within a
<version> subsection under
<oracle.manageddataaccess.client> section. Note the tag names are case sensitive, while the attribute names are case insensitive.
<?xml version="1.0" encoding="utf-8" ?> <configuration> <oracle.manageddataaccess.client> <version number="*"> <dataSources> ... ... </dataSources> <settings> ... ... </settings> <LDAPsettings> ... ... </LDAPsettings> <implicitRefCursor> ... ... </implicitRefCursor> <edmMappings> ... ... <edmMappings> </version> <version number="188.8.131.52"> <dataSources> ... ... </dataSources> <settings> ... ... </settings> <LDAPsettings> ... ... </LDAPsettings> <implicitRefCursor> ... ... </implicitRefCursor> <edmMappings> ... ... <edmMappings> </version> </oracle.manageddataaccess.client> </configuration>
The ODP.NET, Managed Driver configuration and settings are described in the following sections. Many of the attributes are the same as ODP.NET, Unmanaged Driver. See Table 2-3 for detailed attribute descriptions.
All the information required by an application should be grouped under the
version subsections. Each
<version number="X"> section contains parameters applicable for version
X of the ODP.NET, Managed Driver. For example,
<version number="184.108.40.206"> section parameters will be applicable only for those applications using ODP.NET, Managed Driver assembly 220.127.116.11.
Apart from version specific sections, there can also be a generic section
<version number="*">. This section's parameters are applicable for all ODP.NET, Managed Driver versions. Parameters in the version specific section take precedence over the parameters of the generic section. The following is an example of a
<oracle.manageddataaccess.client> <version number="*"> <settings> <setting name="TraceOption" value="1"/> <setting name="PerformanceCounters" value="0" /> </settings> </version> <version number="18.104.22.168"> <settings> <setting name="PerformanceCounters" value="4095" /> </settings> </version> </oracle.manageddataaccess.client>
An application referencing ODP.NET, Managed Driver 22.214.171.124 has the following values set:
TraceOption = 1
This section can appear only under a
<version> section. The mapping between the different data source aliases and corresponding data descriptors should appear in this section. This section is supported by managed ODP.NET only. The following is an example.
<dataSources> <dataSource alias="inst1" descriptor="(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)......)))"/> <dataSource alias="inst2" descriptor="(DESCRIPTION= ......)))"/> </dataSources>
data source connection string attribute can alternatively be set to a full descriptor or Easy Connect syntax rather than a data source alias.
Requirements for connecting to a local database without specifying "data source" connection string attribute:
The listener must be up and running.
ORACLE_SIDenvironment variable must be set appropriately.
data source connection string attribute is not specified, protocol defaults to 'tcp' and port defaults to '1521'.
The ODP.NET managed driver reads and caches all the alias entries from the
machine.config, and from a
tnsnames.ora file that is found at application start-up time. However, aliases that are defined in LDAP servers are resolved and cached on demand. This means for each unique alias that is used by the application, an alias resolution query is executed against an LDAP server and the full descriptor associated with the alias will be cached once it is fetched.
For developers that need to change or add alias settings while developing applications, one may consider using
OracleDataSourceEnumerator.GetDataSources() rather than restarting the application. Invoking this method will first wipe out existing cache entries that were read from the
tnsnames.ora file and all aliases obtained from the LDAP Server. Then, the
tnsnames.ora is re-parsed and all its entries will be cached again. Please note that the
machine.config entries are read only once at application start-up time and thus their contents are maintained and not re-parsed even if
OracleDataSourceEnumerator.GetDataSources() is invoked.
OracleDataSourceEnumerator.GetDataSources() method invocation has an impact on the connection pool. This is because a connection pool, which is created for each unique connection string, will cache the resolved full descriptor information after the first connection is created for a given connection pool. After that, the connection pool uses the cached full descriptor information for all subsequent connection creations. Thus, for applications that have their
tnsnames.ora or LDAP entries modified during the execution of an application where an alias points to a different database than before, one should call the
OracleDataSourceEnumerator.GetDataSources() method to remove old cached entries. This should be followed by the invocation of the
ClearPool(OracleConnection) instance method or the
ClearAllPools() static method to remove existing connections and also have it obtain a new full descriptor value that was read by the invocation of
OracleDataSourceEnumerator.GetDataSources(). Following this scheme will assure that all the connections in the connection pool uses the new full descriptor that is now associated with the alias and all connections in a connection pool is established to the same database.
The following keywords are supported within the descriptor setting:
ADDRESS_LIST(Note: only failover supported)
Oracle recommends using SCAN listener and Runtime Load Balancing to balance the load when connecting to an Oracle RAC database.
DESCRIPTION_LIST(Note: Failover supported;
Address_listload balancing not supported)
HOST(Note: <hostname>, <IPv6 literal>, and <IPv4 literal> are supported)
IP(Note: "loopback" is supported)
PROTOCOL(Note: tcp and tcps are supported. In addition, WS and WSS are also supported.)
RETRY_COUNT: Specifies the number of times an
ADDRESSlist is traversed before the connection attempt is terminated and times out.
RETRY_DELAY: Specifies the delay in seconds between subsequent retries for a connection.
RETRY_DELAYare timeout parameters that work at the Oracle networking layer. They are intended to be used in conjunction with each other. When these parameters are used, ODP.NET will attempt to connect with one of the addresses in the
ADDRESS_LIST. If there is no successful connection after going through the entire list, then ODP.NET will wait for the number of seconds specified by
RETRY_DELAYbefore traversing the address list again. It will repeat this behavior until there is a successful connection or the
RETRY_COUNTlimit is hit.
For example, let's assume
RETRY_DELAY=4when ODP.NET cannot successfully connect to any address on the list. The following sequence is triggered:
Traverse address list to connect.
Wait four seconds for next set of retry attempts.
Traverse the address list again. This is first set of retry attempts.
Wait four seconds for the next retry attempt.
Traverse the address list again. This is the second and final set of retry attempts.
These timeout parameters function independent of ODP.NET application timeouts, such as the
Connection Timeoutconnection string attribute. If the
Connection Timeoutis set to a low value, then it may trigger before the
RETRY_DELAYattempt cycle completes.
Session Data Unit size supports from
SECURITY: SSL_VERSION(Note: overrides sqlnet.ora:ssl_version)
TRANSPORT_CONNECT_TIMEOUT(Note: overrides tcp.connect_timeout)
SSL is now supported via method MCS and FILE.
Both Kerberos5 and NTS authentication are supported. RADIUS is not supported.
Only NTS authentication is supported. No RADIUS nor Kerberos5 authentication.
Only Net Services, Easy Connect naming, and LDAP (namely, Active Directory and Oracle Internet Directory) are supported.
No bequeath (
beq) support. Default address is instead TCP loopback with port 1521 and Oracle service name from environment (
Oracle Database Net Services Reference for a detailed description of the attributes.
Though managed ODP.NET does not support TNS descriptor based load balancing, it does support failover through both an
Note that you need not specify either the
LOAD_BALANCE or the
FAILOVER directive, because only failover is supported. The directives are ignored.
The following examples demonstrate TNS descriptors utilizing failover:
(DESCRIPTION= (ADDRESS_LIST= (ADDRESS=(PROTOCOL=tcp)(HOST=host1)(PORT=1630)) (ADDRESS=(PROTOCOL=tcp)(HOST=host2)(PORT=1630)) (ADDRESS=(PROTOCOL=tcp)(HOST=host3)(PORT=1521))) (CONNECT_DATA=(SERVICE_NAME=Sales.us.example.com))) (DESCRIPTION_LIST= (DESCRIPTION= (ADDRESS_LIST= (ADDRESS=(PROTOCOL=tcp)(HOST=sales1a-svr)(PORT=1521)) (ADDRESS=(PROTOCOL=tcp)(HOST=sales1b-svr)(PORT=1521))) (CONNECT_DATA=(SERVICE_NAME=sales1.example.com))) (DESCRIPTION= (ADDRESS_LIST= (ADDRESS=(PROTOCOL=tcp)(HOST=sales2a-svr)(PORT=1521)) (ADDRESS=(PROTOCOL=tcp)(HOST=sales2b-svr)(PORT=1521))) (CONNECT_DATA=(SERVICE_NAME=sales2.us.example.com))))
This section can appear only under a
<version> section. Any ODP.NET, Managed Driver specific settings should appear in this section. The following is an example of a
<settings> <setting name="TraceLevel" value="7" /> <setting name="TraceOption" value="1"/> <setting name="TNS_ADMIN" value="C:\oracle\work"/> </settings>
A new default behavior has been introduced for ODP.NET Release 126.96.36.199 and later when
InitialLobFetchSize is set to
-1. The new default value is
LegacyEntireLOBFetch = 0. To use the old behavior, set
LegacyEntireLobFetch = 1 in the ODP.NET configuration. Refer to "Setting InitialLONGFetchSize to -1" for more information.
ODP.NET, Managed Driver configuration settings that are supported:
CPVersion: Determines whether ODP.NET, Unmanaged Driver uses the traditional connection pool implementation (
Default=1.0) or the more modern connection pool implementation with better high availability support (
2.0). In addition, the more modern connection pool (
2.0) is required if the application uses Database Resident Connection Pooling (DRCP), or hosts multiple pluggable databases or editions in the same pool. Possible values:
ODP.NET, Managed Driver only uses the more modern connection pool implementation. This setting can only be used for ODP.NET, Unmanaged Driver for .NET Framework 4 and higher. It cannot be used for earlier versions of unmanaged ODP.NET, which will always use the traditional connection pool implementation.
CPVersionis set explicitly, then that setting will be used across processes for all connection strings.
CPVersionis left unmodified (or contains an invalid value) and an application's first unmanaged ODP.NET established connection for a given connection string uses DRCP, pluggable databases, or editions by modifying one these features' properties or configuration settings, then
CPVersionwill be implicitly modified to use the newer connection pool implementation (
CPVersion 1.0pool attempts to use DRCP, pluggable database, or edition settings, then ODP.NET will raise an exception when the application attempts to open a connection.
CPVersion 2.0is used explicitly or implicitly and the "proxy user id" is not specified in the connection string, then a proxy connection will not be created, even if "proxy password" is supplied.
CPVersion 2.0is used by ODP.NET, Unmanaged Driver, the connection pool behavior will be the same as the more modern connection pool as implementation that ODP.NET, Managed Driver uses.
Disable_Oob: Interrupts database query execution via either TCP/IP urgent data or normal TCP/IP data, called out of band data (default) or in band data, respectively. (Default=
All Oracle database clients support interrupting database query execution, such as through an ODP.NET command timeout. Windows-based database servers only support in band breaks, whereas all other (predominantly UNIX-based) database servers can support out of band (OOB) or in band breaks. ODP.NET, Managed Driver uses OOB breaks by default with database servers that support it. For certain network topologies, the routers or firewalls involved in the route to the database may have been configured to drop urgent data or in band the data. If the routers or firewalls can not be changed to handle urgent data appropriately, then the ODP.NET, Managed Driver can be configured to utilize in band breaks by setting the .NET configuration parameter
DllPath: (Unmanaged ODP.NET only) Specifies the directory location dependent unmanaged Oracle Client binaries are loaded from.
See Search Order for Unmanaged DLLs for more information.
DRCPConnectionClass: Specifies a logical name that identifies the DRCP connection pool that the ODP.NET connection will use. It will be used as a default if the
DRCPConnectionClassproperty on the
OracleConnectionobject is not set. It will be ignored for non-DRCP connections.
Valid Values: the connection class name is string at max 1024 characters. The default is null.
GetDecimalRetainTrailingZeros: (Managed ODP.NET only) Specifies whether to retain trailing zeros from an Oracle
NUMBERin a .NET Decimal.
See OracleConfiguration GetDecimalRetainTrailingZeros for more information.
LDAP_ADMIN: Specifies the
LDAP_ADMINsetting works in conjunction with the
TNS_ADMINsetting to set
See Oracle Client Configuration File Settings for
NAMES.DIRECTORY_PATH: The default search order is
EZCONNECTare the only name resolution methods supported, but their order of precedence can be modified.
ORA_DEBUG_JDWP: Allows Oracle PL/SQL Debugger and database to connect automatically without application code changes. Value is set as
IP_address or host_name
debugging port number
RECEIVE_BUF_SIZE: Sets TCP
SO_RECVBUF, the total buffer space associated with the local side of a TCP socket
SEND_BUF_SIZE: Sets TCP
SO_SENDBUF, the total buffer space associated with the local side of a TCP socket
In seconds. (
Whenever a database service becomes unavailable, such as due to a service being relocated, an application can encounter numerous connectivity errors during this time. To avoid unnecessary connection attempts to an unavailable service which will result in an error, ODP.NET blocks any connection attempts until the service is up or until this property's specified time limit expires from the time when the service DOWN event was received, whichever comes first. Once the specified time elapses, all the connection attempts to the specific service which is known to be down will no longer be blocked. Those requests will be sent to the server.
ServiceRelocationConnectionTimeoutis only operational in conjunction with Oracle Fast Connection Failover (
true). Once Fast Connection Failover is enabled for the .NET application, Service Relocation Connection Timeout is automatically enabled. It will use its default value if no
ServiceRelocationConnectionTimeoutvalue has been explicitly set. It works with planned and unplanned outages.
When connecting to Oracle Data Guard in Oracle Database 12c Release 2 or later, database administrators can set their own timeout value,
drain_timeout, to indicate the number of seconds allowed for resource draining to be completed. This setting can be optionally used by the ODP.NET
ServiceRelocationConnectionTimeoutvalue as the intent behind
ServiceRelocationConnectionTimeoutare the same.
drain_timeoutare not set, then the default
ServiceRelocationConnectionTimeoutvalue is used (90 seconds). If only
drain_timeoutis set, then that value will be used for the service relocation connection timeout. If only
drain_timeoutis set and is set to 0, then also default
ServiceRelocationConnectionTimeoutvalue is used (90 seconds). If both are set, then the value of
ServiceRelocationConnectionTimeoutwill override the value of
ServiceRelocationConnectionTimeoutitself can be set based upon the value of
drain_timeout. For example, if ODP.NET administrators desire the service relocation connection timeout to be
drain_timeoutplus 50 seconds, then they would set
ServiceRelocationConnectionTimeoutin the following manner:
<setting name="ServiceRelocationConnectionTimeout" value="drain_timeout + 50"/>
Service Relocation Connection Timeout is not supported in pools that connect to more than one pluggable database.
SQLNET.AUTHENTICATION_SERVICES: Supported values are
Managed ODP.NET supports
TCPSexternal authentication methods. This setting should be set based on the desired database authentication method. If internal database authentication is desired, then the setting should be set to
NONE. Default value is
NONE. The value(s) must be enclosed in parentheses. Example settings made in
SQLNET.AUTHENTICATION_SERVICES = (TCPS) SQLNET.AUTHENTICATION_SERVICES = (NTS) SQLNET.AUTHENTICATION_SERVICES = (Kerberos5, NTS) SQLNET.AUTHENTICATION_SERVICES = (NONE)
NTSexternal authentication methodology is only supported on a Windows-based client and server.
SQLNET.AUTHENTICATION_SERVICESdefault values are different for managed ODP.NET and unmanaged ODP.NET. Managed ODP.NET defaults to
NONEand unmanaged defaults to
ALLwhen no value is set.
SQLNET.CRYPTO_CHECKSUM_CLIENT: Specifies the desired data integrity behavior when this client connects to a server. Supported values are
required. Default =
SQLNET.CRYPTO_CHECKSUM_TYPES_CLIENT: Specifies the data integrity algorithms that this client uses. Supported values are
SQLNET.ENCRYPTION_CLIENT= Negotiates whether to turn on encryption. Supported values are accepted, rejected, requested, or required.
SQLNET.ENCRYPTION_TYPES_CLIENT= Encryption algorithm(s) to use.
The following table lists the valid encryption algorithms for ODP.NET, Managed Driver.
Table 2-4 Encryption Algorithms for ODP.NET, Managed Driver
Algorithm Name Legal Value
AES 128-bit key
AES 192-bit key
AES 256-bit key
For more information on data encryption settings, refer to the Oracle Database Security Guide.
SQLNET.EXPIRE_TIME: Specifies a time interval to send a new set of probes to verify the connection remains active. This setting is equivalent to the
OracleConnection.KeepAliveIntervalis fixed at 6 seconds for
SQLNET.EXPIRE_TIME. Default is 0 (off). By default the value is specified in minutes. However the value can be specified in seconds (sec) and milliseconds (ms), such as the following example:
<setting name=" SQLNET.EXPIRE_TIME" value="30 sec" />
SSL_SERVER_DN_MATCH: To enforce the distinguished name (DN) for the database server matches its service name. (Default=
If you enforce the match verification, then SSL/TLS ensures that the certificate is from the server. If you select to not enforce the match verification, then SSL/TLS performs the check but allows the connection, regardless if there is a match. Not enforcing the match allows the server to potentially fake its identify.
trueto enforce a match.
falseto not enforce a match.
SSL_SERVER_DN_MATCHis often used together with
SSL_SERVER_CERT_DNspecifies the distinguished name (DN) of the database server. It can be set in the connect descriptor.
net_service_name= (DESCRIPTION= (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-svr)(PORT=1521)) (ADDRESS=(PROTOCOL=tcp)(HOST=sales2-svr)(PORT=1521)) (CONNECT_DATA= (SERVICE_NAME=sales.us.acme.com)) (SECURITY= (SSL_SERVER_CERT_DN="cn=sales,cn=OracleContext,dc=us,dc=acme,dc=com")))
The client uses this information to obtain the list of DNs it expects for each of the servers, enforcing the database server DN to match its service name. Use this parameter with
SSL_SERVER_DN_MATCHto enable server DN matching.
SSL_VERSION: Sets the version of the SSL/TLS connection. By default, all supported versions are enabled, in the order
The client and server negotiate to the highest version among the common conversions specified in their configurations. The versions from lowest to highest are:
To specify more than one version, use the
orkeyword between values. For example,
1.2 or 1.1 or 3.0.
TNS_ADMIN: Location where either one or more of
sqlnet.oraare located. Locations can consist of either absolute or relative directory paths.
TOKEN_AUTH: This attribute specifies the access token authentication type. Possible values are
DISABLED. Only supported for managed ODP.NET and ODP.NET Core.
TOKEN_LOCATION: This attribute is the file-based token location. The value can be a directory where a file named "token" is or it can be the file's full path specification. Only supported for managed ODP.NET and ODP.NET Core.
TraceFileLocation: Trace file destination directory, for example,
D:\traces. The default
<Windows user temporary folder>
TraceFileMaxSize: Maximum file size of each trace file. Default is 100 MB (100,000,000). The default value is 100. The unit of measure is megabytes (i.e. 100 MB).
1= public APIs;
2= private APIs;
4= network APIs/data;
8= disables writing SQL statements and network packet contents. These values can be
ORed. To enable everything, set
7. Errors will always be traced.
WALLET_LOCATION: Microsoft Certificate Store (MCS) and file system wallets are supported.
This section can appear only under a
<version> section. Any ODP.NET, Managed Driver specific LDAP settings should appear in this section. This section is supported by managed ODP.NET only. The following is an example of a
<LDAPsetting> subsection under the
<LDAPsettings> <LDAPsetting name="DIRECTORY_SERVER_TYPE" value="AD" /> <LDAPsetting name="DEFAULT_ADMIN_CONTEXT" value="dc=Oracle,dc=com"/> </LDAPsettings>
Lightweight Directory Access Protocol
ODP.NET, Managed Driver supports TNS alias resolution through a LDAP server/service, specifically Microsoft Active Directory and Oracle Internet Directory (OID). TNS alias resolution occurs when using the
LDAPsettings section or
ldap.ora file settings. The
LDAPsettings section settings take precedence over
For Active Directory, only the
DEFAULT_ADMIN_CONTEXT parameters are required in
ldap.ora. When the
DIRECTORY_SERVERS parameter is missing or has no value, the default LDAP server for the current domain will be used.
For OID, all
ldap.ora parameters must be set with valid values to complete configuration.
ODP.NET, Managed Driver and ODP.NET, Unmanaged Driver support the same level of security when using LDAP for name resolution.
Table 2-5 Microsoft Active Directory: Encryption Types and Authentication Credentials For Connecting and Binding
|No Encryption||SSL Encryption|
Domain User authentication
Domain User authentication
Table 2-6 Oracle Internet Directory: Encryption Types and Authentication Credentials For Connecting and Binding
|No Encryption||SSL Encryption|
Wallet based authentication
Note: Wallet based authentication for Oracle Internet Directory is not supported for this release
Oracle Database Net Services Reference for more information on Directory Usage Parameters.
Oracle Database Net Services Administrator's Guide for more information on Managing Network Address.
This section can appear only under a
<version> section. Any information about
REF CURSOR parameters that need to be bound implicitly should appear in this section. The following is an example of an
<implicitRefCursor> <storedProcedure schema="USERREFCUR" name="TestProc1"> <refCursor name="Param3"> <bindInfo mode="Output"/> <metadata columnOrdinal="0" columnName="DEPTNO" baseColumnName="DEPTNO" baseSchemaName="USERREFCUR" baseTableName="DEPT" nativeDataType="number" providerType="Int32" dataType="System.Int16" columnSize="2" allowDBNull="true" /> <metadata columnOrdinal="1" columnName="DNAME" baseColumnName="DNAME" baseSchemaName="USERREFCUR" baseTableName="DEPT" nativeDataType="varchar2" providerDBType="String" columnSize="30" /> </refCursor> <refCursor name="param2"> <bindInfo mode="Output"/> <metadata columnOrdinal="0" columnName="EMPNO" baseColumnName="EMPNO" baseSchemaName="USERREFCUR" baseTableName="EMP" nativeDataType="number" providerType="Int32" dataType="System.Int16" columnSize="4" allowDBNull="false" /> </refCursor> </storedProcedure> <!--Next stored procedure information--> <storedProcedure name="TestProc2"> ... ... </storedProcedure> </implicitRefCursor>
This section can appear only under a
<version> section. Any information about distributed transactions should appear in this section. The following is an example of a
<distributedTransaction> <setting name="OMTSRECO_IP_ADDRESS" value="my-pc" /> <setting name="OMTSRECO_PORT" value="2040" /> <setting name="ORAMTS_SESS_TXNTIMETOLIVE" value="240" /> </distributedTransaction>
OMTSRECO_IP_ADDRESS: Specifies the machine name (or IP address) that the OraMTS Recovery service will be running on to resolve database in-doubt transactions. The default is the local machine name.
OMTSRECO_PORT: Specifies the port that the OraMTS Recovery service will be listening on to resolve database in-doubt transactions. The default is 2030.
ORAMTS_SESS_TXNTIMETOLIVE: Specifies the time in seconds that the transaction can remain inactive after it has been detached or delisted from the database. Once this time expires, the transaction is automatically terminated by the provider. The default is 120 seconds.
UseOraMTSManaged: When set to
trueand using .NET Framework 4.5.2 or higher, ODP.NET uses managed code for distributed transactions. If set to
false, ODP.NET uses Oracle Services for Microsoft Transaction Server to support distributed transactions. Boolean (
Default = false) for ODP.NET, Unmanaged Driver only.
This section can appear only under a
<version> section. This section allows setting a string identifier for each set of monitored connection counters. Refer to Connection Performance Counters documentation section for more details.
This section can appear only under a
<version> section. Any information related to EDM mappings should appear in this section. Refer to Oracle Number Default Data Type Mapping and Customization for more examples on
Oracle Notification Service (ONS) can be configured using either local or remote configuration using the
<onsConfig> section. The
<onsConfig> section is available only for managed ODP.NET. Remote configuration is the preferred configuration for standalone client applications. For releases earlier than Oracle Database 12c, this section is mandatory for ODP.NET to receive ONS notifications. With Oracle Database 12c and later, this section is optional and the information about the ONS daemons is received from the server itself. However, ODP.NET will also listen for events from any
<host:port> pairs that is provided by the user in this section in addition to the
<host:port> pairs received from the server.
For local configuration, please ensure that ONS is configured and available on the node where ODP.NET is running, so that ODP.NET can receive events directly from the local ONS daemon. The following is a sample format for the local configuration:
<onsConfig configFile="C:\temp\test.config" mode="local"> </onsConfig>
configFile specified in .NET config should contain the same
remoteport values as specified in the
ons.config used by the local ONS daemon. This will enable the application to receive events from the local ONS daemon.
Remote configuration is used in scenarios where the application directly receives ONS events from the ONS daemons running on remote machines. One of the advantages of this configuration is that no ONS daemon is needed on the client end and, therefore, there is no need to manage this process.
The following is a sample format for remote configuration:
<onsConfig mode="remote"> <ons database="db1"> <add name="nodeList" value="racnode1:4100, racnode2:4200" /> </ons> <ons database="db2"> <add name="nodeList" value=" racnode3:4100, racnode4:4200" /> </ons> </onsConfig>
In case of remote configuration, the application has to specify the
<host>:<port> values for every potential database that it can connect to. The
<host>:<port> value pairs represent the ports on the the different Oracle RAC nodes where the ONS daemons are talking to their remote clients.
Client Side ONS Daemon Configurationfor information about client side ONS daemon configuration
ONS TCPS and Wallets
ODP.NET enables ONS communications to occur over TCP/IP with SSL/TLS (TCPS), which is more secure than just TCP/IP. As TCPS requires using a wallet for storing keys and certificates, ODP.NET can use one wallet for both ONS and ODP.NET connections or have separate wallets for each.
TCPS provides more secure ONS communication, gives administrators flexibility in how to configure their wallets, and enables cloud database connections.
oracle.manageddataaccess.client configuration section sample
<oracle.manageddataaccess.client> <version number="*"> <onsConfig mode="remote"> <settings> <setting name="Protocol" value="TCPS" /> <setting name="WALLET_LOCATION" value="D:\user\ONS_SSLWallet" /> </settings> <ons database="acdb183"> <add name="nodeList" value="slcai611:6205,slcai610:6205,slcai612:6205" /> </ons> </onsConfig> <settings> <setting name="WALLET_LOCATION" value=" D:\user\DBWallet" /> </settings> </version> </oracle.manageddataaccess.client>
The protocol and wallet location properties are often used together.
If an ONS wallet location is set, ODP.NET will use the wallet for ONS to connect via TCP/IP with SSL/TLS regardless of the protocol setting.
If the protocol is set to “TCPS”, ODP.NET first tries to use the wallet in the ONS configuration wallet location to connect via TCP/IP with SSL/TLS. If no wallet is present, ODP.NET next tries to use the wallet from the database wallet location. If no wallet is found, the connection fails.
Administrators can choose between having the ONS connection use its own independent wallet or share the database’s wallet for ease of use.
If the protocol is set to “TCP” and no ONS wallet location is set, ODP.NET ONS will connect with TCP/IP.
ODP.NET ONS TCPS works with any Oracle Database version that supports ONS TCPS on the server side.
Client Side ONS Daemon Configuration
ONS configuration is controlled by the ONS configuration file,
/opmn/conf/ons.config. This file tells the ONS daemon how it should behave. The
SRVCTL utility can be used to start and stop the ONS daemon. It is installed on each node by default during server install.
Configuration information within ons.config is defined in simple name and value pairs. An example of
ONS.config is given below
# This is an example ons.config file # # The first three values are required localport=4100 remoteport=4200 nodes=racnode1.example.com:4200,racnode2.example.com:4200
Some parameters in the ons.config file are required and some are optional. Table Table 2-7 lists the required ONS configuration parameters and Table 2-8 lists the optional ONS configuration parameters.
Table 2-7 Required ONS Configuration Parameters
The port that ONS binds to on the local host interface to talk to local clients.
The port that ONS binds to on all interfaces for talking to other ONS daemons.
A list of other ONS daemons to talk to. Node values are given as a comma-delimited list of either host names or IP addresses plus ports. The port value that is given is the remote port that each ONS instance is listening on. In order to maintain an identical file on all nodes, the
The nodes listed in the nodes line correspond to the individual nodes in the Oracle RAC instance. Listing the nodes ensures that the middle-tier node can communicate with the Oracle RAC nodes. At least one middle-tier node and one node in the Oracle RAC instance must be configured to see one another. As long as one node on each side is aware of the other, all nodes are visible. You need not list every single cluster and middle-tier node in the ONS configuration file of each Oracle RAC node. In particular, if one ONS configuration file cluster node is aware of the middle tier, then all nodes in the cluster are aware of it.
Table 2-8 Optional ONS Configuration Parameters
The level of messages that should be logged by ONS. This value is an integer that ranges from 1, which indicates least messages logged, to 9, which indicates most messages logged. The default value is 3.
A log file that ONS should use for logging messages. The default value for log file is
The wallet file used by the Oracle Secure Sockets Layer (SSL) to store SSL certificates. If a wallet file is specified to ONS, then it uses SSL when communicating with other ONS instances and require SSL certificate authentication from all ONS instances that try to connect to it. This means that if you want to turn on SSL for one ONS instance, then you must turn it on for all instances that are connected. This value should point to the directory where your
The value, reserved for use on the server-side, to indicate ONS whether it should store all Oracle RAC nodes and port numbers in Oracle Cluster Registry (OCR) instead of the ONS configuration file or not. A value of
Do not use this option on the client-side.
ons.config file allows blank lines and comments on lines that begin with the number sign (#).
Oracle Real Application Clusters Administration and Deployment Guide for more information about the
Relative Windows Path and Windows Environment Variable Configuration Settings
The following managed ODP.NET configuration settings support relative Windows path and environment variables:
File locations for the above config parameters can now be set using relative Windows paths. The "
." notation informs ODP.NET to use the current working directory. Sub-directories can be added by appending them. For example,
.\mydir refers to the sub-directory
mydir in the current working directory. To navigate to a parent directory, use the "
For web applications, the current working directory is the application directory. For Windows applications, the
.EXE location is the current working directory.
Windows paths can also be set using Windows environment variable names within "
If the environment variable that is used by the configuration parameter is not set to anything, then an exception will be thrown.
A directory name cannot partially be using an environment variable. For example,
Multiple variables can used in given directory location. For example,
Oracle Database Net Services Reference chapters covering
tnsnames.ora local naming parameters, and
listener.ora Oracle Net Listener parameters, for more information about these Oracle client settings.