BizTalk Server: WCF Adapters and Troubleshooting

  • Article

Overview and Architecture

The BizTalk Windows Communication Foundation (WCF) adapters allow BizTalk Server to communicate with WCF-based applications. The WCF receive adapter instantiates a ServiceHost object for each WCF receive location. Thus a WCF receive location acts as a WCF service. These ServiceHost objects live inside the BizTalk process (BTSNTSvc.exe or BTSNTSvc64.exe) or inside an IIS worker process (w3wp.exe). A send port acts as a WCF client; the send port configuration contains information about the WCF service such as URI and action. At run time, the WCF send adapter calls WCF channel-layer APIs to communicate with the WCF service.

The BizTalk WCF adapters include five physical adapters: WCF-BasicHttp, WCF-WsHttp, WCF-NetTCP, WCF-NetNamedPipe, and WCF-NetMSMQ. They represent the WCF predefined bindings (BasicHttpBinding, WsHttpBinding, NetTcpBinding, NetNamedPipeBinding, and NetMsmqBinding) and let you easily configure information for most application requirements. The BizTalk WCF adapters also include the WCF-Custom adapter and WCF-CustomIsolated adapter, which you can use to create your own bindings. WCF adapters provide the support for WS-* standards such as WS-Addressing, WS-Security, and WS-AtomicTransaction. WS-ReliableMessaging is not supported.

Additionally, BizTalk Server supplies two tools: the BizTalk WCF Service Publishing Wizard and the BizTalk WCF Service Consuming Wizard. You can use the BizTalk WCF Service Publishing Wizard to create and publish BizTalk orchestrations as WCF services, and to publish schemas as WCF services. You can use the BizTalk WCF Service Consuming Wizard to generate BizTalk Server artifacts, such as orchestrations and types, to consume a WCF service based on the metadata of the WCF service.

Troubleshooting

1. The WCF-send adapter requires request-reply operations even when used on one-way send ports. WCF service operations, which the BizTalk send port calls, can return void but they shouldn’t be marked with IsOneWay=true. The only exception is when you are using NetMsmqBinding, which requires that the service operations be one-way.

2. The WCF send port may return the following error:

The adapter failed to transmit message going to send port "MySendPort" with URL "http://my.com/my.svc". It will be retransmitted after the retry interval specified for this Send Port. Details:"System.InvalidOperationException: An action mapping was defined but BTS.Operation was not found in the message context.

This problem occurs when the BizTalk run time cannot find the action for the outgoing message. Action mapping in the port configuration has this format:

<BTSActionMapping>
     <Operation Name="Operation1" Action="Action1">
     <Operation Name="OperationN" Action="ActionN">
</BTSActionMapping>

For the run time to find the correct action for the outgoing message, the operation name of the orchestration logical port must match one of the operation names in the preceding mapping.

Behind the scenes, the orchestration instance dynamically sets the BTS.Operation property of the outgoing message with the operation name of the logical port. Alternatively, you can programmatically set the message content property BTS.Operation to one of the operation names of the mapping.

  1. The out-of-the-box WCF adapter does not support ProtectionLevel setting in ServiceContractAttribute, OperationContractAttribute, and MessageContractAttribute. You can create a custom behavior to handle this situation. The WCF Adapter port configuration allows you to specify custom behaviors for WCF-Custom Transport. See WCF-Custom Transport Properties Dialog Box, Receive, Binding Tab and WCF-Custom Transport Properties Dialog Box, Send, Behavior Tab.

4. In BizTalk Server 2006 R2, the WCF adapter does not follow the transaction time-out setting in the Machine.config file. The WCF adapter has a maximum transaction time-out setting of 60 minutes. The transaction time-out setting is not changed, even if the transaction time-out setting in the Machine.config file is more than 60 minutes. This issue is fixed in http://support.microsoft.com/kb/942612.

5. WCF-Custom and WCF-CustomIsolated adapters after BizTalk Server 2006 R2 SP1 can look up custom behavior and/or binding extensions from locations other than machine.config. They are configured in WCF adapter handlers, and can be imported and exported. See New Features in BizTalk Server 2006 R2 Service Pack 1.

  1. You can create your own WCF bindings to be used with WCF-Custom and WCF-CustomIsolated adapters. You can also use the WCF LOB Adapter SDK to help you create custom bindings for specifically connecting to line-of-business (LOB) systems.

See Also

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