Overview and Architecture

1. There are three WCF-based versions of the Microsoft BizTalk Adapter for Oracle Database available:

• BizTalk Adapter Pack 1.0 (known as BizTalk Adapter 3.0 for Oracle Database in the first version of the Adapter Pack)
• BizTalk Adapter Pack 2.0
• BizTalk Adapter Pack 2010

All three are based on Windows Communication Foundation (WCF). BizTalk Adapter Pack 1.0 works with BizTalk Server 2006 R2. BizTalk Adapter Pack 2.0 works with BizTalk Server 2006 R2 and BizTalk Server 2009. BizTalk Adapter Pack 2010 works with BizTalk Server 2010.  The versions in BizTalk Adapter Pack 2.0 and BizTalk Adapter Pack 2010 have the same functionalities and have some new and deprecated features over the version in BizTalk Adapter Pack 1.0. For more information, see New and Deprecated Features in BizTalk Adapter for Oracle Database.

2. The Microsoft BizTalk Adapter for Oracle Database implements a Windows Communication Foundation (WCF) custom binding, which contains a single custom transport binding element that enables communication with an Oracle database. The Oracle Database adapter is wrapped by the Microsoft Windows Communication Foundation (WCF) Line of Business (LOB) Adapter SDK run time and is exposed to applications through the WCF channel architecture. BizTalk Server or other .NET clients can consume the Oracle Database adapter through WCF programming models. The Oracle Database adapter communicates with the Oracle database through the Oracle Data Provider for .NET (ODP.NET) and the Oracle client. For more information about the end-to-end architecture, see Architecture for BizTalk Adapter for Oracle Database.

3. The non-WCF Oracle Database adapter is deprecated in favor of the WCF-based Oracle Database adapter. The BizTalk Adapter Pack Migration tool can help you get started with the process of migrating projects using the older adapter to use WCF-based projects. After running the tool, you should be able to deploy and run the new project as-is in most simple projects or fix some aspects as per the limitations outlined in the documentation. The tool is available at http://www.microsoft.com/download/details.aspx?id=7840.

Troubleshooting

1. To troubleshoot run-time issues, you can enable WCF tracing with the following configuration setting in BTSNTSvc.exe.config or BTSNTSvc64.exe.config:

<system.diagnostics>
<sources>
<source name="Microsoft.ServiceModel.Channels" switchValue="Error">
<listeners><add name="xml" /></listeners>
</source>
<source name=" Microsoft.Adapters.OracleDB" switchValue="Information">
<listeners><add name="xml" /></listeners>
</source>
</sources>
<sharedListeners>
<add name="xml" type="System.Diagnostics.XmlWriterTraceListener" traceOutputOptions="LogicalOperationStack" initializeData="C:\AdapterTrace.svclog" />
</sharedListeners>
<trace autoflush="true" />
</system.diagnostics>

2. When you use the Oracle Database adapter to receive data from Oracle database, you may notice that transactions are intermittently aborted because of a TimeoutException. This problem usually happens under load.

The resolution is to increase the ReceiveTimeout binding property of the receive location. Always set the ReceiveTimeout property of any Oracle receive location to a large value or the maximum value 24.20:31:23.6470000 (24 days). For more information, see Working with BizTalk Adapter for Oracle Database Binding Properties and Working with BizTalk Adapter 3.0 for Oracle Database Binding Properties.

3. To use the Oracle Database adapter to perform transactions on the Oracle database in BizTalk Adapter Pack 2.0, you first need to install the Oracle Services for Microsoft Transaction Server component on the computer that is running BizTalk Server. Otherwise you may receive the following exception:

Oracle.DataAccess.Client.OracleException Unable to load OraMTS

4. Non-TNS based URI is not supported under ambient transaction in BizTalk Adapter Pack 2.0 and BizTalk Adapter Pack 2010. If you have to use transactions, use the TNS alias with less than 39 characters. Otherwise you may receive the following exception:

Microsoft.ServiceModel.Channels.Common.ConnectionException: Due to an Oracle Client limitation, the adapter failed to open a connection. This is because either:

• Ambient transaction is present and the TNS alias is longer than 39 characters
• Ambient transaction is present and a non-TNS based URI was used.

To resolve this, use a TNS alias to connect to Oracle and make sure it is not more than 39 characters.

5. If you receive an authentication error when connecting to the Oracle database, try to reconnect with user name/password in all capital letters to rule out an issue with case-sensitivity.

6. All three versions of Microsoft BizTalk Adapter for Oracle Database have some limitations:

For version 1, see http://msdn.microsoft.com/library/dd788520(BTS.10).aspx
For version 2, see http://msdn.microsoft.com/library/dd788520(BTS.10).aspx
For version 2010, see http://msdn.microsoft.com/library/dd788520

7. When using the BizTalk Adapter Pack Migration Tool, you may get error:

Event Type: Error
Event Source: .NET Runtime 2.0 Error Reporting
Event ID: 5000
Description: EventType clr20r3, P1 biztalkadapterpackmigrationtool, P2 1.0.0.0, P3 4a26b834, P4 biztalkadapterpackmigrationtool, P5 1.0.0.0, P6 4a26b834, P7 1ba, P8 ef3, P9 system.nullreferenceexception, P10 NIL.

This can happen if a DLL file is referenced instead of being local to the project. After the migration is complete, re-add the referenced DLL file. The BizTalk Adapter Pack Migration Tool is available at http://www.microsoft.com/download/details.aspx?id=7840.

Additional Links

BizTalk: WCF Adapters and Troubleshooting
BizTalk Adapter Pack 2010 - WCF Oracle E-Business Adapter
BizTalk Adapter Pack 2010 - WCF OracleDb Adapter
BizTalk Server Adapter Pack 2010 - Oracle Table Operations