Monday, 5 January 2009

Custom Soap Exception Detail Propty -Work with BizTalk

How to make use of Custom SOAP error Detail property in BizTalk ?
Today I start this artical with showing a property of Soap Exception. Just have a look at the below image. Have you ever played around with Detail Propery provided by SoapException? If your anwer is "Yes" then jump to Biztalk part below the Webservice code and see how to handle the Detail property at biztalk level. Otherwise check the below code for detailed programming for Custom Soap Exceptions. ( Build a Detail property using Csharp Code).

I have written a simple webservice (webmethod) which accepts two input parameters and check the authentication. If success then returns the Bool value of "True" else raise the Cusom Soap Error Message.

WebService Code
public bool CheckAuthentication(string UserName , string Password)
{ if (UserName == "TestUser" && Password == "TestPwd")
{ return true; }
throw RaiseCustomSoapError("AuthenticationCheck","","101","User is not Authorize person to access this site" "CustomSOAPException");
public SoapException RaiseCustomSoapError(string NameofActor, string wsNamespace, string errNumber,string errMsg, string errSource)
XmlQualifiedName tmpfaultCode = null;
tmpfaultCode = SoapException.ClientFaultCode;

XmlDocument xmlDoc = new XmlDocument();
XmlNode rootNode = xmlDoc.CreateNode(XmlNodeType.Element,SoapException.DetailElementName.Name,SoapException.DetailElementName.Namespace);
XmlNode errorNode1 = xmlDoc.CreateNode(XmlNodeType.Element, "Errors", wsNamespace);
XmlNode errorNode = xmlDoc.CreateNode(XmlNodeType.Element, "Error",wsNamespace);

XmlNode errNumberNode = xmlDoc.CreateNode(XmlNodeType.Element, "ErrorNumber", wsNamespace);
errNumberNode.InnerText = errNumber;

XmlNode errMsgeNode = xmlDoc.CreateNode(XmlNodeType.Element, "ErrorMessage", wsNamespace);
errMsgeNode.InnerText = errMsg;

XmlNode errSourceNode = xmlDoc.CreateNode(XmlNodeType.Element, "ErrorSource", wsNamespace);
errSourceNode.InnerText = errSource;


//Constructing the exception
SoapException soapEx = new SoapException(errMsg, tmpfaultCode, NameofActor, rootNode);
return soapEx;
When you select soapEx.Detail property will retun the XML Structure of Error Details as mentioned in below format.
Custom Error Message Structure

BizTalk Code
Summary of Orchestration Flow : BizTalk receives the Inbound XML File which has username,password and Sends the same to Webservice method (CheckAuthentication) "Request"
If the UserName and password is valid then Wesbservice return the Success status of "True" value and you need to build the output Message and send to Destination Location.
Incase of Failed Authentication Webservice Throws Custom SOAP Exception. Biztalk will pick this Exceptions at SOAP Exception block (System.Web.Services.Protocols.SoapException) using Detail Property.

Inbound and Outbound Schemas:

Orchestration Flow

Write the below code at Assign Error Detail ( Assignment Shape) Code

vErrDetails = soapEX.Detail.OuterXml.ToString();
vXmlObj = new System.Xml.XmlDocument();
GenMsg = vXmlObj;

vXmlObj2= new System.Xml.XmlDocument();
vXmlObj2.LoadXml(" Your generated output Schema structure");

OutputMsg = vXmlObj2;
xpath(OutputMsg,"//Errors") = xpath(GenMsg,"//Error");

For success Output message Error node would be empty and for the Failure (Custom Soap Error Detail property message) Error node filled with details.

you can reach me at


  1. I've followed the steps in your article but reading the Detail property does not match with your result. Instead of retrieving the custom Error nodes that I return in the webservice, I get a "Nack " message.

    ns0:NACK Type="NACK"
    ErrorCode 0xc0c01f07 /ErrorCode
    ErrorCategory 0/ErrorCategory
    ErrorDescription SoapException: Foutje /ErrorDescription

    I can not succeed in reading the custom Error node that has been created by the webservice.

    I think that the BizTalk Soap Adapter translates the Detail node, that has been filled up with a custom error, into such a Nack message.

    I'm running BizTalk Server 2006. Perhaps you're running BizTalk Server 2006 R2?

    Do you've any ideas what could cause this behavior?

  2. I've the same problem as the post above. soapEX.Detail.OuterXml.ToString() returns a Nack. The details node contains an error an a message record.

    Do you have any idea what's causing this? I'm using Biztalk 2006