Saturday, December 27, 2008

How to create custom Functoid [for Biztalk Mapper]


What is Functoid?

The term Functoids refers to predefined functions within the Biztalk Mapper tool set. Functoid's support
a number of useful translations and transformations.

Here are the steps to create, deploy and test the Custom Functoid.

1) Create a C# Class Library Project

2) Add Reference Microsoft.BizTalk.BaseFunctoids.dll to the project you can find this  DLL from the following  Folder [ Biztalk sever should be installed to get this Assembly]


3)  Add Resource file VS.NET Template to the project for to store Functoid Configuration parameters. and add the following Resource string and values.


4) Add Custom Functoid class and that should derive from BaseFunctoid class as shown below.



Here is the my custom function implementation.



When Overriding the Constructor we need to perform the following primary tasks as shown in the table.

[  Source : Microsoft  here is the link Custom Functoid]


Use these methods or properties


Assign a unique ID to the functoid


Use a value greater than 6000 that has not been used. Values less than 6000 are reserved for use by internal functoids.

Indicate whether the functoid has side effects


Used by the mapper to optimize the XSLT code that is generated. This property is true by default.

Point to the resource assembly


Include a resource file with your project. If building with Visual Studio, the resource assembly must be ProjectName.ResourceName.

Enable the custom functoid to appear in the BizTalk Mapper palette





Use a resource ID pointing to a string for the name, tooltip and description; use a 16x16-pixel bitmap.

Assign the functoid to one or more categories


Categorize the functoid by using one or more FunctoidCategory values.

Specify the number of parameters accepted




Use the SetMinParams method to set the number of required parameters and the SetMaxParams method to set the number of optional parameters. Use the following guidelines to set these values:

·         If you have no optional parameters, set min = max.

·         If you have some optional parameters, set max = (number of optional parameters - min number of parameters).

·         If you want to allow unlimited optional parameters, do not set max.

·         If you have a variable number of inputs, do not set min or max, and set HasVariableInputs = true.

Declare what can connect to your functoid


Call AddInputConnectionType once for each ConnectionType that the functoid supports.

Declare what your functoid can connect to


Use values from ConnectionType to tell BizTalk Mapper the types of objects that can receive output from your functoid. Use OR to specify multiple connection types.

Tell BizTalk Server which methods to invoke for your functoid




For cumulative functoids, use SetExternalFunctionName to set the initialization function, SetExternalFunctionName2 to set the accumulation function, and SetExternalFunctionName3 to specify the function that returns the accumulated value. For noncumulative functoids use SetExternalFunctionName to set the functoid method.

Have BizTalk Server use inline code to invoke your functoid

AddScriptTypeSupport SetScriptBuffer

Call AddScriptTypeSupport with ScriptType to enable inline code. Invoke SetScriptBuffer to pass in the code for the functoid. This code will be copied into the map.

Declare global variables for an inline functoid


Any declarations made will be visible to other inline scripts included in the map.

Indicate which helper functions your inline functoid requires


Use values from the InlineGlobalHelperFunction enumeration to specify which helper functions are required. Use OR to specify multiple helper functions.

Validate parameters passed to your functoid



These functions provide a true/false answer without throwing an exception.

5) Add Strong Name Key to the project this can be done from  VS.NET IDE itself or we can use  SN.EXE  from VS.NET command prompt .

6) Now copy the Build DLL into the following  Windows Folder. this is the place where BIZTALK server looks for custom Functoids.



7) Add Custom Functoid to  VS.NET Tool Box 



8. Add the functoid to the Global Assembly Cache (GAC) [ To add Assembly to GAC  the assembly has to build with Strong Name].

Now create a Biztalk MAP and test the Custom Functoid


Input XML Instance:

<ns0:Root xmlns:ns0="http://BizTalk_Server_Project1.Schema1">




Map Out put XML : ( with custom Functoid)

<ns0:Root xmlns:ns0="http://BizTalk_Server_Project1.Schema2">





1 comment:

Bart Thiery said...

Nice and clean guiding blogpost, very usefull for people taking there first steps into custom functoids. But, how could we debug our freshly made functoid? I can't get the debugger to work when testing the functoid in the mapper. I attached VS to the VS-process where the functoid is included...