Developing a Custom Functoid in BizTalk Server

Introduction

In this article, I will show how to create a custom functoid in BizTalk. A functoid is a mapping artifact which enable encapsulate custom business logic in the component in order to transform documents with different formats. As an example, I will describe the process to develop, deploy, and use a custom functoid which implements the addition mathematical operation. The functoid will have two input parameters representing the numbers to be added and one output parameter representing the result of the addition operation.

Getting started with the solution

First of all, create a solution and an Empty BizTalk Server Project (see Figure 1).



Figure 1

Then a create a Class Library .NET project which hosts the functoid component (see Figure 2).



Figure 2

Add a reference to the Microsoft.BizTalk.BaseFunctoids.dll assembly located in the %PROGRAM FILES%\Microsoft BizTalk Server 2006\Developer Tools\ directory (see Figure 3).



Figure 3

Now let's add class to the Class Library project and name it as CustomAddition (see Figure 4).



Figure 4

Now it's time to write the code to implement the CustomAddition class.

First of all, reference the namespace Microsoft.BizTalk.BaseFunctoids and inherit the CustomAddition from the BaseFunctoid base class as well as annotate the class as Serializable using the appropriate attribute. Then write the initialization code in the constructor of the CustomAddition class in order to set an identifier to this class, set a name, description, tooltip, constraints in the minimum and maximum number of parameters and connection to external nodes, a reference to function that implements the addition logic as well as a category inside the Toolbox in Visual Studio (see Listing 1).

It's remarkable to say that in the case of name, description and tooltip properties of the functoid, we don't actually set the value instead we set the identifier to the associated resource. Thus, we need to create a resource file (resx) to store these properties and then add a reference to the resources in the code.

using System;
using System.Collections.Generic;
using System.Text;
using Microsoft.BizTalk.BaseFunctoids;
using System.Reflection; 

namespace CustomFunctoidsLib

{

    [Serializable]

    public class CustomAddition : BaseFunctoid

    {

        public CustomAddition() : base()

        {

            //Identifier for the class. 6000 or higher

            this.ID = 8888;

            //Reference to the resources

            this.SetupResourceAssembly("CustomFunctoidsLib.CustomFunctoidsLibResource",Assembly.GetEntryAssembly());

            //Functoid name

            this.SetName("CUSTOM_ADDITION_NAME");

            //Description of the functoid

            this.SetDescription("CUSTOM_ADDITION_DESCRIPTION");

            //Tooltip fot the functoid

            this.SetTooltip("CUSTOM_ADDITION_TOOLTIP");

            //Constraints in the minimum and maximum number of parameters

            this.SetMinParams(1);

            this.SetMaxParams(2);

            //Constraints on the connections to external nodes

            this.AddInputConnectionType(ConnectionType.All);

            this.OutputConnectionType = ConnectionType.All;

            //Reference to function that implements the addition logic

            this.SetExternalFunctionName(this.GetType().Assembly.FullName, "CustomFunctoidsLib.CustomAddition","Addition");

            //Category inside the Toolbox in Visual Studio

            this.Category = FunctoidCategory.Math;

        }

 

        public string Addition(string strParam1, string strParam2)

        {

            decimal dParam1 = System.Convert.ToDecimal(strParam1);

            decimal dParam2 = System.Convert.ToDecimal(strParam2);

            decimal dResult = dParam1 + dParam2;

 

            return dResult.ToString();

        }

    }
}

Listing 1

Finally, add a strong name key and build the project.

Next, place a copy of the assembly in the %PROGRAM FILES%\Microsoft BizTalk Server 2006\Developer Tools\Mapper Extensions\ directory and register the assembly in the Global Assembly Cache (GAC) using the gacutil tool (see Figure 5). It's remarkable to say that functoids can be tested without being deployed to the GAC.



Figure 5

Now add the functoid into the Toolbox, by right-click on the Toolbar and selecting Choose Toolbox Items option in order to display the Choose Toolbox Items dialog box. Go to the Functoid tab and click on the Browse button to search for the library. Finally, drag and drop the created functoid onto the maps surface and create the links with the underlying schemas.

Conclusion

In this article, I covered the development of a BizTalk functoid so that you can apply this solution to your own business situation.