Calling a .net component from BizTalk orchestration

This blog is to explain how to call C# components from BizTalk. I am going to explain this scenario by taking simple example like Addition of two number in C# component and call the C# method from BizTalk Orchestration.

First, we need to create a C# class library by following below steps.

  1. Start–>VisualStudio–>Click on Visual Solution–>File–>New–>Project
  2. Select class library project from the template “Visual C#” like below.


3. Change the project name “ClassLibrary1” to “SumofTwoNumbers” and then click OK.

4. Change the class name from “Class1.cs” to “Sum.cs”.

5.Add below code in .cs file


using System;

using System.Collections.Generic;

using System.Linq;

using System.Text;

using System.Threading.Tasks;

namespace SumofTwoNumbers



   public class Sum


        public Int32 Addition (Int32 Num1, Int32 Num2)


            Int32 Add;

            Add = Num1 + Num2;

            return Add;       




This C# component takes two input parameter and return the sum of the two parameters. These two input parameters need to be passed from BizTalk orchestration for our scenario.

Note: Make sure class should be ‘Serializable’, because when calling instances of class, not marked as Serializable from an orchestration, it must be from an atomic scope. 

6. Provide strong name key for the project and Build it.

7. Once you build the project, one dll gets created in project directory, you need to GAC the dll by using GACUtils tool.

8. Now C# dll is ready to use from BizTalk orchestration.

Follow below steps to create BizTalk application and call above C# method.

9. Create a BizTalk project and add above C# library as reference to the project.


10. Open BizTalk orchestration–>Goto Orchestration view–>Create a new variable name “SumOfTwoNumbersMethod”–>Open Properties of the variable–>Type–>Select <.Net Class..>–>Select project name–>Select Classname from the References.

11. Now we have a BizTalk variable ready which points to the C# class.

12. Now we can use this variable in BizTalk expression shape to pass the input parameters to the method.


//SumOfTwoNumbersMethod—This is the variable which we created above, to point to the C# class.

//Addition—This is the C# method where we have our actual logic.

//InputMsg.Val1—This is the first input parameter to the C# method.

//InputMsg.Val2—This is the second input parameter to the C# method.

//SumOutput – This is the int data type variable which stores the output of the method.

13. Now we have method output stored in the variable “SumOutput”, we can use this variable according to our requirement in the orchestration.


BizTalk with REST Service

Now in BizTalk 2013 R2 release, Microsoft provide the communication with Rest Services through WCF-WebHttp adapter. Here are below things added in BizTalk to consume and publish REST Service through BizTalk.

  1. WCF-WebHttp adapter- to communicate with REST Service
  2. JSON decoder pipeline component- to convert Json file into xml format in Receive Pipeline.
  3. JSON encoder pipeline component- to convert xml file to Json in Send Pipeline.
  4. JSON Schema Wizard- To generate xsd from json file.

as we know RESTService has always prefer to have data in json format.

Note: Sometime when RESTService respond with empty message then BizTalk will generate the Object Reference is not found error in JSON decoder pipeline. Micorsoft has release the hotfix for that. You can download from below site.


Before BizTalk 2013 and upper version release, BizTalk was not communicating with REST Services without adding custom coding at pipeline level.

For older Version of BizTalk to communicate with REST Service you can refer the below reference:


Following five HTTP methods are commonly used in REST based architecture.

  • GET – Provides a read only access to a resource.
  • PUT – Used to create a new resource.
  • DELETE – Used to remove a resource.
  • POST – Used to update existing resource or create a new resource.
  • OPTIONS – Used to get the supported operations on a resource.

Generate an XSD schema for JSON message

You can Refer to below link:

Create pipelines to process JSON messages

Receive Pipeline:

We are using JSON decoder pipeline component in Receive Pipeline to convert json to xml format. This pipeline has two properties (if you have installed above define hotfix then three properties)

As mentioned in below screenshot.


Below property details should be defined.

Add Message Body For Empty message: By default its False, we need to make this true to handle empty message. (This property only available when you have installed above defined hotfix).

Root Node: Define the schema root node name of the schema which is created through JSON Schema Wizard

Root Node Namespace: define the namespace of the schema which is created through JSON Schema Wizard.

Send Pipeline:

For sending json file from BizTalk, we can use the JSON encoder pipeline component. This component converts xml to json file. There is only one property in this pipeline component as defined in below screenshot.


Remove Outer Envelope: By default, this property is defined False. When we make it true then its remove top layer or envelope of json file.


Json file with property Remove Outer Envelope as False:


  “TestRequest”: {

    “Test”: {

      “TestRequire”: true




Json file with property Remove Outer Envelope as True:


  “Test”: {

    ” TestRequire “: true



For more info you can refer to below reference:

These are the prerequisites knowledge about how to deal with Rest-service through BizTalk.

Now in next blog we have defined that how to publish BizTalk as REST Service.


Terminating Instances running on Isolated Host

Most of the cases when we are trying to terminate the running or suspended instances from BizTalk admin console, then we directly terminate them from the admin console. If it’s not terminate in first trial then we need to follow the below process:

1st Approach: Re-start Host Instances

Terminate the instance and re-run the Run Query. If it’s not terminated then we can restart the respective host instances and in case of isolated host, restart the IIS, then check. if is again not terminated then we need to go for below approach.

Note: Below approach should not be tried in production server, if it’s require then firstly take the backup of data then proceed further.

2nd Approach: Remove from Database

Database: BizTalkMsgBoxDb

SQL Statement For termination of running or suspended Instance



exec dbo.int_AdminTerminateInstance_<Host Instance Name> @uidInstanceID, @uidServiceID, @out


Here @uidInstanceID = uidInstanceID and @uidServiceID = uidServiceID of Instances Table.

Before executing the termination query, we need to understand following info.

Instances Table: This table has all the running and suspend instance details


Here uidAppOwnerID column name represent the Host Instance GUID. We can get the host instance name in respect to uidAppOwnerID from Applications Table.

Application Table:


So now we know the instance details and Host Instance information.

In BizTalkMsgBoxDb database, for every host instance there is dedicated stored procedure for terminating the instance.


Host Instance Stored Procedure for Termination
BizTalkServerApplication dbo.int_AdminTerminateInstance_BizTalkServerApplication


BizTalkServerIsolatedHost int_AdminSuspendInstance_BizTalkServerIsolatedHost

So, for termination the instance, we get the Host Instance Name from BizTalk Admin Console. We get the uidAppOwnerID as uidAppID information from Applications table for Host and message info (Instance ID and Service ID) from Instances table.

Now we run the sql statement to terminate the instance. Here we are terminating the instance of BizTalkServerApplication host instance.




exec dbo.int_AdminTerminateInstance_BizTalkServerApplication ‘4844E88F-F3A9-4057-B252-1D09834B02E2’, ‘0C474F97-45FC-49FA-9D86-D3413804D056’, @out


Check the Instance Table that the Instance has deleted or not.

BAM Installation and Configuration in Multi server Environment

In Most of the Project development, BAM is always chosen as second phase. In Existing BizTalk Project, BAM will add as an additional layer to the solution.

In this blog We are explaning about BAM installation in Multi server Environment. The below BAM installation steps assumes that BizTalk is already installed and configured. To install BAM on BizTalk Servers, we need to again run the BizTalk server setup file on all BizTalk Servers and follow the below steps

Note: The Log on User account to install and configure BAM should have admin rights on SQL server and Biztalk both.

  1. When we run the set-up file, below page will be popup.


  1. Click on Install Microsoft BizTalk Server 2013 R2


  1. Select Modify as below:


  1. Select Portal Component along with all others Component, which had already installed on the machine.


Note: Please select all components which are already installed otherwise It will remove those component from the BizTalk Server and then we need to install all the components again.

  1. Select all BAM Component in Additional Software as Below:


  1. Click Next and install.

Configuring BAM

As a part of multi-computer environment, while configuring BAM, we need to select the Custom Configuration option in the BizTalk Server Configuration tool on each Biztalk Server in the group.

1. Configuring BizTalk BAM Server

Here we assume that Biztalk Server is already installed and configured, we just need to add BAM Tool and BAM portal Configuration on the BizTalk Server. BAM also requires the following:

  • SQL Server Analysis Services (SSAS)
  • SQL Server Integration Services (SSIS)
  • SQL Server Database Mail or SQL Server Notification Services (SSNS)

To configure BAM

  1. Click Start, point to All Programs, point to Microsoft BizTalk Server, and then click BizTalk Server Configuration.


  1. In the left pane, click BAM Tools, and then enter or select the following values:
Name Value
Enable Business Activity Monitoring tools (selected)
Enable Analysis Services for BAM aggregations (selected)
BAM Primary Import Database: Server Name the SQL Server host name
BAM Primary Import Database: Database Name the default name is BAMPrimaryImport
BAM Archive Database: Server Name the SQL Server host name
BAM Archive Database: Database Name the default name is BAMArchive
BAM Analysis Database: Server Name the SQL Server host name
BAM Analysis Database: Database Name the default name is BAMAnalysis
BAM Star Schema Database: Server Name the SQL Server host name
BAM Star Schema Database: Database Name the default name is BAMStarSchema

Screenshot as below:


Note: The service account used for the OLAP service should have db_datareader permissions on the BAM Star Schema database.

  1. In the left pane, click BAM Alerts, and then enter or select the following values (Optional).
    BAM alerts require SQL Server Database Mail , and BAM tools to be enabled.
Name Value
Enable SQL Notification Services for BAM alerts (selected)
Windows service BTService
BAM Alerts SMTP Server (the SMTP server that will be used to send the BAM alerts.)
BAM Alerts File Location (the network share that will be used to store the BAM alerts.)
Note : We must manually create this share before BAM alerts can store the files.
SQL Server for Alerts Databases the name of the SQL Server
Prefix for Alerts Database Names (a prefix that will be used for the alerts databases)

Note: Do not install BAM Alerts unless you have a SMTP server available and planning to use BAM Alerts feature. SKIP installation of BAM Alerts by Unchecking the box in case it is already checked.

  1. In the left pane, click BAM Portal, and then enter or select the following values. In case you have not created domain groups for BAM , create the below three domain groups to control access to BAM:
  1. (domain)\BAM Portal Users
  2. (domain)\BAMAppPoolUser
  3. (domain)\BAMMgmtWSUser
Name Value
Enable BAM Portal (selected)
BAM Management Web Service user (domain)\BAMMgmtWSUser
BAM Application Pool Account (domain)\BAMAppPoolUser
BAM Portal Users (domain)\BAM Portal Users
BAM Portal Web Site Default Web Site

Note: BAM Management Web Service user and BAM Application Pool Account can be service account but service account will have admin access on BizTalk server.

Screen Shot as below which uses a Bam Portal users group as everyone which is not recommended in production environments and create a separate “BAM Portal Users” in domain.


  1. Click Apply Configuration.
  2. On the Summary page, to apply the configuration, click Next.
  3. Verify that the Configuration Result is Success, and then click Finish.
  4. Close Microsoft BizTalk Server 2013 R2 Configuration.

2. BAM Portal Configuration

After BAM Configuration with BizTalk Server Configuration. We need to check BAM Portal and config setting (if Require) on IIS.


Select BAM in Left side and open Authentication in Right side of IIS window as mentioned below screenshot:


Now Select Window Authentication and Click on Provider.. as mentioned in Below Screenshot.


Note: Only Enable ASP.NET Impersonation and Windows Authentication.

Select NTLM and Click Move Up Button. NTLM should be the first in the list of Providers


When we browse BAM Portal, it will open as below:


Note: BAM Portal works on Internet Explorer. For Chrome , a separate Extension IE tab is required.


Resource Link
Installation of BAM
Installation of BizTalk
Installation & Configuration Issue

BAM (Business Activity Monitoring)

BAM is the optional and important part of BizTalk. Its available when we are installing BizTalk Server.

BAM is used for monitor the data and milestone of the messages in near real time, which are passing thought the BizTalk.

Its show the tracking information of messages on web Portal to Business people who don’t know about the BizTalk inside activity. So, Business people or users will know about the details which is require when the messages processing in BizTalk. It shows when messages is processed through BizTalk, has it successful passed or not. And also generate alert message if require.

BAM is rich set of Tools for monitoring. It’s available along with BizTalk Licence. BAM Portal is ASP.NET Component.

In terms of MSDN (

Business Activity Monitoring (BAM) is a collection of tools that allow you to manage aggregations, alerts, and profiles to monitor relevant business metrics (called Key Performance Indicators, or KPIs). It gives you end-to-end visibility into your business processes, providing accurate information about the status and results of various operations, processes, and transactions so you can address problem areas and resolve issues within your business.

Benefits of BAM

  • BAM portal- Here user can track all the details for messages, aggregate data and generate alert.
  • BAM as a reporting solution provides a familiar environment to business users by taking advantage of Office and Sharepoint
  • Unlike application development, BizTalk development often does not have anything tangible which can be shown to a client. BAM will provide them information about their business processes and can help them to see the benefits of the solution
  • BAM can be implemented in easy way with some small coding if we write BAM programatically and with no code in case of Tracking Profile Editor
  • BAM is a built-in feature of BizTalk which a company who invests in BizTalk will already have made
  • In Most of the Project development, BAM is always chosen as second phase. In Existing BizTalk Project, BAM will add as an additional layer to the solution. You would simply deploy the BAM artifacts to the existing BizTalk group

Generate Schema when Schema has multiple Root Node

Some times BizTalk developer who starts BizTalk development, They mostly face issue to generate sample xml from schema, when schema has multiple root node. Its by default generate xml for the top first root.

We need to setup a small property to generate sample xmls from multiple root node.

Below is Sample schema which has three root node.


There is below property in the schema which we need to set Root Node name for which we need to generate sample schema.


Select respective Node and then Generate Schema from Schema. Here I have selected Root2. And go for generate Schema as below


Now below is Generated sample xml file