Export (0) Print
Expand All

Troubleshooting Adapters

Adapter creation fails

Problem: The adapter creation fails.

Cause: References to assemblies cannot be resolved.

Resolution: Use fuslogvw.exe to determine if there are references to assemblies that cannot be resolved.

Address (URI) values in user interface and code do not match

Problem: The URI value shown in BizTalk Explorer does not match the ReceiveLocation.Address property or the TransportInfo.Address property in the BizTalk Explorer Object Model.

Resolution: If you change the Address (URI) value by using Windows Management Instrumentation (WMI) or the BizTalk Explorer Object Model, you should always use those same methods to retrieve the correct value.

Messaging Engine fails to submit a message to the MessageBox

Problem: When submitting a message from a custom adapter to the MessageBox, the Messaging Engine fails to submit the message.

Cause: Nonserializable objects cannot be assigned to a message context property.

Resolution: Do not assign nonserializable objects to a message context property.

Property description is truncated on adapter property page

Problem: In an adapter property page, the description for a property is truncated.

Cause: The property description is longer than the default measurements for the description pane.

Resolution: Resize the description pane by moving the double-headed arrow that appears on the top border of the pane.

Digest Authentication is not working in IIS 5.0

Problem: Digest authentication is not working as expected in IIS 5.0

Resolution: Enable digest authentication programmatically using the following script:

public static void EnableDigestSSP(bool enable)
         // Get the IISWebService object
         DirectoryEntry service=new DirectoryEntry("IIS://localhost/W3SVC");

Troubleshooting Receive Adapters

Batch fails

Problem: An adapter batch fails (the BatchComplete method fails).

Resolution: The adapter gets three types of HRESULTs when Messaging Engine calls the BatchComplete method:

  • Batch HRESULT. The batch passed or failed.
  • Operation HRESULT. Typically adapters are not required to code against this.
  • Message HRESULT. The message is valid or not valid.

If BATCH FAILS (Batch HRESULT < 0) then the adapters should loop through the messages. For every message, if the operation was SubmitMessage, SubmitRequestMessage or SubmitResponseMessage:

  1. If message HRESULT == S_OK, then adapter can retry the operation. This assumes that the original adapter stream is seekable. In the case where it is not seekable, the adapter cannot perform any action.
  2. If message HRESULT == S_FALSE. This means that this message was being suspended due to pipeline failure. However, the operation failed because some other message in the batch was bad. The adapter can call the MoveToSuspendQ method on the message to explicitly move the message to suspendQ.
  3. If message HRESULT == BTS_S_SECURITY_CHECK_FAILED. This means that the message had a security issue and the receive port is marked as “Authentication Required Drop message”. The original operation should not be retried.
    • Adapters like FILE should delete the message from the receive location.
    • Other adapters like HTTP should return an “Access Denied” error.
  4. If message HRESULT < 0 then adapter can report a failure back to its client (if one exists), and then try to suspend the message using the MoveToSuspendQ method.

If the operation was DeleteMessage or MoveToSuspendQ:

  1. If message HRESULT < 0, then adapter should not retry the operation and the failure should be ignored.
  2. If message HRESULT == 0, then the adapter can retry the operation.

If the operation was ResubmitMessage or MoveToNextTransport:

  1. If message HRESULT < 0 then adapter can either:
    • Try to suspend the message using the MoveToSuspendQ method.
    • Try to move the message to the next available transport using the MoveToNextTransport method if the original operation was ResubmitMessage.
  2. If message HRESULT == 0, then the adapter can retry the operation.

IF BATCH PASSES due to one of the following conditions

  • (Batch HRESULT == 0 ) the adapter can safely assume that all messages have been persisted.
  • (Batch HRESULT == S_FALSE) one or more messages in the batch were automatically suspended by the messaging engine due to a pipeline failure.
  • (Batch HRESULT == BTS_S_SECURITY_CHECK_FAILED ) one or more messages in the batch failed the biztalk authentication check and hence were dropped by the messaging engine.

The most common cause for a batch to fail is E_BTS_NO_SUBSCRIPTION. If a single message in the batch does not have a corresponding subscription, then the whole batch will fail.

MoveToSuspendQ Method Fails

Problem: The MoveToSuspendQ method fails.

Resolution: Typically the adapter should do nothing. For example, the FILE receiver should unlock the file and leave the message as is in the receive location, so that it can be picked up again.

Problem: The S_ EPM_SECURITY_CHECK_FAILED HRESULT is returned for the message.

Resolution: The adapter must handle two cases: batch passed and batch failed.

The adapter stream is not seekable

Problem: Adapter stream is not seekable.

Resolution: If a single message in the batch does not have a corresponding subscription, then the whole batch will fail. If the batch fails, then adapter writers need to have batch filtration and retry logic as explained in the "batch fails" issue above.

For resubmitting (SubmitMessage/SubmitRequestMessage) the good messages in the failed batch, the stream in the message must be seekable. Receivers like HTTP and SOAP may not have seekable streams.

The recommendation is that transports that cannot have a seekable stream should use a BatchSize=1. This is required to avoid denial of service attacks whereby an attacker could try to poison a batch by sending one bogus message.

The downside to a batch size of 1 is that performance may not be satisfactory.

Therefore if performance is important to a transport, then it should try to make its stream seekable. Internal adapters like HTTP have a seekable stream implementation for this.

The Batch.Done method fails

Problem: The Batch.Done method fails.

Resolution: The Batch.Done method may fail during the application domain recycle or during service shutdown. The adapter should handle this gracefully and should refrain from submitting new work to the Messaging Engine when this happens.

The Batch.Done method is blocked

Problem: The Batch.Done method is blocked.

Resolution: The adapter needs to do nothing. If the system is under heavy load then the Messaging Engine will stop any new work from getting processed until the system is back in a normal state. When this happens the thread calling Done is blocked indefinitely. An event will be fired in the event log when the engine is under heavy stress and another event is fired when it returns back to a normal stress level.

Databases are down

Problem: Databases are down.

Resolution: Typically, do nothing.

Out of Process Adapters

When the Configuration database or the MessageBox database is down, the Messaging Engine will detect the failure and will try to call the RemoveReceiveEndpoint method for all receive locations. Adapters must be written so that they do not block on any calls to AddReceiveEndpoint, RemoveReceiveEndpoint, and UpdateReceiveEndpoint methods. Also the implementation of these method should refrain from making any calls to the transport proxy or submitting any new work to the system.

In Process Adapters

When the Configuration database or the MessageBox database is down, the Biztalk NT service will recycle itself. When this happens, the Terminate method is called on every adapter to give every adapter a chance to cleanup. Every adapter should ensure that this method does not block. In addition, when this happens all new work submitted to the transport proxy will be rejected.

Request-response messages time out

Problem: Request-response messages time out.

Resolution: There is a default time-out of three minutes for the response message corresponding to a request message to be sent. If a response takes longer than three minutes then the Messaging Engine will send a Negative Acknowledgement (SOAP fault) back to the adapter as the response to the original message. Adapters that need to control the time-out should specify it while calling the SubmitRequestMessage method.

See Also

Developing Adapters Using the Adapter Framework

To download updated BizTalk Server 2004 Help from www.microsoft.com, go to http://go.microsoft.com/fwlink/?linkid=20616.

Copyright © 2004 Microsoft Corporation.
All rights reserved.
© 2015 Microsoft