Exception Handling on BizTalk Orchestration Published as Web Service

The example project returns an xml containing the exception message and details. It follows the custom schema:

Transmission Error Schema file


This will be the sample output error on the Console application consuming the web service:


The project includes an orchestration that receives an input file conforming to activate a package. I will discuss on how to make a custom fault message (TransmissionError.xsd as its message type) on Exception Handling having System.Exception as its object type within the scope. This is the overview of the orchestration:



You will notice that a decision shape exists after the scope. This is to avoid the following errors that may occur:

  • must receive before sending a fault message on an implemented port
  • must receive before sending a message whose message type corresponds to a request response operation on an implemented port.

The decision shape makes sure that only one action – with transmission error (fault message) or none (response) – will be sent to the request-response port.

First, set the transaction type of your scope to None. Then, add a new Exception Handler and set its object type to System.Exception and its Object Name to “ex”:


Before adding an exception, make sure that the logic within the scope is tested to run correctly. This is the sample exception created:

The expression that is created (Successful = False) serves as Flag to indicate that the activation of package was unsuccessful. The first Construct Message shape receives “xdoc”(created from scope > message of type System.Xml.XmlDocument¬†). Inside the Message Assignment expression editor, type the following:

xdoc = new System.Xml.XmlDocument();
xdoc.LoadXml("Paste the generated instance of the TransmissionError schema : ex. =<ns0:TransmissionError xmlns:ns0='http://...Internal.TransmissionError'><Message>Message_0</Message><ExceptionDetails>ExceptionDetails_0</ExceptionDetails></ns0:TransmissionError>");

The second Construct Message shape constructs the TransmissionError message of type TransmissionError.xsd above. Type the following on its message assignment:

TransmissionError = xdoc;
TransmissionError.Message = ex.Message;
TransmissionError.ExceptionDetails = ex.ToString();

Notice the example from Console Application output error above: ex.Message displays “DeliveryFailureException”, ExceptionDetails receives the details from ex.ToString(); After the scope, the decision shape looks into the Flag whether an exception occurs. So if the the transaction encounters a transmission error, then it would go to the exception handler that sets the Flag to false and constructs the exception to TransmissionError message.


Also, when you encounter the following error upon testing your Web Service:

The server was unable to process the request due to an internal error. 
For more information about the error, either turn on IncludeExceptionDetailInFaults 
(either from ServiceBehaviorAttribute or from the <serviceDebug> configuration behavior) 
on the server in order to send the exception information back to the client, 
or turn on tracing as per the Microsoft .NET Framework 3.0 SDK documentation and inspect the server trace logs.

This is because you need to set the includeExceptionDetailInFaults to “true” inside the Web.config usually located in C:\inetpub\wwwroot\NameOfWebsite. ūüôā


BizTalk: Error on Debugging Orchestration (Debugging Client is not a BizTalk Server Administrator)

One great way to debug an orchestration in BizTalk Server Administration is to use the Orchestration Debugger. You can find this when you click BizTalk Group > Tracked Message Events and right-click the item of your query having the service name of your orchestration file. When you try to Debug > Attach and the Health and Activity Tracking Tool prompts you with following error:

The following errors occurred when attaching to the instance: Debugging user validation against group "localhost\BizTalk Server Administrators" failed with error: Debugging Client is not a BizTalk Server Administrator. This could happen if the Debugging Client is not a BizTalk Server Administrator.

like this:

then you need to set yourself as a member of BizTalk Server Administrators.

If you aren’t sure how, here is a list of steps on how to do it:

1) Go to Control Panel.
2) You’ll see all COntrol panel items on viewing it by icon. Click Administrative Tools.
3) Double-click Computer Management.
4) Under Local Users and Groups, click Users.
5) Double-click the name of the user you are using.
6) On the “Member Of” tab on the Properties window, click “Add”.
7) Click “Advanced…” and click “Find Now” in the “Select Groups” window.
8) Click “BizTalk Server Administrator” that is displayed on the “Search results” field.
8) Click OK.

Congratulations! Now you are an administrator of the BizTalk Server. ūüėČ

Now you can fully work with your Orchestration Debugger ūüėČ (http://msdn.microsoft.com/en-us/library/aa953746(v=bts.20).aspx)


c/o Ryan Velasco, Jesse Gador


BizTalk: Debatching Flat File to Multiple XML files.

After successfully validating instance of a comma-separated flat file (See: http://www.codeproject.com/Articles/13706/Creating-Flat-File-schemas-using-the-BizTalk-Serve), ¬†click the Schema Property and change ¬†“Allow Message Breakup At Infix Root” to “Yes“. Click the Record ¬†Property¬†(Child Record of CSV Root file in the example) and set “Max Occurs” to 1 and leave “Min Occurs” to blank.

On your Visual Studio, create new Schema file on your Solution Explorer and name it as XMLSchema.xsd. Rename the Root to anything you want (in this example we name it CSVxml), given that it has a child record “Record”. Create three child field elements (e.g. Name, DOB, Address) by right-clicking the Record and choosing “Insert Schema Node”. Your work will look similar to this:

Create a new Orchestration file and name it to FFOrchestration. On your Orchestration View, right click “Messages” and click “New Message”. Set the Identifier to “FFfile” and choose the Message Type “Schemas > FlatFileSchema.FFSchema_CSV¬†“. Create another message and set the Identifier to “FFxml” and the message type to “FlatFileSchema.XMLSchema” still under “Schemas”.

Go back to Orchestration View and create New One Way Port Type under “Types”. Set the Port Identifier to “FFPort”, the Operation Identifier to “FFOperation”, and the Request Message Type to FlatFileSchema.FFSchema_CSV. Create another One Way Port Type. This time, set the Port Identifier to “XMLport”, the Operation Identifier to “XMLOperation”, and the Request Message Type to FlatFileSchema.XMLSchema.

On your FFOrchestration.odx, create a new Port by dragging the Port icon from the toolbox. Name it “FFReceivePort” on the Port Configuration Wizard.¬†¬†Use an existing Port Type (FlatFileSchema.FFPort). Select “I’ll always be receiving messages on this port” on the “Port direction of communication” option and “Specify Later” on your “Port Binding”. Drag another Port and name it “FFSendPort” to your FFOrchestration.odx. Choose “FlatFileSchema.XMLport” as your existing Port Type. Select¬†“I’ll always be sending messages on this port” on the “Port direction of communication” option and “Specify Later” on your “Port Binding”.

Note that FFReceivePort has the FFOperation while the FFSendPort has XMLOperation.

Create a Receive shape by dragging the Receive icon from the toolbox and set its property to:

Activate : True
Name : FFReceiveShape
Message: FFfile
Operation: FFReceivePort.FFOperation.Request.

Drag a Send Shape below FFReceiveShape and set its property to:

Name : FFSendShape
Message: FFxml
Operation: FFSendPort.XMLOperation.Request

Your orchestration looks similar to this:

After doing that, add new Map file and name it FFMap.btn and map the FFSchema_CSV.xsd to the newly created Schema. In this example, XMLSchema.xsd with Root name “CSVxml”.

Then, add new Receive Pipeline. Let us name “FFReceivePipeline”. Drag “AS2 dissambler to “Drop Here!” Box in Disassemble.

Remember to set your Assembly’s Application Name by right-clicking the assembly name in your Solution Explorer > Properties. Click Deployment > BizTalk Group > Application Name. ¬†Also create a strong name key file under Signing (*.snk) as BizTalk requires strong name key for your application.

Build Solution. Deploy. ^^

On your BizTalk Server, locate your application under BizTalk Group.¬†Right-click “Receive Ports” and create new One-way Receive Port. Having created that, create new One-Way Receive Location and choose your newly added Receive Port. Configure the name, type (FILE), the Receive Folder (click Configuration beside the File Type) and change the File Mask to *.txt. Change the Receive Pipeline to FFReceivePipeline and click OK.

Create new Static One-Way Send Port and configure the Destination Folder, File name as %MessageID%.xml, File Type as FILE and choose XML Transmit for the Send Pipeline option. Set your Orchestration Properties similar to this:

Start your application. Test it by putting the CSV text file in your Receive folder. You know it is successful when there are multiple XML files in your Destination folder. ūüėČ

c/o Ryan Velasco, Jesse Gador


BizTalk Orchestration Error: Having Multiple Versions of GUID

If you find yourself having two orchestrations (with different Public Key Token in the assembly version) when you run your application in your BizTalk Server Administration Console, it is likely that you have different versions of GUID running.

So even when you try to update and redeploy your application on Microsoft Visual Studio, BizTalk would still load the older version of your GUID.

In this example, let us name our assembly BTDemo,

To delete the other versions of your GUID, you must make sure that you have stopped running the orchestrations on your BizTalk Server Administration Console (Application Name > Orchestration) . Find the location of different versions of your GUID inside the Global Assembly Cache or GAC (C:\Windows\Microsoft.NET\assembly\GAC_MSIL\BTDemo\ * Versions of GUID) and delete all old versions of the GUID.

On your BizTalk Sever Administration Control, remember to restart the Host Instances under Platform Settings found under BizTalk Group before redeploying your application from VS. Try running your application this time ūüėČ

Also note, if there is a problem on  tracking database or if message is not found in the message box, you may refer to: http://www.12qw.ch/2012/03/enable-biztalk-trackingthe-message-was-not-found-in-the-message-box-or-the-tracking-database/. Make sure all 4 steps are applied. This helped me on successfully running my application.

c/o Ryan Velasco, Jesse Gador



–I just realize that the error of redeployment of Biztalk is that due to those suspended messages. To solve this even without removing the assembly in the gac is to terminate the suspended message related to the Biztalk project you are trying to deploy‚Ķ-Ryan Velasco