Calling External Assemblies From Orchestrations

Introduction

In this article, I will cover how to call business logic contained in external assemblies from orchestration in order to reuse this component's logic. For the solution, I will create a library with a component which implements the string concatenation logic. Then this assembly will be referenced from an orchestration and the underlying method will be invoked.

Getting started with the solution

First of all, open Visual Studio .NET and create a solution, an Empty BizTalk Server project (see Figure 1) and Class Library project (see Figure 2).



Figure 1



Figure 2

Now let's add the Concatenation class to the Class Library project and implement the underlying business logic (see Listing 1). It's remarkable to say that we need to annotate the class as Serializable because when calling instances of class not marked as Serializable from an orchestration, it must be from an atomic scope. Thus, it's appropriate to mark all classes as Serializable.

using System;
using System.Collections.Generic;
using System.Text;

namespace StringUtilitiesLibrary
{
    [Serializable]
    public class Concatenation
    {
        public Concatenation()
        { }

        public string Concat(string strParam1, string strParam2)
        {
            return strParam1 + strParam2;
        }
    }
}

Listing 1

In order to be correctly reference this assembly by BizTalk orchestration, we need to add a strong name file to the project, then compile the assembly and add it to the Global Assembly Cache (GAC) using gacutil tool. You can compile and deploy this assembly.

Now let's move to the BizTalk project and create two schemas for the messages that the Concatenation class's instance will receive by its Contact operation. The first one for the input message (see Figure 3). Set the Param1 and Param2 data fields as distinguished fields in order to be accessed from orchestrations.



Figure 3

And the other schema for the output messages (see Figure 4). Set the Value data field as distinguished fields in order to be accessed from orchestrations.



Figure 4

Now let's define the orchestration object variables and messages. First of all, add a reference to the previously created assembly by calling the Add Reference dialog box, clicking on the Browse tab, and finding the assembly (see Figure 5).



Figure 5

Now let's add an orchestration artifact into the project and define the underlying business logic and business entities such as variables and messages (see Figure 6).



Figure 6

As you have the assembly available in the project, then create a new orchestration variable by right-clicking the Variables node and selecting New Variable from the context menu in the Orchestration View window. Now let's set up the variable using the Properties windows. Set the name property to objConcatenation and specify the Type property by selecting the <.NET Class...> option from the drop-down box and choosing the Concatenation class from the Select Artifact Type dialog box (see Figure 7).



Figure 7

Now let's create two messages one for the input values and other for the output values by right-clicking the Messages node and selecting New Message from the context menu in the Orchestration View window. Set Identifier property to msgInput and the Message Type to the previously created Input XML Schema for the first message (see Figure 8).



Figure 8

And set the Identifier property to msgOutput and the Message Type to the previously created Output XML Schema for the second message (see Figure 9).



Figure 9

Now let's add a Receive, Construct and Send shape to the orchestration. Set appropriate name for each shape. Set the Message property to msgInput for the Receive shape and the Activate property to True as well as set the Message property to msgOutput for the Send shape as well as set the Messages Constructed property to msgOutput for the ConstructMessage shape.

Now let's add a MessageAssignment shape within the ConstructMessage shape and double-click it to open the BizTalk Expression Builder dialog box. Finally write the invocation to external objects within the text box (see Figure 10).



Figure 10

Next step is to add, configure and bind the Receive and Send ports for the Receive and Send shapes. The final orchestration resembles to Figure 11.



Figure 11

When you compile this solution, you receive an error concerning that the msgOutput message has not been initialized. You can solve this problem by creating a .NET helper class to create an instance of this message. For simplicity, we're going to do a trick in order to instantiate the message through BizTalk maps. We're going to add a dummy transformation (using a BizTalk map) which maps from Input Schema documents into output Schema documents (see Figure 12).



Figure 12

Then drag and drop a Transform shape from the Toolbox within the ConstructMessage shape and configure this shape by clicking on the Map Name property, then the Tranform Configuration dialog box will appear. Select the Existing Map option, and choose the previously created InitializedInputSchema_Map map, then set the source message to msgInput and the destination message to msgOutput (see Figure 13).



Figure 13

Now you can assign a key name file to the project (see Figure 14), set an application name (see Figure 15) and finally build it and deploy it to the server in order to be tested.



Figure 14



Figure 15

Conclusion

In this article, I covered how to invoke the methods of components contained in external assemblies from orchestration in order to reuse this component's business logic. Now you can apply this solution to your own business scenario.