Oracle.ManagedDataAccess NuGet Package 19.11.0 README ===================================================== Release Notes: Oracle Data Provider for .NET, Managed Driver March 2021 This document provides information that supplements the Oracle Data Provider for .NET (ODP.NET) documentation. You have downloaded Oracle Data Provider for .NET from Oracle, the license agreement to which is available at https://www.oracle.com/downloads/licenses/distribution-license.html TABLE OF CONTENTS *New Features *Bug Fixes *Installation and Configuration Steps *Installation Changes *Documentation Corrections and Additions *ODP.NET, Managed Driver Tips, Limitations, and Known Issues Note: The 32-bit "Oracle Developer Tools for Visual Studio" download from https://otn.oracle.com/dotnet is required for Entity Framework design-time features and for other Visual Studio designers such as the TableAdapter Wizard. This NuGet download does not enable design-time tools; it only provides run-time support. This version of ODP.NET supports Oracle Database version 11.2.0.4 and higher. New Features ============ 1) Allowing Deserialization of Oracle Provider Types into DataSet/DataTable This version introduces a new AddOracleTypesDeserialization() method on the OracleConfiguration class. This new method can be called to add ODP.NET-specific data types to the "allow" list, so that they can be deserialized into DataSet/DataTable. If an attempt is made to deserialize ODP.NET-specific types without adding them to the "allow" list, an ODP.NET type initializer exception will be encountered. If your app or third-party software you use adds data types to the allow list as well, be careful not to overwrite the ODP.NET allowed types by appending to the allow list. // C# snippet enbling Oracle data type deserialization, then loading them from an XML file static void Main(string[] args) { OracleConfiguration.AddOracleTypesDeserialization(); DataSet ds = new DataSet(); ds.ReadXml("OracleTypes.xml"); // The xml file name will depend on your application. } 2) Suppress GetDecimal Invalid Cast Exception The SuppressGetDecimalInvalidCastException property has been added to the OracleDataReader and OracleDataAdapter classes in ODP.NET 19.10. It specifies whether to suppress the InvalidCastException and return a rounded-off 28 precision value if the Oracle NUMBER value has more than 28 precision. OracleDataAdapter.SuppressGetDecimalInvalidCastException API description: https://docs.oracle.com/en/database/oracle/oracle-data-access-components/19.3.2/odpnt/DataAdapterSuppressGetDecimalInvalidCastException.html OracleDataReader.SuppressGetDecimalInvalidCastException API description: https://docs.oracle.com/en/database/oracle/oracle-data-access-components/19.3.2/odpnt/DataReaderSuppressGetDecimalInvalidCastException.html 3) Bulk Copy ODP.NET 19.10 now supports bulk copy, which allows fast data transfer between .NET and Oracle databases. It supports the same bulk copy APIs as unmanaged ODP.NET. These APIs are documented in the ODP.NET Developer's Guide. 4) GetDecimalRetainTrailingZeros Configuration Parameter ODP.NET 19.11 supports a config parameter called GetDecimalRetainTrailingZeros that can be set in .NET config or by setting the OracleConfiguration.GetDecimalRetainTrailingZeros property. By default, it's false. If it's set to true, the Oracle NUMBER column value that eventually gets retrieved as a .NET decimal through OracleDataReader's GetDecimal() method will retain a trailing 0 if the number of digits on the right hand side of the decimal point is odd in number. Bug Fixes since Oracle.ManagedDataAccess NuGet Package 19.10.1 ============================================================== 32185056 : ORA-01017 WHILE PASSING PASSWORD WITH TRAILING EQUAL SIGN 32370414 : ENCOUNTER SEMAPHOREFULLEXCEPTION WHEN OPEN CONNECTIONS IN HEAYY LOAD 32466408 : EXPOSE GETDECIMALRETAINTRAILINGZEROS CONFIG Installation and Configuration Steps ==================================== The downloads are NuGet packages that can be installed with the NuGet Package Manager. These instructions apply to install ODP.NET, Managed Driver. 1. Un-GAC and un-configure any existing assembly (i.e. Oracle.ManagedDataAccess.dll) and policy DLL (i.e. Policy.4.122.Oracle.ManagedDataAccess.dll) for the ODP.NET, Managed Driver, version 4.122.19.1 that exist in the GAC. Remove all references of Oracle.ManagedDataAccess from machine.config file, if any exists. 2. In Visual Studio, open NuGet Package Manager from an existing Visual Studio project. 3. Install the NuGet package from NuGet Gallery (nuget.org). From Local Package Source ------------------------- A. Click on the Settings button in the lower left of the dialog box. B. Click the "+" button to add a package source. In the Source field, enter in the directory location where the NuGet package(s) were downloaded to. Click the Update button, then the Ok button. C. On the left side, under the Online root node, select the package source you just created. The ODP.NET NuGet packages will appear. From Nuget.org -------------- A. In the Search box in the upper right, search for the package with id, "Oracle.ManagedDataAccess". Verify that the package uses this unique ID to ensure it is the official Oracle Data Provider for .NET, Managed Driver download. B. Select the package you wish to install. 4. Click on the Install button to select the desired NuGet package(s) to include with the project. Accept the license agreement and Visual Studio will continue the setup. 5. Open the app/web.config file to configure the ODP.NET connection string and connect descriptors. Below is an example of configuring the net service aliases and connect descriptors parameters: After following these instructions, ODP.NET is now configured and ready to use. IMPORTANT: Oracle recommends configuring net service aliases and connect descriptors in a .NET config file to have the application configuration be self-contained rather than using tnsnames.ora or TNS_ADMIN. NOTE: ODP.NET, Managed Driver comes with one set of platform specific assemblies for Kerberos support: Oracle.ManagedDataAccessIOP.dll. The Oracle.ManagedDataAccessIOP.dll assembly is ONLY needed if you are using Kerberos5 based external authentication. Kerberos5 users will need to download MIT Kerberos for Windows version 4.0.1 from https://web.mit.edu/kerberos/dist/ to utilize ODP.NET, Managed Driver's support of Kerberos5. The asssemblies are located under packages\Oracle.ManagedDataAccess.\bin\x64 and packages\Oracle.ManagedDataAccess.\bin\x86 depending on the platform. If these assemblies are required by your application, your Visual Studio project requires additional changes. Use the following steps for your application to use the 64-bit version of Oracle.ManagedDataAccessIOP.dll: 1. Right click on the Visual Studio project. 2. Select Add -> New Folder. 3. Name the folder x64. 4. Right click on the newly created x64 folder. 5. Select Add -> Existing Item. 6. Browse to packages\Oracle.ManagedDataAccess.\bin\x64 under your project solution directory. 7. Choose Oracle.ManagedDataAccessIOP.dll. 8. Click the 'Add' button. 9. Left click the newly added Oracle.ManagedDataAccessIOP.dll in the x64 folder. 10. In the properties window, set 'Copy To Output Directory' to 'Copy Always'. For x86 targeted applications, name the folder x86 and add assemblies from the packages\Oracle.ManagedDataAccess.\bin\x86 folder. To make your application platform independent even if it depends on Oracle.ManagedDataAccessIOP.dll, create both x64 and x86 folders with the necessary assemblies added to them. Installation Changes ==================== The following app/web.config entries are added by including the "Official Oracle ODP.NET, Managed Driver" NuGet package to your application: 1) Configuration Section Handler The following entry is added to the app/web.config to enable applications to add an section for ODP.NET, Managed Driver-specific configuration:
Note: If your application is a web application and the above entry was added to a web.config and the same config section handler for "oracle.manageddataaccess.client" also exists in machine.config but the "Version" attribute values are different, an error message of "There is a duplicate 'oracle.manageddataaccess.client' section defined." may be observed at runtime. If so, the config section handler entry in the machine.config for "oracle.manageddataaccess.client" has to be removed from the machine.config for the web application to not encounter this error. But given that there may be other applications on the machine that depended on this entry in the machine.config, this config section handler entry may need to be moved to all of the application's .NET config file on that machine that depend on it. 2) DbProviderFactories The following entry is added for applications that use DbProviderFactories and DbProviderFactory classes. Also, any DbProviderFactories entry for "Oracle.ManagedDataAccess.Client" in the machine.config will be ignored with the following entry: 3) Dependent Assembly The following entry is created to ignore policy DLLs for Oracle.ManagedDataAccess.dll and always use the Oracle.ManagedDataAccess.dll version that is specified by the newVersion attribute in the element. The newVersion attribute corresponds to the Oracle.ManagedDataAccess.dll version which came with the NuGet package associated with the application. 4) Data Sources The following entry is added to provide a template on how a data source can be configured in the app/web.config. Simply rename "MyDataSource" to an alias of your liking and modify the PROTOCOL, HOST, PORT, SERVICE_NAME as required and un-comment the element. Once that is done, the alias can be used as the "data source" attribute in your connection string when connecting to an Oracle Database through ODP.NET, Managed Driver. Documentation Corrections and Additions ======================================= None ODP.NET, Managed Driver Tips, Limitations, and Known Issues =========================================================== None Copyright (c) 2020, 2021, Oracle and/or its affiliates.