Edit

Using BaseFunctoid

  • Article

All custom functoids must derive from the BaseFunctoid class. You must first override the constructor and make a set of calls that tell BizTalk Mapper about your custom functoid. Then you need to write the functoid logic.

Overriding the Constructor

You must perform a number of tasks in the class constructor override method to characterize your functoid. These tasks are in addition to any functoid-specific code your solution requires. The following table describes the primary tasks.

Task Use these methods or properties Comments
Assign a unique ID to the functoid ID 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 HasSideEffects Used by the mapper to optimize the XSLT code that is generated. This property is true by default.
Point to the resource assembly SetupResourceAssembly 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 SetName

SetTooltip

SetDescription

SetBitmap		 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 Category Categorize the functoid by using one or more Microsoft.BizTalk.BaseFunctoids.FunctoidCategory values.
Specify the number of parameters accepted SetMinParams

SetMaxParams

HasVariableInputs		 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 AddInputConnectionType Call AddInputConnectionType once for each Microsoft.BizTalk.BaseFunctoids.ConnectionType that the functoid supports.
Declare what your functoid can connect to OutputConnectionType Use values from Microsoft.BizTalk.BaseFunctoids.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 SetExternalFunctionName

SetExternalFunctionName2

SetExternalFunctionName3		 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 Microsoft.BizTalk.BaseFunctoids.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 SetScriptGlobalBuffer Any declarations made will be visible to other inline scripts included in the map.
Indicate which helper functions your inline functoid requires RequiredGlobalHelperFunctions 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 IsDate

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

Implementing Functoid Logic

To make the functoid useful you must implement one or more methods depending upon the functoid category. If the functoid is cumulative, then you need to supply three methods—one for initialization, one to do the accumulation, and one to return the accumulated value. If the functoid is not cumulative, then you need to supply one method that returns a value.

You also have to decide if the functoid implementation code should be copied inline into the map or kept within a compiled .NET assembly and used through a reference.

Consider using an inline functoid when:

  • It is okay for others to read and potentially modify your business logic.

  • Your functoid depends only upon .NET Framework namespaces that the map supports. For available namespaces, see Scripting Using Inline C#, JScript .NET, and Visual Basic .NET.

  • You do not want to deploy and maintain another assembly with your BizTalk solution.

  • You are writing a series of functoids that share variables.

    Consider using a referenced functoid when:

  • You do not want your business logic copied into the map where it might be seen or modified by others.

  • Your functoid depends upon .NET Framework classes that the map does not support.

  • The added functionality provided by the .NET Framework justifies deploying and maintaining another assembly with your BizTalk solution.

See Also

Developing a Custom Referenced Functoid
Developing a Custom Inline Functoid
Developing a Custom Cumulative Functoid
Microsoft.BizTalk.BaseFunctoids.BaseFunctoid