BizTalk Server: Call external code in an orchestration

Introduction

BizTalk Server core is the messaging engine and on top of it an orchestration capability has been created and introduced with BizTalk Server 2004. An orchestration can aid in automating a business process. For instance when an order enters BizTalk and has to be routed to several back-end systems in a certain order; Check inventory, send a message to logistics, billing, and so on. An orchestration can be implemented by a developer within Visual Studio (orchestration designer) by placing several shapes on a canvas. These shapes are configured and/or can contain code or a reference to external .NET components. The latter is don in expression shapes with possible reference(s) to an external class in a custom .NET component. 

These custom .NET  components can provide capabilities such as serialization/deserialization of messages (see article BizTalk Server: Working with XLangMessage inside Orchestration), error handling, caching, tracing, and logging (see article BizTalk Server 2013 R2: Instrumenting an orchestration with ETW). The benefit of calling external components is that you do not have to create multiple objects in different orchestrations. The .NET classes in external components are implemented as static as you will see in this article. No internal state is maintained in the orchestration, therefore reducing the size that must be persisted in the MessageBox. However, there can be a risk by putting too much logic and processing into .NET components. You could be tempted to do so and increase lead time and make debugging more complex. Consider using .NET components only to boost performance, see also MSDN Optimizing Orchestration Performance or reduce the complexity of an orchestration.

Scenario

To keep orchestrations lean and performant you can call referenced .NET class(es) in an expression shape. Consider you want to a rather complex calculation to be done inside an orchestration like calculate mortgage monthly payment. You could call a rule engine or pass the message to a .NET component.  In latter case the component will contain a class with a static method CalculateMonthlyPayment containing the following possible logic: 

var loan = 300000; // desired amount 
var periods = 360; // 30 years 
var monthlyRate = (0.065)/12;  // 0.065= APR of 6.5% as decimal 
var monthyPayment = (monthlyRate /(1-(Math.pow((1+monthlyRate),-(periods)))))*loan;

The above calculation is based on the following financial formula for calculating the monthly rate: 

http://i208.photobucket.com/albums/bb152/Steef-Jan/Algoritme_zpsvpuhpnp1.png

Calling an external .NET component is straightforward and will be demonstrated in the article.

.NET Component

The .NET component will have in this scenario one class with one method like shown below.

using System;
using System.Collections.Generic;
using System.Text;
using System.Xml;
using System.IO;
namespace MortgageCalculator
 {
  [Serializable]
  public class  Payments
   {
/// <summary>
/// Calculate the montlyPayment over period of months
/// </summary>
/// <param name="loan">Amount</param>
/// <param name="periods">Number of months</param>
/// <param name="monthlyRate">Interest rate i.e. 0.065= APR of 6.5%</param>
/// <returns></returns>
public static  double CalculateMonthlyPayment(double loan, double periods, double monthlyRate)
{
double monthlyPayment = 0;
//Calculate monthly payment
monthlyPayment = (monthlyRate / (1 - (Math.Pow((1 + monthlyRate), - (periods))))) * loan;
return monthlyPayment;
}
   }
}

Call component in an orchestration

In a BizTalk project, you need to reference the project containing the component/class. Subsequently, you drag an expression shape into your orchestration that will call the component. The variable in the code below will be assigned the outcome of the calculation.

monthlyPayment = MortgageCalculator.Payments.CalculateMonthlyPayment(IncomingMsg.MessagePart.Loan,IncomingMsg.MessagePart.Period,IncomingMsg.MessagePart.InterestRate);

The orchestration can look like below.

http://i208.photobucket.com/albums/bb152/Steef-Jan/Mortgage%20Cal%20Orch_zpsgiz4dhcx.png

Figure 1. Orchestration with an expression shape invoking an external component.

You can download the sample and explore how to call an external assembly from an orchestration. MSDN Code Gallery - Invoking an external component in a BizTalk Orchestration.

See Also

Another important place to find an extensive amount of BizTalk related articles is the TechNet Wiki itself. The best entry point is BizTalk Server Resources on the TechNet Wiki.