Share via

BizTalk Server: WCF-based Oracle Adapter and Troubleshooting

  • Article

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.

  1. 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.

  1. 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.

  1. 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.

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

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.

8. If there are multiple assemblies with user defined types (UDTs), BizTalk may not be able to send messages to Oracle database. It fails with error:

The adapter failed to transmit message going to send port "MyOracleSendPort" with URL "oracledb://Sample". It will be retransmitted after the retry interval specified for this Send Port.

Details:"System.InvalidOperationException: Custom type mapping for 'TEST _TYPE' is not specified or is invalid.

Server stack trace: *
*

at System.Runtime.AsyncResult.End[TAsyncResult](IAsyncResult result)

at System.ServiceModel.Channels.ServiceChannel.SendAsyncResult.End(SendAsyncResult result)

at System.ServiceModel.Channels.ServiceChannel.EndCall(String action, Object[] outs, IAsyncResult result)

at System.ServiceModel.Channels.ServiceChannel.EndRequest(IAsyncResult result)

Exception rethrown at [0]:

at System.Runtime.Remoting.Proxies.RealProxy.HandleReturnMessage(IMessage reqMsg, IMessage retMsg)

at System.Runtime.Remoting.Proxies.RealProxy.PrivateInvoke(MessageData& msgData, Int32 type)

at System.ServiceModel.Channels.IRequestChannel.EndRequest(IAsyncResult result)

at Microsoft.BizTalk.Adapter.Wcf.Runtime.WcfClient`2.RequestCallback(IAsyncResult result)".

Resolution

This is an ODP.NET limitation. All the UDTs must be in a single assembly. If ODP.NET finds one assembly with UDTs, it doesn't look for additional UDTs.

See Also

Read suggested related topics:

Another important place to find a huge amount of BizTalk related articles is the TechNet Wiki itself. The best entry point is BizTalk Server Resources on the TechNet Wiki