BizTalk: Writing and using a custom referenced functoid.
This is a simple demonstration to illustrate the powerful techniques available to
developers incorporating custom functoids in their BizTalk solutions.
This article assumes a working knowledge of BizTalk Server 2006, maps, orchestrtations
and functoids. As such some instructions on how to create artefacts and deploy
applications etc. will be shortened.
Step 1 - Writing the custom functoid code
Start Visual Studio, create a new C# class library and name it ReverseWordsFunctoid.
Rename the default class to ReverseWords.cs. Add a reference to the Microsoft.BizTalk.BaseFunctoids
assembly. This can be found in the <install_location>\Microsoft BizTalk
Server 2006\Developer Tools\Microsoft.BizTalk.BaseFunctoids.dll
Paste the following code into the ReverseWords.cs class, replacing everything that
public class ReverseWords : BaseFunctoid
// Two member variables used by the methods called by this functoid.
public static string rev = string.Empty;
public static string str = string.Empty;
/// The constructor of this referenced custom functoid
public ReverseWords(): base()
// Custom functoids should have an ID greater than 6000
this.ID = 8888;
// Reference to resource file
// Format of 1st param is: [Namespace.Resourcefilename] - no extension
// Define the properties of the functoid
// Define a category for this functoid. This determines which pane in the toolbox
the functoid will appear in
this.Category = FunctoidCategory.String;
// Set the limits for the number of input parameters.
// In this instance there is only one input param.
// Add one line of code as set out below for each input param. For multiple input params,
each line would be identical.
// The functoid output can go to any node type.
this.OutputConnectionType = ConnectionType.All;
// Set the function name that is to be called when invoking this functoid.
// To test the map in Visual Studio, this functoid does not need to be in the GAC.
// If using this functoid in a deployed BizTalk app. then it must be in the GAC
SetExternalFunctionName(GetType().Assembly.FullName, GetType().FullName, "Reverse");
/// Takes a string of words as input and reverses the words and the letters within
/// <param name="w">The words to be reversed.</param>
/// <returns>The reversed words and reversed letters within each word</returns>
public string Reverse(string w)
if (w.Length > 0)
string arrWords = w.Split(' ');
for (int i = arrWords.Length - 1; i >= 0; i--)
str = ReverseLetters(arrWords[i]) + " ";
/// Takes a string as input and returns the reversed string
/// <param name="s">The string to be reversed</param>
/// <returns>The reversed string</returns>
public static string ReverseLetters(string s)
str += s.Substring(s.Length - 1);
s = s.Substring(0, s.Length - 1);
if (s.Length > 0)
Refer to the comments in the code to see what each line is responsible for.
Note: You will have to add a resource file to your project. This file will contain
details such as the name, tooltip, description and bitmap icon file of your functoid.
This information will be used when you add your functoid to the BizTalk Mapper
toolbox. For information on how to add a resource file to your project follow
this link: http://msdn.microsoft.com/en-us/library/7k989cfy%28VS.80%29.aspx
Sign the project and build. To use this functoid in your BizTalk map you must copy
the assembly from its build directory (this would be <path_to_project>\<project_name>\bin\Release
if you accept the default build location) to the Mapper Extensions directory
under <install_location>\Microsoft BizTalk Server 2006\Developer Tools\Mapper
Extensions. Once in the Mapper Extensions you will be able to add your functoid
to the String Functoids pane of the BizTalk Mapper screen.
As you will be using this functoid in a test BizTalk application you will have to
sign and deploy the cutom functoid assembly to the GAC. If you were to simply
test the map from Visual Studio, the assembly does not need to be signed or GAC’d.
Create BizTalk project
Open Visual Studio and create a blank BizTalk project.
The first thing we need is a source schema to hold our sentence to be reversed and
a destination schema to hold the reversed words.
Create Source Schema
Right click the BizTalk Project and add a new schema file and call it Words.xsd.
Construct it so as to be like the following screenshot.
Create the schema instance
The instance of this schema will be the file we drop into our directory in order
to invoke the functoid. Right click the schema and select Generate Instance.
Examine the output window of Visual Studio to determine where the instance file
was saved. Open it in your preferred text editor and edit it to look as the text
<TheWords>The quick Brown Fox jumped over the lazy dogs</TheWords>
Save the file as input.xml on somewhere on your filesystem.
Create the Destination Schema
Add another schema and call it sdroW.xsd. This should resemble the screenshot below.
Add a new map to the solution and select the source and destination schemas you just
created as the source and destination schemas of the map.
Add custom functoid to map toolbox
To add your functoid to the toolbox, right click the toolbox and select Choose items.
In the dialog box that appears, select the functoids tab and then click the Browse
button. Navigate to the <install_location>\Microsoft BizTalk Server 2006\Developer
Tools\Mapper Extensions directory and select your functoid assembly. Below is
a screenshot of the functoid in situ. Please note I created a bitmap icon and
included it in the resource file.
Now join the source and destination schemas to the functoid as shown below
Save the project. You can now test the map and the functoid by doing the following.
Right click on the map file in the solution explorer and select properties. In the
dialog that appears, set the value of the TestMap Input Instance property to
the destination of the input.xml file you created a few steps ago.
Once you have done this, click OK. You can now test your map by right clicking the
map file in solution explorer and selecting Test map. You should see something
similar to the following in the Output screen.
Test Map used the following file: <file:///C:\Projects\CustomFunctoid\Schemas\Input.xml>
as input to the map.
Test Map success for map file C:\Projects\CustomFunctoid\CustomFunctoidMap.btm. The
output is stored in the following file: <file:///C:\Documents and Settings\user\Local
Component invocation succeeded.
By following the link to the CustomFunctoidMap_output.xml you should see the following
appear in the main Visual Studio window.
To use this map in an Orchestration, add a new orchestration to the project.
The orchestration should contain the following artefacts:
A receive port with the following properties:
A Receive shape with the following properties:
A message Construction shape with the following properties
Inside the construct message shape, a transform shape with the follwing properties:
A send shape with the following properties
And finally a send port with the following properties
The final Orchestration should look something like this
To test drop the input.xml file into the directory you specified in the receive port
and shortly after the reversed.xml file should appear in the output directory
you specified in the send port. The contents of the reversed.xml file should
look something like this.
<sdroWehT>sgod yzal eht revo depmuj xoF nworB kciuq ehT </sdroWehT>
This article demonstrated how to develop a custom referenced functoid and how to
include and use it in a BizTalk map. This example used a simple method within
the functoid to return a string of words reversed. This is a simple demonstration
to illustrate the powerful techniques available to developers incorporating custom
functoids in their BizTalk solutions.