Handling and Throwing SOAP Exceptions from BizTalk

I’m building the “system qualification” applications for our new BizTalk Server 2006 environment, and one use case consisted of both consuming and exposing web services using BizTalk. Given that I frequently forget the process for handling SOAP exceptions, I figured I’d document it here for future reference.

In this case, I’m receiving a message, using a message value to call a web service, and assuming everything goes fine, I construct a message response to the caller. I’ve wrapped my Send shape and Receive shape into a non-transactional Scope shape. This allows me to have exception handlers. In the exception handler below, I’m catching SOAP exceptions (found in System.Web.Services.Protocols.SoapException). I’ve created a message named “FaultMsgOutput” of type “string.” In the exception block I construct that fault string (FaultMsgOutput = “ProcessOrder.odx had a SOAP error occur!”) and send it out via a Fault operation method. If you have an inbound request/response port, you can add any number of fault messages.

After building and deploying this project (and generating a web service using the Web Services Publishing Wizard), I had to remember to jump into the auto-generated send port and switch the Retries number to 0. Otherwise, BizTalk would retry the SOAP call a few times, while the original caller ends up with a timeout. This way, the exception is immediately returned to me in the orchestration.

To test this, I built a small WinForm application to call the BizTalk generated web service. In the portion of the code where I call my BizTalk web service, I included the following “catch” statement …

catch (System.Web.Services.Protocols.SoapException soapEx)

First I naturally executed a “standard” scenario with everything working. Next, I changed the web service that my orchestration calls to include the following line at the top of called method …

throw new Exception(“bad inventory service exception”);

Nothing too exciting. As expected, this exception was shown in my WinForm app was the text I typed in the “FaultMsgOutput” string message. Next, I went to the called web service in IIS, and changed the permissions. As I hoped, this error was also caught by my orchestration and gracefully returned to the initial caller.

So, it’s fairly easy to catch web services exceptions, whether they are specific to the code itself, or infrastructure (e.g. IIS) related.

Technorati Tags: ,

Author: Richard Seroter

Richard Seroter is Director of Developer Relations and Outbound Product Management at Google Cloud. He’s also an instructor at Pluralsight, a frequent public speaker, the author of multiple books on software design and development, and a former InfoQ.com editor plus former 12-time Microsoft MVP for cloud. As Director of Developer Relations and Outbound Product Management, Richard leads an organization of Google Cloud developer advocates, engineers, platform builders, and outbound product managers that help customers find success in their cloud journey. Richard maintains a regularly updated blog on topics of architecture and solution design and can be found on Twitter as @rseroter.

20 thoughts

  1. Hi

    I get the following error when building my project trying to use the Fault operation message as you describe.

    ‘must receive before sending a fault message on an implemented port’

    Any ideas?



  2. I had that problem too … trying to recall how I got around it. What you don’t see in the picture above are the next steps. I made a “decision” and then constructed and sent the response message. What do you have following the “scope” block?

  3. Hi,

    I tried your sample in a different way. I was looking for an example to catch SOAP exceptions and I found this post. What I am trying to is sent a request through an orchestration to a webservice. This service can go allright and give me an reponse back, but it also could go wrong and give me exception which i want to catch in my orchestration and handle gracefully. Your post helped me with it and succesfully handled the error; the only thing is that the message is suspended and an administrator has to act on that, hence it will appear in its asministration console. Is there a way to prevent this? Thx,


  4. You know, I’ve been thinking about the same issue (web service msg still shows up suspended). I’ll have to try out a few things. Maybe put a “generate error report” flag on the port, and swallow any errors?

  5. Hi Richard,

    yeah i m working on that. i got some issues. hope u can help me out. its working for positive scenario but when i try to send a my own fault contract, apparently it sends as message with soap envelope. the receive shapes expects the response so BTS goes to suspended mode saying that unexpected message. can u help me in this?

  6. Hello,
    could You send me Your solution? I have this Problem with “must receive before sending a fault message on an implemented port”, and can’t get around it.

    Thank You,

  7. What if I really want to return an exception message in the synchronous response message instead of a new fault message?

  8. Michael,

    Do you mean the actual error thrown by the activities between the “receive” and “send”? I would think that this happens automatically if you don’t wrap the process in a scope and “catch” the exception. Have you already tried that?

  9. Well sort of and that is mostly true however what meant was for handling other errors that may occur in the orch that are not soap errors…. but I am now back to setting up catch blocks that handle the soap exception and use a decision block to send a fault message like demonstrated. I followed all the links and am still skeptical that it can work.

    I either get the “must receive before send fault message” OR if I move the send to the else of the decision then I get “Use of unconstructed message” I do not want to move the construct out of the exception scope because I am trying to catch potential exceptions here as well… UNLESS it the assumption should be that my maps will never throw exceptions once deployed in production environment.

  10. I have an issue with soap fault. When I publish the biztalk orchestration using Web service publishing wizard its not creating the definition for Soap Fault in the wsdl file. Bcos of this I couldnt able to receive the fault messages in client.
    Could you help me

  11. I know this is an old thread, but I’m just now learning the ropes on this topic. 🙂

    I have gotten it to work, but I’m not entirely happy with the exception message that the client (caller) sees. Let’s say the orchestration puts the value “This is my error” in the string variable that is plugged into the “fault” of the receive port, the client will see something like this:

    “This is my error”

    as the value of the exception Message property. I’m not overly thrilled with the “” tags being in there, and I’m sure most client’s wouldn’t be either. They probably are going to want the Message property to be something they could display to the end user without parsing out the XML tags.

    1. Oops. It stripped out the “string” tag that is around the message. Let’s try this again:

      “<This is my error>”

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.