Oracle Data Provider for  .NET, Managed Driver

Installation Guide, Quick Start, and Release Notes

Release Beta

September 2012

Copyright (c) Oracle Corporation 2012

This document provides information that supplements the Oracle Data Provider for .NET (ODP.NET) Production documentation.




1. Download ODP.NET, Managed Driver .zip file to a directory for staging the install.
2. Unzip the download to expand its contents into the target directory.
3. Run configure.bat to GAC and configure machine.config for ODP.NET, Managed Driver.
4. Create a new Visual Studio 2010 console application project for C#.
5. Add Oracle.ManagedDataAccess.dll as a reference to the project.
6. Replace the contents of Program.cs with the following C# code. Notice that the namespace of ODP.NET, Managed Driver (Oracle.ManagedDataAccess.*) is different from the namespace of ODP.NET, Unmanaged Driver (Oracle.DataAccess.*).

// C#
using System;
using Oracle.ManagedDataAccess.Client;
using Oracle.ManagedDataAccess.Types;

namespace Connect
  class Program
    static void Main(string[] args)
        // Please replace the connection string attribute settings
        string constr = "user id=scott;password=tiger;data source=oracle";

        OracleConnection con = new OracleConnection(constr);
        Console.WriteLine("Connected to Oracle Database {0}", con.ServerVersion);

        Console.WriteLine("Press RETURN to exit.");
      catch (Exception ex)
        Console.WriteLine("Error : {0}", ex);

7. Modify the "user id", "password", and "data source" connection string attributes appropriately.
8. Copy over the sqlnet.ora and tnsnames.ora (which contains the definition of the alias used by the "data source" attribute setting) to the location of the .exe. For example, if the application has "...;data source=oracle;..." in the connection string, then 'oracle' needs to be defined, in a tnsnames.ora. If you do not have these files, modify the tnsnames.ora supplied in the .zip and copy the tnsnames.ora and sqlnet.ora to the location of the .exe. Note that there are other ways to define data source aliases. See the Configuration and Setup section below for more details. If you do not wish to copy the .ora files, then you can configure the application config file as in the following example. Please modify the path appropriately to where the .ora files are located.
    <version number="*">
        <setting name="TNS_ADMIN" value="C:\oracle\network\admin"/>
To make this a machine-wide setting, the machine.config file can be configured.
9. Build your ODP.NET application and run.
10. If you are able to connect, you are on your way to develop and run other ODP.NET, Managed Driver projects!
11. If you're not able to connect to the Oracle Database, please have a look at the Oracle Network Managegement Documentation.
12. Run unconfigure.bat to remove ODP.NET, Managed Driver from the GAC and remove its configuration entries from the machine.config.

Note: ODP.NET, Managed Driver has the same exact application programming interfaces (APIs) as ODP.NET, Unmanaged Driver. However, the Managed Driver's APIs are a subset of the Unmanaged Driver's APIs. Refer to the Differences Between ODP.NET, Managed Driver and ODP.NET, Unmanaged Driver section for more details.

Note: ODP.NET, Managed Driver is not supported to work with Oracle Developer Tools for .NET (ODT.NET).



ODP.NET, Managed Driver requires the following:

  • Microsoft Windows operating system
    • 32-bit: Windows 7 (Professional, Enterprise, Ultimate editions), Windows Server 2008
    • x64: Windows 7 (Professional, Enterprise, Ultimate editions), Windows Server 2008 R2 and Windows Server 2008 (all editions, except HPC)
  • Microsoft .NET Framework 4
  • Access to an Oracle Database Server (Oracle Database 10g Release 2 or higher)

ODP.NET, Managed Driver is built with AnyCPU. It runs on either 32-bit or 64-bit (x64) Windows.



Installation Files

The zip file contains the following files:

    File Description
    Oracle.ManagedDataAccess.dll Platform-independent (AnyCPU), fully-managed ADO.NET provider
    x64\Oracle.ManagedDataAccessDTC.dll Platform-dependent (x64 only), Managed Assembly for Distributed Transaction support.
    x86\Oracle.ManagedDataAccessDTC.dll Platform-dependent (x86 only), Managed Assembly for Distributed Transaction support.
    x64\OraProvCfg.exe Platform-dependent (x64 only) utility to configure/unconfigure ODP.NET, Managed and Unmanaged Drivers on x64 platforms
    x86\OraProvCfg.exe Platform-dependent (x86 only) utility to configure/unconfigure ODP.NET, Managed and Unmanaged Drivers on x86 platforms and on WOW (Windows on Windows)
    configure64.bat Batch file to place ODP.NET, Managed Driver into the GAC and add configuration entries into the machine.config on 64-bit OS. [XCopy install only]
    configure32.bat Batch file to place ODP.NET, Managed Driver into the GAC and add configuration entries into the machine.config on 32-bit OS and on WOW. [XCopy install only]
    unconfigure64.bat Batch file to remove ODP.NET, Managed Driver from the GAC and remove configuration entries from machine.config on 64-bit OS. [XCopy install only]
    unconfigure32.bat Batch file to remove ODP.NET, Managed Driver from the GAC and remove configuration entries from machine.config on 32-bit OS and on WOW. [XCopy install only]
    tnsnames.ora A sample configuration file that defines data source aliases. [XCopy install only]
    sqlnet.ora A sample configuration file that configures network related settings. [XCopy install only]
    Oracle.ManagedDataAccess.Client.Configuration.Section.xsd An XML schema file that defines the configuration section for ODP.NET, Managed Driver.

  • Oracle.ManagedDataAccessDTC.dll is only needed if the application uses distributed transactions.
  • If Distributed Transactions are used by the ODP.NET, Managed Driver application, the appropriate Oracle.ManagedDataAccessDTC.dll (x64 or x86) will be loaded. However, the required Oracle.ManagedDataAccessDTC.dll needs to be either in the GAC or in the same directory as the .exe for it to be loaded by Oracle.ManagedDataAccess.dll.
  • Oracle.ManagedDataAccessDTC.dll must not be referenced by the application.
  • On a 64-bit OS, only the x64 version of Oracle.ManagedDataAccessDTC.dll is placed into the GAC upon the completion of an OUI install or an invocation of the XCopy configure.bat.

Configuration File Format

The ODP.NET, Managed Driver configuration file section name is <oracle.manageddataaccess.client> as compared to <oracle.dataaccess.client> in ODP.NET, Unmanaged Driver. 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" ?>
    <version number="*">
    <version number="">

'version' Section

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=""> section parameters will be applicable only for those applications using ODP.NET, Managed Driver assembly

There can also be a generic section with X = “*” (i.e. <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 generic section's parameters. Below is an example.
  <version number="*">
	<setting name="TraceOption" value="1"/>
	<setting name="PerformanceCounters" value="0" />
  <version number="">
	<setting name="PerformanceCounters" value="4095" />
An application referencing ODP.NET, Managed Driver has the following values set:
TraceOption = 1
PerformanceCounters = 4095

All other versions will have the following values set:
TraceOption = 1
PerformanceCounters = 0

'dataSources' Section

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. Below is an example.
  <dataSource alias="inst1" descriptor="(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)......)))"/>
  <dataSource alias="inst2" descriptor="(DESCRIPTION= ......)))"/>

The following precedence order is followed to resolve the data source alias specified in the 'Data Source' attribute in the connection string. NOTE: app/web.config setting takes precedence over machine.config.

1. data source alias in the 'dataSources' section under <oracle.manageddataaccess.client> section in the .NET config file.
2. data source alias in the tnsnames.ora file at the location specified by 'TNS_ADMIN' in the .NET config file.
3. data source alias in the tnsnames.ora file present in the same directory as the .exe.
4. data source alias in the tnsnames.ora file present at %TNS_ADMIN% (where %TNS_ADMIN% is an environment variable setting).
5. data source alias in the tnsnames.ora file present at %ORACLE_HOME%\network\admin (where %ORACLE_HOME% is an environment variable setting).

NOTE: The "data source" connection string attribute can alternatively be set to a full descriptor or EZ Connect syntax rather than a data source alias, which need to be resolved using the above precedence rule.

The following keywords are supported within the descriptor setting:

1. ADDRESS_LIST (Note: Failover supported)
2. DESCRIPTION_LIST (Note: Failover supported; Address_list load balancing not supported)
5. PROTOCOL (Note: "tcp" and "tcps" are supported)
6. HOST (Note: <hostname>, <IPv6 literal>, and <IPv4 literal> are supported)
8. IP (Note: "loopback" is supported)
9. SDU (Note: 256 to 65536 are supported)
10. TRANSPORT_CONNECT_TIMEOUT (Note: overrides tcp.connect_timeout)
11. SECURITY: SSL_VERSION (Note: overrides sqlnet.ora:ssl_version)

Note: SSL is only supported via method MCS and as a transport.
Note: Only NTS authentication is supported. RADIUS and Kerberos authentication are not supported.
Note: Only SQL*Net and Easy Connect naming are supported. There is no LDAP/Active Directory support.
Note: No bequeath ('beq') support. Default address is instead TCP loopback with port 1521 and Oracle service name is obtained from environment or configruation file via the "ORACLE_SID" setting.

Requirements for connecting to a local database WITHOUT specifying "data source" connection string attribute:

1. The listener must be up and running.
2. ORACLE_SID must be configured appropriately through the configuration file or the environment.

NOTE: When "data source" connection string attribute is not specified, protocol defaults to 'tcp' and port defaults to '1521'.

'settings' section

This section can appear only under a <version> section. Any ODP.NET, Managed Driver specific settings should appear in this section. Below is an example.
  <setting name="TraceLevel" value="7" />
  <setting name="TraceOption" value="1"/>
  <setting name="TNS_ADMIN" value="C:\oracle\network\admin"/>
Below is a list of ODP.NET, Managed Driver configuration settings that are supported:

1. FetchSize
2. DbNotificationPort
3. DemandOraclePermission
4. MaxStatementCacheSize
5. MetaDataXml
6. PerformanceCounters
7. SelfTuning
8. StatementCacheSize
9. TNS_ADMIN : Location where tnsnames.ora and/or sqlnet.ora are located.
10. TraceFileLocation : Trace file destination location. This is different from ODP.NET, Unmanaged Driver, which supports TraceFileName.
11. TraceLevel : 1 = public APIs; 2 = private APIs; 4 = network APIs/data. These values can be ORed. To enable everything, set TraceLevel to 7. Errors will always be traced.
12. TraceOption
17. WALLET_LOCATION : Only "METHOD" supported is MCS
18. SQLNET.AUTHENTICATION_SERVICES : Only supported values are NTS and null/empty/not-specified.

For more information on these settings, reference ODP.NET Developer's Guide and Oracle Database Net Services Reference

'implicitRefCursor' section

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. Below is an example.
  <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 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" />

   <!--Next stored procedure information-->
   <storedProcedure name=”TestProc2”>

'distributedTransaction' section

This section can appear only under a <version> section. Any information about distributed transactions should appear in this section. Below is an example.
  <setting  name="recoveryerviceHost" value="my-pc" />
  <setting name="recoveryservicePort" value="2040" />
The RecoveryServiceHost attribute specifies the host machine name that has a running recovery service. The RecoveryServicePort attribute specifies the port that the recovery service is listening on. The port specified in the managed provider section need to match the port configured with the OraMTS Recovery Service. By default, RecoveryServiceHost is set to the name of the local host if none is specified. By default, RecoveryServicePort is set to 2030, if none is specified.

'edmMappings' section

This section can appear only under a <version> section. Any information related to EDM mappings should appear in this section. Below is an example.
  <edmMapping dataType="number">
    <add name="bool" precision="1"/>
    <add name="byte" precision="2" />
    <add name="int16" precision="5" />



Features Not Supported in ODP.NET, Managed Driver

    Namespace Classes / Enumerations / Interfaces Unsupported Method / Property / Event
    Oracle.ManagedDataAccess.Client FailoverEvent enumeration All
    Oracle.ManagedDataAccess.Client FailoverReturnCode enumeration All
    Oracle.ManagedDataAccess.Client FailoverType enumeration All
    Oracle.ManagedDataAccess.Client OracleAQAgent class All
    Oracle.ManagedDataAccess.Client OracleAQDequeueuMode enumeration All
    Oracle.ManagedDataAccess.Client OracleAQDequeueOptions class All
    Oracle.ManagedDataAccess.Client OracleAQEnqueueOptions class All
    Oracle.ManagedDataAccess.Client OracleAQMessage class All
    Oracle.ManagedDataAccess.Client OracleAQMessageAvailableEventArgs class All
    Oracle.ManagedDataAccess.Client OracleAQMessageAvailableEventHandler class All
    Oracle.ManagedDataAccess.Client OracleAQMessageDeliveryMode enumeration All
    Oracle.ManagedDataAccess.Client OracleAQMessageState enumeration All
    Oracle.ManagedDataAccess.Client OracleAQMessageType enumeration All
    Oracle.ManagedDataAccess.Client OracleAQNavigationMode enumeration All
    Oracle.ManagedDataAccess.Client OracleAQNotificationGroupingType enumeration All
    Oracle.ManagedDataAccess.Client OracleAQNotificationType enumeration All
    Oracle.ManagedDataAccess.Client OracleAQQueue class All
    Oracle.ManagedDataAccess.Client OracleAQVisibilityMode All
    Oracle.ManagedDataAccess.Client OracleBulkCopy All
    Oracle.ManagedDataAccess.Client OracleBulkCopyColumnMapping class All
    Oracle.ManagedDataAccess.Client OracleBulkCopyColumnMappingCollection class All
    Oracle.ManagedDataAccess.Client OracleBulkCopyOptions class All
    Oracle.ManagedDataAccess.Client OracleCommand XmlCommandType property
    Oracle.ManagedDataAccess.Client OracleCommand XmlQueryProperties property
    Oracle.ManagedDataAccess.Client OracleCommand XmlSaveProperties property
    Oracle.ManagedDataAccess.Client OracleConnection FlushCache() method
    Oracle.ManagedDataAccess.Client OracleConnection Failover event
    Oracle.ManagedDataAccess.Client OracleConnection ConnectionType property
    Oracle.ManagedDataAccess.Client OracleConnectionType enumeration All
    Oracle.ManagedDataAccess.Client OracleDBShutdownMode enumeration All
    Oracle.ManagedDataAccess.Client OracleDBStartupMode enumeration All
    Oracle.ManagedDataAccess.Client OracleDataReader GetOracleRef() method
    Oracle.ManagedDataAccess.Client OracleDataReader GetOracleBlobForUpdate() method
    Oracle.ManagedDataAccess.Client OracleDataReader GetOracleClobForUpdate() method
    Oracle.ManagedDataAccess.Client OracleDataReader GetOracleXmlType() method
    Oracle.ManagedDataAccess.Client OracleDataAdapter SafeMapping property
    Oracle.ManagedDataAccess.Client OracleDatabase All
    Oracle.ManagedDataAccess.Client OracleDbType enumeration Array
    Oracle.ManagedDataAccess.Client OracleDbType enumeration Object
    Oracle.ManagedDataAccess.Client OracleDbType enumeration Ref
    Oracle.ManagedDataAccess.Client OracleFailoverEventArgs class All
    Oracle.ManagedDataAccess.Client OracleFailoverEventHandler class All
    Oracle.ManagedDataAccess.Client OracleGlobalization class ClientCharacterSet property
    Oracle.ManagedDataAccess.Client OracleGlobalization class GetClientInfo() method
    Oracle.ManagedDataAccess.Client OracleGlobalization class GetThreadInfo() method
    Oracle.ManagedDataAccess.Client OracleGlobalization class SetThreadInfo() method
    Oracle.ManagedDataAccess.Client OracleNotificationRequest class GroupingInterval property
    Oracle.ManagedDataAccess.Client OracleNotificationRequest class GroupingNotificationEnabled property
    Oracle.ManagedDataAccess.Client OracleNotificationRequest class GroupingType property
    Oracle.ManagedDataAccess.Client OracleRowsCopiedEventArgs class All
    Oracle.ManagedDataAccess.Client OracleRowsCopiedEventHandler class All
    Oracle.ManagedDataAccess.Client OracleXmlCommandType enumeration All
    Oracle.ManagedDataAccess.Client OracleXmlQueryProperties class All
    Oracle.ManagedDataAccess.Client OracleXmlSaveProperties class All
    Oracle.ManagedDataAccess.Types IOracleArrayTypeFactory interface All
    Oracle.ManagedDataAccess.Types IOracleCustomType interface All
    Oracle.ManagedDataAccess.Types IOracleCustomTypeFactory interface All
    Oracle.ManagedDataAccess.Types OracleArrayMappingAttribute class All
    Oracle.ManagedDataAccess.Types OracleCustomTypeMappingAttribute class All
    Oracle.ManagedDataAccess.Types OracleObjectMappingAttribute class All
    Oracle.ManagedDataAccess.Types OracleRef class All
    Oracle.ManagedDataAccess.Types OracleTimestampTZ struct OracleTimeStampTZ(DateTime dt, string timeZone) constructor. This constructor is supported but the timeZone must be an hour offset.
    Oracle.ManagedDataAccess.Types OracleUdt class All
    Oracle.ManagedDataAccess.Types OracleUdtFetchOption enumeration All
    Oracle.ManagedDataAccess.Types OracleUdtStatus enumeration All
    Oracle.ManagedDataAccess.Types OracleXmlStream class All
    Oracle.ManagedDataAccess.Types OracleXmlType class All

Other Differences between ODP.NET, Managed Driver and ODP.NET, Unmanaged Driver

    Feature Category Difference compared to ODP.NET, Unmanaged Driver
    Configuration Configuration file format is different. See Configuration File Format section above.
    Configuration 'Oracle.ManagedDataAccess.Client.Configuration.Section.xsd' file, shipped with ODP.NET, Managed Driver enables intellisense when modifying/updating .NET configuration file.
    Configuration Registry-based confguration is not supported
    Configuration HA & RLB notifications Oracle Notification Service (ONS). Thus, to use HA or RLB, configure database and client to use ONS, rather than AQ. Note that change notification will continue to use AQ.
    Configuration Parameter Edition is not supported.
    Configuration Parameter CheckConStatus is not supported.
    Configuration Parameter DllPath is not supported.
    Configuration Parameter SatementCacheWithUdts is not supported.
    Configuration Parameter ThreadPoolMaxSize is not supported.
    Configuration Parameter TraceFileName has been replaced by TraceFileLocation.
    Configuration Parameter UdtCacheSize is not supported.
    Configuration Parameter UDT Mapping is not supported.
    Connection String Context Connection is not supported.
    Connection String Enlist=dynamic will behave the same as Enlist=false.
    Connection String Promotable Transaction setting will be ignored. It will always be set to "promotable" and always support promotions.
    Connection String Statement Cache Purge is not supported.
    Connectivity Connection to Oracle Times Ten Database is not supported
    Performance Monitor NumberOfStatisConnections performance counter is not supported.
    Performance Monitor Performance monitor category name is "ODP.NET, Managed Driver"
    Provider Types Provider Types accept (via constructors) and generate (via ToString() methods) only culture-invariant strings
    Tracing Trace file name format is: <process_name>_PID_<process_id>_DATE_<date>_TIME_<time>.trc.
    Tracing Dyanmic tracing is enabled by changing the TraceLevel setting in the app/web/machine.config. NOTE: For ASP.NET applications, doing so will recycle the appdomain.
    Tracing An eventlog entry is generated indicating where the trace file is created or if ODP.NET, Managed Driver had issues creating one.



1. Updating multiple long columns in multiple rows with data > 4k does not work with this release of ODP.NET, Managed Driver. [Bug 14304263]

2. OracleConnection object's OpenWithNewPassword() method invocation will result in an ORA-1017 error [Bug 14311412]



1. Interval Day to Second and Interval Year to Month column values cannot be compared to literals in a WHERE clause of a LINQ to Entities or an Entity SQL query.

2. LINQ to Entities and Entity SQL (ESQL) queries that require the usage of SQL APPLY in the generated queries will cause SQL syntax error(s) if the Oracle Database being used does not support APPLY. In such cases, the inner exception message will indicate that APPLY is not supported by the database.

3. ODP.NET does not currently support wildcards that accept character ranges for the LIKE operator in Entity SQL (i.e. [] and [^]). [Bug 11683837]

4. ODP.NET does not support Code First or the DbContext APIs.

5. Executing LINQ or ESQL query against tables with one or more column names that are close to or equal to the maximum length of identifiers (30 bytes) may encounter "ORA-00972: identifier is too long" error, due to the usage of alias identifier(s) in the generated SQL that exceed the limit.

6. An "ORA-00932: inconsistent datatypes: expected - got NCLOB" error will be encountered when trying to bind a string that is equal to or greater than 2,000 characters in length to an XMLType column or parameter. [Bug 12630958]

7. An "ORA-00932 : inconsistent datatypes" error can be encountered if a string of 2,000 or more characters, or a byte array with 4,000 bytes or more in length, is bound in a WHERE clause of a LINQ/ESQL query. The same error can be encountered if an entity property that maps to a BLOB, CLOB, NCLOB, LONG, LONG RAW, XMLTYPE column is used in a WHERE clause of a LINQ/ESQL query.

8. An "Arithmetic operation resulted in an overflow" exception can be encountered when fetching numeric values that have more precision than what the .NET type can support. In such cases, the LINQ or ESQL query can "cast" the the value to a particular .NET or EDM type to limit the precision and avoid the exception. This approach can be useful if the LINQ/ESQL query has computed/calculated columns which will store up to 38 precision in Oracle, which cannot be represented as .NET decimal unless the value is casted.

9. Oracle Database treats NULLs and empty strings the same. When executing string related operations on NULLS or empty strings, the result will be NULL. When comparing strings with NULLs, use the equals operator (i.e. "x == NULL") in the LINQ query, which will in turn use the "IS NULL" condition in the generated SQL that will appropriately detect NULL-ness.

10. If an exception message of "The store provider factory type 'Oracle.ManagedDataAccess.Client.OracleClientFactory' does not implement the IServiceProvider interface." is encountered when executing an Entity Framework application with ODP.NET, the machine.config requires and entry for ODP.NET under the section. To resolve this issue by adding an entry in the machine.config, reinstall ODAC.

Oracle has a very active research organization (Oracle Labs) that is charged to 'Identify, explore, and transfer new technologies that have the potential to substantially improve Oracle's business'. One part of the organization is the External Research Office (ERO). The ERO is charged to ' ... invest in research collaborations that fit Oracle's long-term strategic goals. These collaborations are between university researchers and engineers/researchers throughout Oracle's various organizations'. The ERO webpage lists numerous current and past collaborations. Oracle provides funds and direct interactions with highly experienced developers.

If you are interested in the ERO program please contact Steve Jeffreys at

If you would like to explore opportunities for a research collaboration with the database team please contact Dieter Gawlick at

or Garret Swart at
Oracle Database Cloud