Shipped task performers

LLBLGen Pro comes with a set of task performers you can use in your own generator configuration files. The source code of these task performers is included in the sourcecode archive available to customers. This section describes the task performers shipped with LLBLGen Pro and the parameter details.

For folder and file names, placeholders are recognized. The placeholders recognized in folder names are:

• [dbspecificSubFolder]. Used for LLBLGen Pro Runtime framework, and replaced with the setting value "AdapterDbSpecificSubFolderName"
• [dbgenericSubFolder]. Used for LLBLGen Pro Runtime framework, and replaced with the setting value "AdapterDbGenericSubFolderName"
• [driverShortName]. Replaced with the shortName element value of the driver of the current database which mappings / relational model data is consumed during code generation. This element value is defined in the driver config file of the driver. Example value: SQL Server (SqlClient)
• [databaseShortName]. Replaced with the databaseShortName element value of the driver of the current database which mappings / relational model data is consumed during code generation. This element value is defined in the driver config file of the driver. Example value: SQL Server
• [elementName]. Replaced with the name of the element, e.g. the name of the current entity.
• [groupName]. Replaced with the name of the group the current element is in.

The placeholders recognized in file names are:

• [extension]. Replaced with the extension defined in the target language's .language file. Used to specify code file extensions.
• [time]. Replaced with the actual current time in the format: yyyyMMdd-HHmmss
• [containerName]. Replaced with the ActiveSourceElementsContainerName value of the executing Generator object, which is the projectname when the project property GroupUsage is set to AsVisualGroupingMechanism, otherwise it's the active group name.
• [elementName]. Replaced with the name of the element, e.g. the name of the current entity.
• [groupName]. Replaced with the name of the group the current element is in.

DirectoryCreator

This is a small task performer which will create new directories, based on the parameters specified. The following parameters can be specified:

• folderToCreate This is the folder relative to the project destination directory which will be created. Mandatory.
• failWhenExistent If set to 'true', a GeneratorAbortException exception will be thrown when the directory is already available. Optional. Default: 'false'.
• clearWhenExistent If set to 'true', the directory will be cleared, if it already existed. Set failWhenExistent to 'false' when using this parameter since failWhenExistent overrules clearWhenExistent. Optional. Default: 'false'.

Starting with v4.0, it's not necessary to pre-create the folders for classes using this task perfomer anymore, folders are created on-the-fly now as needed.

FileRemover

This is a small task performer which removes one file on disk based on parameters. It can be used to make sure files which were generated with a previous setup are cleaned up properly, e.g. because they're optional or not needed anymore. It doesn't accept wildcards.

The following parameters can be specified:

• filenameFormat. This is a format specifier for the file to delete. the following placeholders are recognized and will replace them with the related data element:
  • [dbgenericSubFolder]. This will be replaced by the value specified in the project properties for AdapterDbGenericSubFolderName. Adapter specific
  • [groupName]. This will be replaced by the group name that's currently active.
  • [dbspecificSubFolder]. This will be replaced by the value specified in the project properties for AdapterDbSpecificSubFolderName. Adapter specific
  • [extension]. This will be replaced by the fileExtension value specified in the template config file.
  • [rootNameSpace]. This will be replaced by the active rootnamespace.
  • [containerName]. This will be replaced by the active container name, either by the groupname if groups are separate projects, or the project name
  • [driverShortName]. This will be replaced by the shortname of the active database driver
  • [databaseShortName]. This will be replaced by the shortname of the database related to the active database driver.
• ignoreErrors. Optional. If set to true (default), any error occuring during file removal will be ignored. If set to false, any error will cause a GeneratorAbortException to be thrown

DirectoryRemover

Similar to FileRemover, this task performer removes directories instead of files. This task performer accepts a single parameter, folderToRemove. This parameter accepts the following macros:

• [dbgenericSubFolder]. This will be replaced by the value specified in the project properties for AdapterDbGenericSubFolderName. Adapter specific
• [groupName]. This will be replaced by the group name that's currently active.
• [dbspecificSubFolder]. This will be replaced by the value specified in the project properties for AdapterDbSpecificSubFolderName. Adapter specific
• [rootNameSpace]. This will be replaced by the active rootnamespace.

The task performer removes the folder recursively, so all folders and files in the folder to remove will be removed as well.

CodeEmitter

This is the TDL templates based code emitter of the system. It will process one template at a time, so for each output file type (e.g. entity class, typed list class etc.) a task should be defined. It supports the following parameters, which all have to be defined for a codeEmitter task, unless specified otherwise. If one is omitted, the CodeEmitter task will fail, however will not terminate the project.

The following parameters can be set :

• destinationFolder This is the folder relative to the project destination directory where the output file(s) should be written. Mandatory. It's created if it doesn't exist.
• filenameFormat This is the format for output filenames. Mandatory.
• dependentUponFileFormat. This is the format of the filename the files produced by this task performer depend upon in a VS.NET project. Optional. Uses the same format characteristics as filenameFormat.
• templateID This is the template ID of the template to load and use for code emitting. When the templateID specified is not found in the template config file, the task is skipped. Mandatory.
• failWhenExistent If the target file already exist, and this parameter is set to true, a GeneratorAbortException will be thrown. If this parameter is omitted, and a file is readonly, the CodeEmitter will simply skip generating code for that file. Optional, default: 'false'.

• emitType This is the type of code emitting the CodeEmitter will perform. Mandatory. Based on the value of this parameter, the codeEmitter will walk a given set of elements in the project or will simply execute the specified template without walking a set of elements. The following values can be specified as types:

  • actionSPCalls. The engine will execute the specified template for all action stored procedure calls together.
  • allCatalogs. The task is executed once for all catalogs in all databases.
  • allDerivedModels. The task is executed once for all derived models in the project.
  • allDrivers. The task is executed once for all drivers with a database in the project. The active object is a DBDriverBase instance.
  • allEntities. The engine will walk all entities defined in the project and will for each entity execute the template specified.
  • allModelViews. The engine will walk all modelviews defined in the project and will for each modelview execute the template specified.
  • allSchemas. The task is executed once for all schemas in all databases.
  • allSPCalls. The task is executed once for every stored procedure call in the project, whether they’re an action sp call or retrieval sp call.
  • allStoredProcedures. The task is executed once for all stored procedures in all databases.
  • allRootDerivedElements. The engine will walk all root derived elements defined in the active Derived Model and will for each root derived element execute the template specified.
  • allRootDerivedElementsAllModels. The task is executed once for each root derived element in all derived models, not only the one in scope.
  • allTables. The task is executed once for all tables in all databases.
  • allTableValuedFunctions. The task is executed once for all table valued functions in all databases.
  • allTypedLists. The engine will walk all typedlists defined in the project and will for each typed list execute the template specified.
  • allTypedViews. The engine will walk all typed views defined in the project and will for each typed view execute the template specified.
  • allTvfCalls. The engine will walk all TvfCalls defined in the project and will for each TvfCall execute the template specified.
  • allValueTypes. The engine will walk all value types defined in the project and will for each value type execute the template specified.
  • allViews. The task is executed once for all views in all databases.
  • generic The code emitter will simply use the specified template and the current project and generate code. The statements in the template are executed for the project, no elements inside the project are used as a set to execute the template multiple times for multiple files. A single file is the result.
  • retrievalSPCalls. The engine will execute the specified template for all retrieval stored procedure calls together.

  For each type, [elementName] is replaced with the name of the element, if multiple files are generated, otherwise ignored, [time] with the actual time in yyyyMMdd-HHmmss format, [containerName] with the name of the container, which is the project or derived model name, [groupName] with the name of the group of the element, if applicable.

• templateBindingDefinitionName The name of the templatebindings to use for finding the binding for the templateID specified. Optional. Should be specified only if a very specific template id binding has to be selected, despite the order of the templatebindings.
• templateIsOptional. This parameter controls (if defined, default is false) if a missing templateID binding results in an error (false, default) or a normal action description.
• elementFilter. This filter will accept the body of a lambda for filtering in string format, according to the DynamicQuery example for C#, shipped with VS.NET. The filter is used to filter elements in the set to process. Example "Fields.Count > 0", which can be used to allow only entities which have fields. Optional, default: empty (all elements in the input set are processed)

ProjectFileCreator

The ProjectFileCreator task performer is used to generate a Visual Studio.NET project file for the project just generated. It works in conjunction with the CodeEmitter, that it relies on the CodeEmitter to create a list of files generated (which includes the files skipped because they were existent and failWhenExistent was set to true) which is stored in the taskCache of the Generator object executing all the task performers.

It is therefore important that a task which uses the ProjectFileCreator as the task performer is specified at the end of a generator configuration file.

The ProjectFileCreator supports DependentUpon tags. To specify if a generated file A is dependent upon another file B, specify the fileformat of B as the value of the parameter dependentUponFileFormat on the task which generates A.

ProjectFileCreator looks for the following tags (case sensitive):

• <[ProjectGuid]>, the guid for the project.
• <[ProjectName]>, the name of the project
• <[BinRootFolder]>, the root folder for the bin folders for the project
• <[RootNamespace]>, the root namespace for the project
• <[DbSpecificNamespaceSuffix]>, the db specific namespace suffix (adapter)
• <[DbSpecificProjectSuffix]>, the db specific project file suffix (adapter)
• <[DbGenericProjectSuffix]>, the db generic project file suffix (adapter)
• <[RuntimeLibraryHintPath]>, the path to the runtime libraries.

The following parameters can be specified:

• destinationFolder This is the folder relative to the project destination folder where the project file should be stored. Mandatory.
• binRootFolder This is the folder relative to destinationFolder which is the root folder for the bin (VB.NET) / bin\debug|release (C#) folders. The value specified has to be appended with a \ and can be empty. Optional.
• filenameFormat This is a format specifier for the output filename to use. Mandatory.
• alterWhenExistent If the target file already exist, and this parameter is set to true, the ProjectFileCreator will not create a new file and will alter the existing file instead. If this parameter is omitted or the file is readonly, the ProjectFileCreator will simply skip generating code for that file. If this parameter's value is set to false, and the file exists, the file is simply overwritten, when it's not readonly however keeping the same GUID. Optional, default: 'true'.
• useRootNameSpaceForProjectName When set to 'true', the root namespace is used as project name. Optional. When set to false, or not specified, a screen will pop up.
• templateID The template ID to use for a vs.net project file. The platform and language in the generatorobject are used to select the proper template
• projectName. Name which is used for the projectname if useRootNameSpaceForProjectname is set to false. If left empty, the ProjectName property value of the LLBLGen Pro project is used instead, if useRootNameSpaceForProjectname is set to false or left empty. Optional.
• templateBindingDefinitionName The name of the templatebindings to use for finding the binding for the templateID specified. Optional. Should be specified only if a very specific template id binding has to be selected, despite the order of the templatebindings.
• clearFileCacheAfterwards. When set to true, the filename cache in the generator cache is cleared. Optional. Default is false.
• buildActionPerExtension. A '|' delimited list of string pairs, which define per extension which buildaction to use in the vs.net project file. If the extension is empty, the build action is considered the default for all extensions not mentioned in the list. Example: .config;None|.hbm.xml;EmbeddedResource|;Compile

DotNetTemplateEngine

This is the C#/VB.NET template engine, stored in the LptParser assembly. It will process one .lpt template at a time, so for each output file type (e.g. entity class, typed list class etc.) a task should be defined. It supports the following parameters, which all have to be defined for a DotNetTemplateEngine task, unless specified otherwise.

DotNetTemplateEngine processes only .lpt templates, which contain template logic in C# or VB.NET. CodeEmitter only processes .template templates which contain template logic in TDL. DotNetTemplateEngine is not an interpreter. It will parse all .lpt templates in the template set, generate C# or VB.NET code from them and compile that code into a library assembly.

That assembly is then used for the object(s) to generate output. Based on the targetLanguageDescription value in the used template set config the compiler is chosen ('C#' for C# and 'VB.NET' for VB.NET). A cache is kept for assemblies already created, the executing generator checks whether it needs to compile an additional assembly (e.g. for include templates, or for a different database type, which could contain different template files).

See for more information about .lpt templates the Lpt templates engine documentation.

The following parameters can be set :

• compileOnly. This option will generate C#/VB.NET code and compile that code to an assembly on disk, returning the compile results in the taskCache with the key 'CompilerResult'. It will not produce any output. When this option is specified, templateAssemblySourceFileFormat has to be set as well. When this option is specified, destinationFolder is treated as a fixed path. The filename the dll is compiled to is LptTemplateAssembly.dll, overwriting any existing dll. Optional. Default: 'false'.
• debugBuild. This option will build a debug build of the lpt templates instead of a release build. A debug build will contain a .pdb file and will always be to disk and when specified, destinationFolder also has to be specifiedOptional. default: 'false'
• destinationFolder. This is the folder relative to the project destination folder where the output file(s) should be stored. If CompileOnly is specified, this option holds the value to the fixed path where the file with the compiled code is stored in.
• filenameFormat. This is a format specifier for the output filename to use. Ignored if CompileOnly is specified.
• dependentUponFileFormat. This is the format of the filename the files produced by this task performer depend upon in a VS.NET project. Optional. Uses the same format characteristics as filenameFormat.
• templateAssemblySourceFileFormat. The pre-compilation sourcecode, the result of the template parsing (C# code or VB.NET code) which will form the template classes code can be exported to a file. Use [extension] for the extension in the fileformat. This is an optional parameter and can be used to debug template compilation errors. If CompileOnly is specified, this option is mandatory, and the file is stored in the folder specified with the option destinationFolder. The filename is stored in the taskCache with the key 'templateAssemblySourceFilename'. It is recommended that when debugBuild is specified, this parameter is also specified.
• templateID. This is the template ID of the template to run. When the templateID specified is not found in the template config file, the task is skipped. Ignored if CompileOnly is specified.
• templateBindingDefinitionName The name of the templatebindings to use for finding the binding for the templateID specified. Optional. Should be specified only if a very specific template id binding has to be selected, despite the order of the templatebindings.
• failWhenExistent. If the target file already exist, and this parameter is set to true, the engine will skip executing the template code for that file. If this parameter is omitted, and a file is readonly, the engine will simply skip generating code for that file. Optional, default: 'false'. Ignored if CompileOnly is specified.

• emitType. This is the type of code emitting the engine will perform. Based on the value of this parameter, the engine will walk a given set of elements in the project or will simply execute the specified template without walking a set of elements. The following values can be specified as types.

  • allEntities. The engine will walk all entities defined in the project and will for each entity execute the template specified.
  • allTypedLists. The engine will walk all typedlists defined in the project and will for each typed list execute the template specified.
  • allTypedViews. The engine will walk all typed views defined in the project and will for each typed view execute the template specified.
  • actionSPCalls. The engine will execute the specified template for all action stored procedure calls together.
  • allValueTypes. The engine will walk all value types defined in the project and will for each value type execute the template specified.
  • retrievalSPCalls. The engine will execute the specified template for all retrieval stored procedure calls together.
  • allModelViews. The engine will walk all modelviews defined in the project and will for each modelview execute the template specified.
  • allRootDerivedElements. The engine will walk all root derived elements defined in the active Derived Model and will for each root derived element execute the template specified.
  • generic. The engine will simply execute the specified template. A single file is the result.

  Ignored if compileOnly is specified. For each type, [elementName] is replaced with the name of the element, if multiple files are generated, otherwise ignored, [time] with the actual time in yyyyMMdd-HHmmss format, [containerName] with the name of the container, which is the project or derived model name, [groupName] with the name of the group of the element, if applicable.

• templateIsOptional. This parameter controls (if defined, default is false) if a missing templateID binding results in an error (false, default) or a normal action description.
• elementFilter. This filter will accept the body of a lambda for filtering in string format, according to the DynamicQuery example for C#, shipped with VS.NET. The filter is used to filter elements in the set to process. Example "Fields.Count > 0", which can be used to allow only entities which have fields. Optional, default: empty (all elements in the input set are processed)