BizTalk: Writing and using a custom referenced functoid.

This article will show how to develop a custom referenced functoid and how to include and use it in a map. A referenced functoid is one that is coded using a .Net language to create a class file that is referenced by the functoid at run time. As such it has access to the full .Net framework. This example will use a simple method within the functoid that will take in a string of words as an input and return the words and the letters within the words, reversed.

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.

Pre-Requisites
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 was there.

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

namespace ReverseWords.Functoid
{
    [Serializable]
    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;

        /// <summary>
        /// The constructor of this referenced custom functoid
        /// </summary>
        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
            SetupResourceAssembly("ReverseWords.Functoid.ReverseWordsResource", Assembly.GetExecutingAssembly());

             // Define the properties of the functoid
           SetName("REVERSEWORDSFUNCTOID_NAME");
            SetTooltip("REVERSEWORDSFUNCTOID_TOOLTIP");
            SetDescription("REVERSEWORDSFUNCTOID_DESCRIPTION");
            SetBitmap("REVERSEWORDSFUNCTOID_BITMAP");

             // 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.
            this.SetMinParams(1);
             this.SetMaxParams(1);

             // Add one line of code as set out below for each input param. For multiple input params, each line would be identical.
            AddInputConnectionType(ConnectionType.All);

             // 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");

        }

         /// <summary>
        /// Takes a string of words as input and reverses the words and the letters within each word.
        /// </summary>
        /// <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]) + " ";
                 }
                 return str;
            }
            return null;
        }
         /// <summary>
        /// Takes a string as input and returns the reversed string
        /// </summary>
        /// <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)
                 ReverseLetters(s);
             return str;
        }  
    }
}

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 below.

<ns0:Words xmlns:ns0="http://CustomFunctoid.Schemas.words">
<TheWords>The quick Brown Fox jumped over the lazy dogs</TheWords>
</ns0:Words>

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.



Create map
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.

Invoking component...
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 Settings\Temp\_MapData\CustomFunctoidMap_output.xml>
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



Testing

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.

<ns0:sdroW xmlns:ns0="http://CustomFunctoid.Schemas.sdroW">
<sdroWehT>sgod yzal eht revo depmuj xoF nworB kciuq ehT </sdroWehT>
</ns0:sdroW>

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.

Happy Programming.