Working with user functions

With user functions, you can easily extend the existing functionality of the template language TDL. User functions are written in C#, and they can make use of the entire scope of the .NET Framework.

How user functions are created is described in the chapter "Adding a user function".

Attributes

ToscaTDMConstantDefinition

For a user function, constants can be defined that facilitate the reading of a template. Thus, e.g. for the Trim() function, the constants TRIM_START, TRIM_END, and TRIM_BOTH are defined so that you do not have to work with numbers in TDL.

Instead of

String trimmedString = Trim(untrimmedString, 2);

the relating constant can be used:

String trimmedString = Trim(untrimmedString, TRIM_END);

Own constants are created via the ToscaTDMConstantDefinition attribute. This attribute receives the name of the constant to be created and the value. It should be used directly with the function, as shown here using the example of Trim():

[ToscaTDMConstantDefinition("TRIM_START", 1)]
[ToscaTDMConstantDefinition("TRIM_END", 2)]
[ToscaTDMConstantDefinition("TRIM_BOTH", 3)]
public string Trim( string str, long pos )
{
       // Code...
}

ToscaTDMStaticCleanup

User functions with the attribute ToscaTDMStaticCleanup are run after the data creation has finished in order to clean up the environment. They can for instance be used to close database connections or to reset test environments.

The attribute can be applied to private, static user functions without parameters.

       [ToscaTDMStaticCleanup]
       private static void MyCleanupFunction()
       {
               Tracer.Trace(Tracer.Level.Information, "Call of the cleanup function.");
       }

When executed in a project with a task, the above function would return the following output:

Data generation started...

Data generation started for task "Task1"...

Call of the cleanup function.

0 template(s) processed.

Completed successfully.

ToscaTDMStaticSetup

User functions with the attribute ToscaTDMStaticSetup are run directly before the data creation in order to initialize the environment.

The attribute can be applied to private, static user functions without parameters.

       [ToscaTDMStaticSetup]
       private static void MyStartupFunction()
       {
               Tracer.Trace(Tracer.Level.Information, "Call of the start function.");
       }

When executed in a project with a task, the above function would return the following output:

Data generation started...

Call of the start function.

Data generation started for task "Task1"...

0 template(s) processed.

Completed successfully.

ToscaTDMVariablesSetup

For constants that can not be defined using ToscaTDMConstantDefinition (for attributes, only simple constant values are allowed in C #), a function (private and static) can be created in which such constants can be defined. This function must be marked with the ToscaTDMVariablesSetup attribute.

Constants are created by adding another entry of type VarValue to the UserVariables property, as shown below using a constant to be filled with the contents of a file:

 [ToscaTDMVariablesSetup]
 private static void _InitializeSpecialVariables()
{
       UserVariables["MY_VAR"] = new VarValue(
new Value(File.ReadAllText(".\\MyDataFile.txt")),
VarProperties.Const | VarProperties.Predefined);
}

To define a constant, VarProperties.Const must be specified as shown above. Otherwise, the contents of the variables can be changed by TDL code.

Using additional libraries in user functions (for C# developers)

Additional assemblies in the project settings

If you need to access special classes such as the System.Runtime.Serialization.Formatters.Soap.SoapFormatter class in your code, you may not be able to immediately translate and use your function. The reason for this is that the assembly, in which this class is defined, is not used as standard.

To use classes of this kind, you must

  • find out which assembly contains the class (if you don't know this already). It may be useful to refer to msdn.microsoft.com/en-us/library/default.aspx for this.

  • Open the project settings by double-clicking on the project node in Project Explorer and enter the name of the assembly on the Behavior tab under Other Assemblies (see screenshot above).

An additional feature since TDM 1.7 is the ability to save .ttsaf files in the function directory of the project. This is described in chapter "Behavior".

This way, you can use any required assembly for your own functions. You can also specify multiple assemblies. The names of the assemblies must be separated by semicolons. In order to make the assemblies accessible for translation, they should be installed in the GAC (Global Assembly Cache). If this is not the case, we recommend entering the complete path to the assembly in the field Additional Assemblies.

The additional assemblies also have to be accessible during the execution of the project. For this, they must be present at at least one of the following locations:

  • in the GAC

  • in the directory that contains ToscaTDM.exe

  • in the directory of the project file which directly accesses the assembly

  • in the functions directory of the project which accesses the assembly (this also contains the compiled file userfunctions.dll)

  • in the Windows system directory

  • in the directory that contains ToscaTDM.AutoLoader.exe, if the project is an AutoLoader project