Implementing a task performer

This section walks you through the various aspects of implementing a task performer. It is recommended that you consult the source code of the various task performer assemblies shipped with LLBLGen Pro for further information.

The code shipped is in C#, however you can implement your task performer in any .NET language. For a full understanding about the various objects in the project object tree, see the reference manual of the Application Core assembly for further details.

Constructing the class

Each task performer is a .NET class and can be implemented in any .NET language. A task performer has to implement the interface SD.LLBLGen.Pro.ApplicationCore.ITaskPerformer. This interface is located in the assembly SD.LLBLGen.Pro.ApplicationCore.dll, which is part of the LLBLGen Pro assemblies installed in the LLBLGen Pro directory.

You should start by adding a reference to that assembly in your task performer project. To make it easy for developers, the SD.LLBLGen.Pro.GeneratorCore namespace contains a base class, TaskPerformerBase, which already implements ITaskPerformer and contains some other nice functionality, like a method for logging text on the Application output window, which is called LogLine() and which has various overloads.

Add a class to your task performer project which derives from SD.LLBLGen.Pro.GeneratorCore.TaskPerformerBase. Because TaskPerformerBase contains two abstract methods, Perform(IGenerator executingGenerator, ITask taskDefinition) and Perform(IGenerator executingGenerator, ITask taskDefinition, Dictionary<string, TaskParameter> parameters), you have to implement these in your class.

These two methods are the methods which can be called by the Generator object executing the task performer: when the task tag has parameters specified, the Perform overload which accepts the parameters hashtable will be called, otherwise the Perform overload which doesn't accept a parameters hashtable. See the source code of the shipped task performers for details about this and about handling parameters and values.

The TaskPerformerBase class also defines a boolean property: PerformResult. This property should return the result of the task performer Perform method execution: true when the Perform() method called was ran successful, false otherwise.

All task performer class instances created are kept alive during the code generation process and task performers can walk the task tree via the Generator object to check whether task performers executed prior to the current task performer were successful or not by consulting this property. Please see the LLBLGen Pro Core designer assemblies reference manual for details about the TaskPerformerBase class and its methods.

The method LogLine() and its overloads are very important. Using these you can directly log a line onto the Application Output window in real time. For a user it is important to know what's going on. You can set flags to signal the method to log a line only when the verbose checkbox is checked, to canalize logged text for the user.

Walking project information

To use the project information, you have to add a reference to the SD.LLBLGen.Pro.ApplicationCore.dll assembly, which is also part of LLBLGen Pro and is located in the LLBLGen Pro installation folder.

The passed in IGenerator object, executingGenerator, is the object from which offers you the elements which are in scope for your task performer: which entities, valuetypes, typedlists, typedviews and other elements are chosen for your task. Additionally you can consult the Project object itself, however it's recommended you limit the elements used by your task to the ones exposed by the executingGenerator.

Debugging and testing

After you're done implementing the two Perform methods, you can test your task performer class. To do this, you first have to assign it to a task in a .tasks file. Make a copy of an existing .tasks file and add a task (or alter a task tag) tag to the task definitions and define your assembly and your class as the task performer for that particular task.

You then copy the assembly file (dll) created by compiling your task performer project and the .pdb file to the TaskPerformers directory of the LLBLGen Pro installation you use to test the task performer with. You can also store the task performer in the Additional task performers folder specified in the project properties or preferences.

The .pdb file is created in a debug build and is important because it points the CLR debugger to the source code location.

When you're all set, you set a break point in your task performer class, for example at the start of Perform(), and you start LLBLGen Pro the normal way. In Visual Studio.NET you 'attach' to this LLBLGen Pro process from the debug menu.

This will assure that when the break point set is called, from the LLBLGen Pro process, it will stop execution and transfer control over to the Visual Studio.NET instance. Start a generation process by hitting F7 after loading a project and select a preset with the task definition using your task performer. This will hit the breakpoint you've set and you can then step through the code.