Handling and Throwing SOAP Exceptions from BizTalk

Written by

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)

{

MessageBox.Show(soapEx.Detail.InnerText);

}

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: BizTalk, web services

Comments

20 responses to “Handling and Throwing SOAP Exceptions from BizTalk”

February 23, 2007

Harold Hoffman

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?

Thanks

Harold

Reply
February 23, 2007

Richard Seroter

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?

Reply
February 24, 2007

Harold Hoffman

I found a solution here

http://www.traceofthought.net/PermaLink,guid,abdd6ca2-e964-437d-8bee-0188ec5b5afa.aspx

He also used a decision shape and checked the success() of the previous transaction.

Thanks

Harold

Reply
March 1, 2007

Steef-Jan Wiggers

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,

Steef-Jan

Reply
March 1, 2007

Richard Seroter

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?

Reply
April 17, 2007

Suresh

Hi,

have you tried getting a fault contract from consumed WCFservice and returning that message?

Reply
April 17, 2007

Richard Seroter

Hey Suresh,

I have not done that yet. You?

Reply
April 20, 2007

suresh

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?

Reply
May 25, 2007

Anna Semyonova

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,
Anna

Reply
May 25, 2007

Richard Seroter

Hey Anna,

It seems a few people have gotten that error before. Check this out (http://geekswithblogs.net/chrishan/archive/2006/02/23/70482.aspx) for more. I got around that error (in my sample above) by having a “decision” after the catch block.

Reply
June 14, 2007

Michael

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

Reply
June 15, 2007

Richard Seroter

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?

Reply
June 15, 2007

Michael

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.

Reply
July 11, 2008

Mike

Hi Richard,

In addition to your post, people might also find my post interesting as I discuss how different adapters return the biztalk fault message to the client. There are a number of different configuration settings which affect what the client gets in terms of an exception. (Note this also includes the WCF adapters)

http://geekswithblogs.net/michaelstephenson/archive/2007/11/13/116807.aspx

Reply
August 4, 2009

psmithesh

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
Thanks
Smitesh

Reply
July 1, 2011

Todd Hensley

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.

Reply
1. July 1, 2011
  
  Todd Hensley
  
  Oops. It stripped out the “string” tag that is around the message. Let’s try this again:
  
  “<This is my error>”
  
  Reply
  1. July 7, 2011
    
    Richard Seroter
    
    Hmm. It’s going to have to come out as XML though, isn’t it? Won’t you need to do some parsing to extract the message?
    
    Reply
  2. July 12, 2011
    
    Todd Hensley
    
    I don’t think people who are writing the client software are going to expect to have to parse the value in system.exception.message. Isn’t it intended to be a human-readable error?
    
    http://msdn.microsoft.com/en-us/library/system.exception.message.aspx
    
    Reply
  3. July 12, 2011
    
    Todd Hensley
    
    This page describes what I am seeing much better than I manged to do 😉
    http://efreedom.com/Question/1-3937017/BizTalk-Orchestration-Respond-Untyped-SOAP-Fault
    
    Reply