Oracle® Database

Using Oracle Client for Microsoft Tools

Release 19c
F84376-01
October 2023
Oracle Database Using Oracle Client for Microsoft Tools, Release 19c

F84376-01

Copyright © 2023, 2023, Oracle and/or its affiliates.

Primary Authors: Alex Keh, Pedro Torres, Nari Akiyama

Contributing Authors: CM Dietrich

This software and related documentation are provided under a license agreement containing restrictions on
use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your
license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license,
transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse
engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is
prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If
you find any errors, please report them to us in writing.

If this is software, software documentation, data (as defined in the Federal Acquisition Regulation), or related
documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S.
Government, then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs (including any operating system, integrated software,
any programs embedded, installed, or activated on delivered hardware, and modifications of such programs)
and Oracle computer documentation or other Oracle data delivered to or accessed by U.S. Government end
users are "commercial computer software," "commercial computer software documentation," or "limited rights
data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental
regulations. As such, the use, reproduction, duplication, release, display, disclosure, modification, preparation
of derivative works, and/or adaptation of i) Oracle programs (including any operating system, integrated
software, any programs embedded, installed, or activated on delivered hardware, and modifications of such
programs), ii) Oracle computer documentation and/or iii) other Oracle data, is subject to the rights and
limitations specified in the license contained in the applicable contract. The terms governing the U.S.
Government's use of Oracle cloud services are defined by the applicable contract for such services. No other
rights are granted to the U.S. Government.

This software or hardware is developed for general use in a variety of information management applications.
It is not developed or intended for use in any inherently dangerous applications, including applications that
may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you
shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its
safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this
software or hardware in dangerous applications.

Oracle®, Java, and MySQL are registered trademarks of Oracle and/or its affiliates. Other names may be
trademarks of their respective owners.

Intel and Intel Inside are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are
used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Epyc,
and the AMD logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered
trademark of The Open Group.

This software or hardware and documentation may provide access to or information about content, products,
and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly
disclaim all warranties of any kind with respect to third-party content, products, and services unless otherwise
set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be
responsible for any loss, costs, or damages incurred due to your access to or use of third-party content,
products, or services, except as set forth in an applicable agreement between you and Oracle.
Contents

1 Installing and Configuring Oracle Client for Microsoft Tools

1.1 About Oracle Client for Microsoft Tools 1-1
1.1.1 Example: Determining the Bitness of a Microsoft Product 1-2
1.2 Installing Oracle Client for Microsoft Tools 1-2

2 Database Client Configuration Files

2.1 Setting Up On-Premises Databases 2-1
2.2 Setting Up Oracle Autonomous Database 2-2

3 Connecting with Microsoft Tools

3.1 Microsoft Power BI Desktop 3-1
3.1.1 Validating Power BI Connects to Oracle DB 3-1
3.2 Microsoft Power BI Service 3-4
3.2.1 Installing and Configuring Power BI Gateway 3-5
3.2.2 Validating Power BI Connects to Oracle DB 3-10
3.3 Performance Tuning for Large Data Retrievals 3-13
3.3.1 Performance Tuning for Unmanaged ODP.NET 3-13
3.3.2 Performance Tuning for Managed ODP.NET 3-14

Index

iii
1
Installing and Configuring Oracle Client for
Microsoft Tools
Learn about Oracle Client for Microsoft Tools, including determining the correct install type
and installation instructions.
• About Oracle Client for Microsoft Tools
Learn about Oracle Client for Microsoft Tools, supported Microsoft tools, and how to
select the appropriate Oracle Client for Microsoft Tools install type.
• Installing Oracle Client for Microsoft Tools
General steps for installing Oracle Client for Microsoft Tools.

1.1 About Oracle Client for Microsoft Tools

Learn about Oracle Client for Microsoft Tools, supported Microsoft tools, and how to select
the appropriate Oracle Client for Microsoft Tools install type.

Introduction
Oracle Client for Microsoft Tools (OCMT) is a graphical installer that automates the
installation and configuration of Oracle Data Provider for .NET (ODP.NET) to support
Microsoft tool connections with Oracle on-premises and cloud databases, including Oracle
Autonomous Database (ADB) Serverless. OCMT supports multiple Microsoft tools, including:
• Power BI Desktop
• Power BI service
• Excel
• SQL Server Analysis Services
• SQL Server Data Tools
• SQL Server Integration Services
• SQL Server Reporting Services
• BizTalk Server
These instructions work for on-premises database and both dedicated and serverless ADB.
The instructions for on-premises database setup also apply to Oracle Database Cloud
Services and Oracle Exadata Cloud Service.

Compatibility
Power BI Desktop, Power BI service, Excel, SQL Server Analysis Services, and BizTalk
Server use unmanaged ODP.NET to connect to Oracle database. If you use a 64-bit product,
you must use 64-bit OCMT to install 64-bit unmanaged ODP.NET. If you use a 32-bit
Microsoft product, you must use 32-bit OCMT to install 32-bit unmanaged ODP.NET.
SQL Server Data Tools, SQL Server Integration Services, and SQL Server Reporting
Services use managed ODP.NET. Managed ODP.NET works with both 32-bit and 64-bit

1-1
 Chapter 1
Installing Oracle Client for Microsoft Tools

apps, which allows you to use either 32-bit or 64-bit OCMT with any of these Microsoft
products.
• Example: Determining the Bitness of a Microsoft Product
Determine the bitness of a Microsoft product.

1.1.1 Example: Determining the Bitness of a Microsoft Product

Determine the bitness of a Microsoft product.
If you are using unmanaged ODP.NET, determine whether you are using the 32-bit
Microsoft product or the 64-bit Microsoft product so you can install the matching
bitness of ODP.NET.
Let's use Power BI Desktop as an example. In Windows, start Power BI Desktop. On
the menu, select Help , then About to see a window like the following:

The above screenshot notes that this is 64-bit Power BI Desktop. That means 64-bit
unmanaged ODP.NET must be installed and configured for Power BI to connect to an
Oracle Database.
If you are using 32-bit Power BI Desktop instead, you must install 32-bit unmanaged
ODP.NET.

1.2 Installing Oracle Client for Microsoft Tools

General steps for installing Oracle Client for Microsoft Tools.
Determine which bitness of Oracle Client for Microsoft Tools (OCMT) you need to
install. In general, if you use a 32-bit product, you should use 32-bit OCMT. If you use
a 64-bit product, you should use 64-bit OCMT.

Note:
Screenshots may differ slightly between 32-bit OCMT and 64-bit OCMT.

1-2
 Chapter 1
Installing Oracle Client for Microsoft Tools

For more information on selecting the bitness of a product, see About Oracle Client for
Microsoft Tools for general information, or Connecting with Microsoft Tools for information on
the specific tool you are using.
1. From the Oracle Client for Microsoft Tools page, click on the download link:
• For 64-bit unmanaged ODP.NET, choose 64-bit Oracle Client for Microsoft Tools.
• For 32-bit unmanaged ODP.NET, choose 32-bit Oracle Client for Microsoft Tools.
• For managed ODP.NET, you can choose either download.
OCMT downloads to your machine.

2. Find the OCMT executable on your machine and doubleclick it to begin the install
process.

3. Click Yes in the User Account Control screen.

The introductory install screen displays.

1-3
 Chapter 1
Installing Oracle Client for Microsoft Tools

4. Click Next.
5. The OCMT Setup Type screen appears. You have two choices:
• Custom - Decide whether to install and configure only managed ODP.NET,
only unmanaged ODP.NET, or both.
• Default - Both managed and unmanaged ODP.NET are installed and
configured.

1-4
 Chapter 1
Installing Oracle Client for Microsoft Tools

6. Click Next.
7. (Custom only) On the Select Features screen, select an installation option and click
Next:
• Managed ODP.NET - Installs only managed ODP.NET.
• Unmanaged ODP.NET - Installs only unmanaged ODP.NET.
• Both - Installs both managed and unmanaged ODP.NET.

1-5
 Chapter 1
Installing Oracle Client for Microsoft Tools

8. On the Destination Location screen, click Browse and select the installation
directory for ODP.NET.

9. Click Next.

1-6
 Chapter 1
Installing Oracle Client for Microsoft Tools

10. On the Oracle Configuration File Directory screen, click Browse to select the location
of the Oracle Client configuration files, sqlnet.ora and tnsnames.ora, and click Next.
For example, C:\network\admin.

11. If you are connecting to Oracle Autonomous Database Serverless:

a. Download the database connection credentials zip file from the Oracle Cloud
Console.
b. Unzip the contents into the configuration file directory you specified in the previous
step.
c. Open sqlnet.ora.
d. Update the wallet location's DIRECTORY setting value to the same configuration file
directory.
For more information on configuring Oracle database connections with specific
Microsoft tools, see Connecting with Microsoft Tools.
12. Click Install.

1-7
 Chapter 1
Installing Oracle Client for Microsoft Tools

13. (Optional) Select the checkbox to view the README file.

14. Click Finish.

The installation is complete and configured for use on your machine. Your Microsoft
tools can now connect to Oracle databases.

1-8
 Chapter 1
Installing Oracle Client for Microsoft Tools

Note:
For more information on connecting specific Microsoft tools, see Connecting with
Microsoft Tools.

1-9
2
Database Client Configuration Files
Learn about database client configuration files for on-premises database and Oracle
Autonomous Database (ADB).
In order to use Oracle Client for Microsoft Tools, an on-premises Oracle Database or ADB
must already be provisioned. Connecting to Oracle databases on-premises and through ADB
are similar, but there are some variations in the steps needed.
• Setting Up On-Premises Databases
Locate the client configuration files and place them into a specified location on your
machine.
• Setting Up Oracle Autonomous Database
Download your database credentials and unzip the content onto your client machine.

2.1 Setting Up On-Premises Databases

Locate the client configuration files and place them into a specified location on your machine.
To connect to an on-premises database:
1. Locate the configuration files required for your database server setup.
• Typically, ODP.NET requires tnsnames.ora and sqlnet.ora to be accessible to
connect to the database server. These files can be copied from another Oracle
database client that connects to the target database server.
• Alternatively, an Easy Connect or Easy Connect Plus string can be used in lieu of
credential files for on-premises databases. If you use Easy Connect (Plus), you can
skip the credential file downloading and setup steps.
For example, the Power BI Desktop Server configuration setting accepts an Easy
Connect string with the following format:

<DB hostname>:<Port>/<Service Name>

2. Place the client configuration files on your Windows machine into a directory, and note
the directory location.
For example, C:\data\wallet.

2-1
 Chapter 2
Setting Up Oracle Autonomous Database

If your on-premises database requires a wallet or additional configuration, be sure

to update your tnsnames.ora, sqlnet.ora, or other configuration files accordingly.
The credentials are now available, and you can continue with the configuration of your
specific Microsoft tool.

2.2 Setting Up Oracle Autonomous Database

Download your database credentials and unzip the content onto your client machine.
In order to use Oracle Client for Microsoft Tools (OCMT), Autonomous Database
(ADB) must already be provisioned.
You need access to the Oracle Cloud Console that has access to your ADB instance.
1. Go to the cloud console screen for the ADB instance you connect to.
2. Start your ADB instance.
3. Click Database Connection.
4. Click Download Wallet.
5. Supply the wallet password. Confirm the password, and click Download.
6. Download the ADB credentials zip file to the machine that has your Microsoft tool
installed.
OCMT uses these credential files (cwallet.sso, tnsnames.ora, and sqlnet.ora)
to connect your Microsoft tool to ADB.

2-2
 Chapter 2
Setting Up Oracle Autonomous Database

7. Unzip the credentials, and place them on your Windows machine into a directory. Note
the directory location.
For example, C:\data\wallet.

8. If you are connecting to one ADB instance:

a. From the credentials directory, open sqlnet.ora in a text editor.
b. Locate the following line: WALLET_LOCATION = (SOURCE = (METHOD = file)
(METHOD_DATA = (DIRECTORY=?/network/admin)))
c. Set the DIRECTORY value to the ADB wallet directory.
For example,

WALLET_LOCATION = (SOURCE = (METHOD = file) (METHOD_DATA =

(DIRECTORY=C:\DATA\WALLET)))

9. If you are connecting to multiple ADB instances:

a. Ensure that each ADB instance is set up with a different wallet.
b. In each wallet location, add the parameter WALLET_LOCATION to each connect
descriptor in tnsnames.ora.
c. After making your changes, save the file.
For example:

adwptr_high =
(description=(retry_count=20)(retry_delay=3)(address=(protocol=tcps)
(port=1522)(host=host name))
(connect_data=(service_name=service name))

2-3
 Chapter 2
Setting Up Oracle Autonomous Database

(security=(ssl_server_dn_match=yes)
(WALLET_LOCATION=C:\DATA\WALLET\ADWPTR)))

adwbi_high =
(description=(retry_count=20)(retry_delay=3)(address=(protocol=tcps)
(port=1522)(host=host name))
(connect_data=(service_name=service name))
(security=(ssl_server_dn_match=yes)
(WALLET_LOCATION=C:\DATA\WALLET\ADWBI)))

10. Continue with the configuration of your specific Microsoft tool.

Note:
See Connecting with Microsoft Tools for more detailed information.

2-4
3
Connecting with Microsoft Tools
Learn about connecting Oracle databases to Microsoft tools, including configuration steps.
• Microsoft Power BI Desktop
Configure Microsoft Power BI Desktop to connect to Oracle Database.
• Microsoft Power BI Service
Configure Microsoft Power BI Service to connect to Oracle Database.
• Performance Tuning for Large Data Retrievals
Recommendations for improving Oracle database retrieval performance with Microsoft
tools.

3.1 Microsoft Power BI Desktop

Configure Microsoft Power BI Desktop to connect to Oracle Database.
Microsoft Power BI Desktop uses unmanaged Oracle Data Provider for .NET (ODP.NET)
for data access. You can configure Microsoft Power BI Desktop to access on-premises
database and both dedicated and serverless ADB. The instructions for on-premises
databases setup also apply to Oracle Database Cloud Services and Oracle Exadata Cloud
Service.

Overview
The general steps to set up Oracle database connectivity with Microsoft Power BI Desktop
are:
1. Provision Oracle database or ADB.
2. Download database credentials to Windows client. (See Database Client Configuration
Files.)
3. Install Power BI on Windows client.
4. Install and configure ODP.NET on Windows client with OCMT. (See Installing and
Configuring Oracle Client for Microsoft Tools.)
5. Validate Power BI connects to Oracle database or ADB.
This section covers how to complete step 5, and assumes you have already completed steps
1-4. Database Client Configuration Files covers step 2. Installing and Configuring Oracle
Client for Microsoft Tools covers step 4.
• Validating Power BI Connects to Oracle DB
Validate the Power BI Desktop connection to Oracle Database by setting up the
connection from Power BI Desktop.

3.1.1 Validating Power BI Connects to Oracle DB

Validate the Power BI Desktop connection to Oracle Database by setting up the connection
from Power BI Desktop.

3-1
 Chapter 3
Microsoft Power BI Desktop

1. Open Power BI Desktop.

2. On the menu bar, click Get data, More....

3. Select Database, Oracle database, Connect.

3-2
 Chapter 3
Microsoft Power BI Desktop

4. In the Server text box, enter your database net service name or an Easy Connect (Plus)
string.
If you are using a tnsnames.ora file with your Oracle database, open the file to see which
ADB or database net service names you can connect to. The screenshot shows three
different ones: adwptr_high, adwptr_low, and adwptr_medium. Use one of these values
for the server name.

5. Set any other Power BI settings needed on this screen.

6. Click OK.
7. Select Database and enter your database credentials.

Note: Oracle Autonomous Database Serverless, new Oracle Database 19c release
updates, and Oracle Database 23c support Microsoft Entra ID/Azure Active Directory
connections.
8. Click Connect.

3-3
 Chapter 3
Microsoft Power BI Service

9. To continue, select the schema objects needed for your Microsoft Power BI
Desktop file (.pbix) and load the data.

Congratulations! Powder BI Desktop is connected to ADB or an on-premises Oracle

database. For information on performance tuning for large data retrievals, see
Performance Tuning for Unmanaged ODP.NET.

3.2 Microsoft Power BI Service

Configure Microsoft Power BI Service to connect to Oracle Database.
Microsoft Power BI Service runs in the Microsoft 365 cloud. Power BI service uses an
on-premises data gateway, also known as Power BI gateway, to connect the Power
BI service to Oracle databases. The gateway is hosted on Windows, either on-
premises or in a cloud virtual machine, such as in Oracle Cloud Infrastructure or
Azure.
These instructions use 64-bit unmanaged Oracle Data Provider for .NET
(ODP.NET) for data access. They work for on-premises database and both dedicated
and serverless ADB. The instructions for on-premises databases setup also apply to
Oracle Database Cloud Services and Oracle Exadata Cloud Service.

Overview
These are the general steps to setup Oracle database connectivity with Microsoft
Power BI Desktop:
1. Provision Oracle database or ADB.

3-4
 Chapter 3
Microsoft Power BI Service

2. Download database credentials to Windows client. (See Database Client Configuration

Files.)
3. Create Power BI service in Microsoft 365 Cloud.
4. Install and configure Power BI gateway.
5. Install and configure ODP.NET on Windows client with OCMT. (See Installing and
Configuring Oracle Client for Microsoft Tools.)
6. Validate Power BI service connects to Oracle database or ADB.
This section covers how to complete steps 4 and 6, and assumes you have already
completed all other steps. Database Client Configuration Files covers step 2. Installing and
Configuring Oracle Client for Microsoft Tools covers step 5.
• Installing and Configuring Power BI Gateway
Download Power BI Gateway from the Power BI website.
• Validating Power BI Connects to Oracle DB
Configure and validate the Power BI Service connection to Oracle Database.

3.2.1 Installing and Configuring Power BI Gateway

Download Power BI Gateway from the Power BI website.
To install and configure Power BI Gateway:
1. Sign on to the Power BI website with your Microsoft 365 account.

2. From the Power BI web console, click Menu, Download, Data Gateway.

3-5
 Chapter 3
Microsoft Power BI Service

3. Click Download standard mode.

4. After the gateway installation file downloads, run GatewayInstall.exe.

5. Select the installation directory location, and accept the terms.

3-6
 Chapter 3
Microsoft Power BI Service

6. Complete your registration of the Power BI gateway:

a. Enter the email address of your Power BI service account.

b. Sign in.
c. Select Register a new gateway on this computer.

3-7
 Chapter 3
Microsoft Power BI Service

d. Click Next.
e. Name the gateway, provide the recovery key, and confirm the key.
You use the gateway name when creating a Power BI Data Source.

3-8
 Chapter 3
Microsoft Power BI Service

f. Click Configure.
The gateway is now online and ready to use.

3-9
 Chapter 3
Microsoft Power BI Service

3.2.2 Validating Power BI Connects to Oracle DB

Configure and validate the Power BI Service connection to Oracle Database.
1. Log into the Power BI website with your Microsoft 365 account.

2. Navigate to a Power BI Premium or Power BI Pro workspace.

3. Click New, Dataflow.

3-10
 Chapter 3
Microsoft Power BI Service

4. On the Start creating your dataflow screen, select Add new tables.

5. Select Oracle database.

3-11
 Chapter 3
Microsoft Power BI Service

6. Provide the entries to connect to your data source:

a. Server - Enter the database net service name.
For example, adwptr_high, adwptr_low, or the Easy Connect (Plus)
configuration.
For more information, see Setting Up On-Premises Databases.
b. Data gateway - the Power BI gateway name.
For more information, see Installing and Configuring Power BI Gateway.
c. Authentication kind - Basic
d. Username and Password - Your ADB or on-premises database user
credentials

7. Click Next to complete the connection.

3-12
 Chapter 3
Performance Tuning for Large Data Retrievals

8. To continue, select the schema objects needed for your Microsoft Power BI application
and load the data.

Congratulations! Power BI Service now connects to Oracle Database. You can now view the
schema objects by selecting the objects from the tree control. For information on
performance tuning for large data retrievals, see Performance Tuning for Unmanaged
ODP.NET.

3.3 Performance Tuning for Large Data Retrievals

Recommendations for improving Oracle database retrieval performance with Microsoft tools.
Typically, BI and ETL applications retrieve large amounts of data from a source database for
further processing. The ODP.NET FetchSize setting determines the amount of data
ODP.NET fetches into its internal cache upon each database round trip. You can improve
performance by an order of magnitude by significantly increasing FetchSize when retrieving
large result sets.
• Performance Tuning for Unmanaged ODP.NET
Improve performance for unmanaged ODP.NET by increasing FetchSize in the Windows
Registry.
• Performance Tuning for Managed ODP.NET
Improve performance for managed ODP.NET by increasing the FetchSize in the .NET
machine.config file.

3.3.1 Performance Tuning for Unmanaged ODP.NET

Improve performance for unmanaged ODP.NET by increasing FetchSize in the Windows
Registry.
This method works for tools that use unmanaged ODP.NET, including Microsoft Power BI
Desktop, Microsoft Power BI Service, and Microsoft SQL Service Analysis Services.
To increase FetchSize in the Windows Registry:
1. Launch the Windows Registry editor (regedit.exe).

3-13
 Chapter 3
Performance Tuning for Large Data Retrievals

2. Go to the following Registry key:

HKEY_LOCAL_MACHINE\SOFTWARE\Oracle\ODP.NET\4.122.19.1
3. Add the String Value FetchSize and set it to a value larger than the default
(131072), such as 4194304 (4 MB).
FetchSize can be set as large as int.MaxValue.
4. Restart the Microsoft tool and run your queries with the new setting.

3.3.2 Performance Tuning for Managed ODP.NET

Improve performance for managed ODP.NET by increasing the FetchSize in the .NET
machine.config file.
This method works for tools that use managed ODP.NET, including Microsoft SQL
Server Data Tools, Microsoft SQL Service Integration Services, and Microsoft SQL
Server Reporting Services.
To increase FetchSize in the .NET machine.config file:
1. Locate the .NET machine.config file. This file is generally located in one of two
directories. The file you need to modify depends on whether you are running 32-bit
or 64-bit processes.
• For 32-bit, the location is
C:\Windows\Microsoft.NET\Framework\v4.0.30319\Config
• For 64-bit, the location is
C:\Windows\Microsoft.NET\Framework64\v4.0.30319\Config
Modifying the machine.config file requires Windows Administrator privileges.
2. Add an <oracle.manageddataaccess.client> section in the machine.config file
for managed ODP.NET. This section should be placed within the <configuration>
section and after <configSections></configSections>.
This example sets FetchSize to 4 MB. New configuration additions are in bold.

<configuration>
<configSections>
…
</configSections>
<oracle.manageddataaccess.client>
<version number="4.122.19.1">
<settings>
<setting name="FetchSize" value="4194304" />
</settings>
</version>
</oracle.manageddataaccess.client>
</configuration>

3. Restart the Microsoft tool and run your queries with the new setting.

3-14
Glossary

Glossary-1
Index

Index-1