XML formats for .tasks, .preset and .platform files

The Tasks folder contains three types of files:

platform definition files, stored in files with the extension .platform
preset definitions, stored in files with the extension .preset
task definitions, stored in files with the extension .tasks

This section describes their XML format. If you want to create these files yourself, please use the shipped XSD files in the XSDs folder in the Tasks folder. These give you intellisense in for example VS.NET when you edit the files. Preset files can also be created graphically using the LLBLGen Pro designer.

Platform definition files.

Platforms are defined in .platform files which are located in the Tasks folder. A .platform file contains a definition for a platform which can be used to control tasks.

.platform file format

<platform 
    name=""
    isDefault = "true|false"
>
    <supportingDrivers>
        <supportingDriver id="driver GUID">
        <!-- more -->
    </supportingDrivers>
    <aspects>
        <aspect name="" value=""/>
        <!-- more -->
    </aspects>
</platform>

aspects are made available to all task performers and should be used by task performers to perform platform specific activities or functionality. For example, a task generator which has to perform activities based on the fact if a platform supports 'partial classes', has to check the aspects of the selected platform.

Attribute descriptions

name. The unique name for a platform. This name is refered to in the platformsSupported tags in tasks/task groups.
isDefault. the flag which specifies if this platform is the default. Starting with v5, .NET 4.6.1 is the default platform.

Child tag descriptions

aspects. Container with aspect definitions which are name-value pairs. Aspect names can be either one of the predefined aspect names or one created for a given task performer.
supportingDrivers. Optional element. If the element isn’t specified, the platform is supported by all drivers. If it is specified it contains supportingDriver elements which contain an id attribute which has a GUID as value, the GUID of the driver which supports this platform.

Predefined platform aspects The following list contains pre-defined aspects for platforms, which are understood by the task performers shipped with LLBLGen Pro.

supportsPartialClasses. Value can be 'true' or 'false'. Aspect which signals that the platform supports partial classes, so a code generator can use this aspect and the value of this aspect to control whether partial classes should be generated or not. The TDL code generator uses this aspect to generate the partial keyword into the output if applicable.

Task definition XML format

Tasks are defined in .tasks files and have the following format:

<task name="" 
    assemblyFilename="" 
    taskPerformerClass="" 
    requiresCleanCache="true|false" 
    description=""
  isOptional="bool"
>
    <supportedPlatforms>
        <platform name=""/>
    </supportedPlatforms>
    <supportedTemplateGroups>
        <templateGroup name=""/>
    </supportedTemplateGroups>
    <supportedFrameworks>
        <framework name="target framework name"/>
        <!-- more -->
    </supportedFrameworks>
    <dependencies>
        <dependency name=""/> <!--(0 or more) -->
    </dependencies>
    <parameters>
        <parameter name="" defaultValue="" isOptional="true|false" description="" valueType=""/> <!-- (0 or more)-->
    </parameters>
</task>

Attribute descriptions

name the name of the task. This is a unique name and identifies the task. It's a string based attribute and can be chosen freely, but if it's left empty or duplicates are found, the task is ignored. The name has to be unique in the complete task scope of llblgen pro, so every task or taskgroup found has to have a unique name within that set of tasks/taskrgroups.
assemblyFilename the filename in which LLBLGen Pro will find the code which will perform the task. The assembly has to be stored in the directory specified as taskPerformersRootFolder in the LLBLGen Pro config file.
taskPerformerClass the class which should be instantiated to perform the task. The class has to implement ITaskPerformer.
requiresCleanCache. Optional attribute, which controls whether LLBLGen Pro will clear the task cache container before the task is started. If omitted, false is assumed. Task cache clearing isn't required for normal code generation tasks, though it can be required, if for example filename caches have to be cleared if multiple vs.net project files have to be generated.
description. Attribute which contains the description of the task.
isOptional. Flag which signals task performers that this task is optional so it can't lead to failure.

Child tag descriptions

supportedPlatforms. Optional tag. Container for platform tags, which specify which platforms the task supports. A platform tag has to refer to a known platform definition loaded from .platform files. If this tag is omitted, LLBLGen Pro will assume the task supports all platforms. This tag is only necessary for platform specific tasks like vs.net project generator tasks. If a containing taskgroup specifies a platform, all tasks inside the taskgroup inherit that setting if they're part of the taskgroup during task execution. This is because a task inside a taskgroup isn't executable if the containing taskgroup isn't executable due to any restriction applied to the taskgroup.
supportedTemplateGroups. Optional tag. Container for templateGroup tags which specify to which template groups this task belongs to/is supported. If omitted, all template groups are supported.
supportedFrameworks. Optional tag. Container for framework tags which specify for which target frameworks the task is valid. If not present, all target frameworks supported by LLBLGen Pro are assumed. Child element framework has one attribute: name, which is the full name of the target framework, e.g. "LLBLGen Pro Runtime Framework".
dependencies. Container of dependency tags which contain solely the name of the task / taskgroup this particular task is depending on. This tag can be empty.
parameters. Container for parameter tags which define the various parameters for the task. This is a change from v1.x where parameters were defined inside the task tag, but containing them inside a container tag is better for readability. A parameter tag defines a parameter for the task. The following attributes are allowed for parameter tags.
- name. Name of the parameter. Has to be unique within a task.
- defaultValue. The initial value for this parameter. Can be overriden in a preset.
- isOptional. Flag to signal if the parameter is optional or not.
- description. Optional. Short description for the parameter, which can be used in GUIs.
- valueType. Optional.Type specification for the value. This specification can be used in GUIs to specify proper value selection controls. Possible values: string (default), bool, templateID, emitType

Task group definition XML format

Task groups are groups of task definitions and / or task groups and are also stored in .tasks files. A .tasks file can contain a task group definition or a single task definition.

<taskGroup name="" 
    requiresCleanCache="true|false" 
    description=""
  isOptional="true|false"
>
    <supportedPlatforms>
        <platform name=""/>
    </ supportedPlatforms >
    <supportedTemplateGroups>
        <templateGroup name=""/>
    </supportedTemplateGroups>
    <supportedFrameworks>
        <framework name="target framework name"/>
        <!-- more -->
    </supportedFrameworks>
    <dependencies>
        <dependency name=""/> <!--(0 or more)-->
    </dependencies>
    <task ... /> <!--(0 or more)-->
    <taskGroup /> <!--(0 or more)-->
</taskGroup>

name is similar to task.name.
isOptional is similar to task.isOptional.
dependencies is similar to task.dependencies.
requiresCleanCache is similar to task.requiresCleanCache.
supportedPlatforms is similar to task.supportedPlatforms, though any platform specified here restricts any containing taskgroup/task.
supportedTemplateGroups is similar to task.supportedTemplateGroups.
supportedFrameworks is similar to task.supportedFrameworks.

Preset definition XML format

Presets are groups of tasks/taskgroups with a specific order and when needed task parameter value specification which differs from the default value for that task parameter. Presets are stored in .preset files and form the definition of a run queue, which means that a preset can be used to execute a set of tasks by the generator process.

Typically, presets are created in the LLBLGen Pro designer, in the generator configuration dialog.

<preset 
    name=""
    lastModifiedOn=""
    createdBy=""
    isSealed="true|false"
    isDefault="true|false"
>
    <supportedTemplateGroups>
        <templateGroup name="" />
    </supportedTemplateGroups>
    <supportedPlatforms>
        <platform name=""  />
    </supportedPlatforms>
    <supportedFrameworks>
        <framework name="target framework name"/>
        <!-- more -->
    </supportedFrameworks>
    <taskPresets>
        <taskPreset name="" displayName="" requiresCleanCache="true|false" isEnabled="true|false">
            <performRule enabled="" settingName="" operator="" operand=""/>
            <parameters>
                <parameter name="" value=""/>
            </parameters>
        </taskPreset>
        <taskGroupPreset name="" displayName="" requiresCleanCache="true|false" isEnabled="true|false"
            additionalRootNamespace="" additionalDestinationFolder="">
            <performRule isEnabled="" settingName="" operator="" operand=""/>
            <elementSelectionRule isEnabled="" settingName="" operator="" operand="" targetElementType=""/>
          <taskPreset/> <!--(0 or more)-->
            <taskGroupPreset /> <!--(0 or more)-->
        </taskGroupPreset>
    </taskPresets>
</preset>

Attribute descriptions

name The unique name for the preset which is used to reference to the preset.
lastModifiedOn DateTime in XML format on which the preset was last modified.
createdBy
isSealed A boolean flag which signals that the preset can only be saved under a different name. Of course a user can manually edit the file on disk, this flag is meant for the LLBLGen Pro designer to avoid having the user overwrite originally shipped presets.
isDefault. A boolean flag which signals whether the preset is the default one to select on projects on which the code generator hasn't run yet. Default is 'false'.

Child tag descriptionss

supportedTemplateGroups. Optional tag. This tag contains templateGroup tags which illustrate for which template groups this preset is valid for. If it's omitted, all template groups are supported. The contents of this tag is used to filter out presets which aren't usable with a selected template group. Normally this is only set on specific presets, like adapter specific presets.
supportedFrameworks. Similar to task.supportedFrameworks.
supportedPlatforms. Optional tag. This tag contains platform tags which illustrate for which platforms this preset is valid for. If it's omitted, all platforms are supported. The contents of this tag is used to filter out presets which aren't usable with the selected platform. Normally this is only set on specific presets
taskPresets. Container tag which contains the preset values for tasks and taskgroups. If a task or taskgroup is listed inside this taskPresets node, the values set for the preset will overwrite the defaultValues set initially for the task, so a task selected will then get the values set for the preset. A non-optional parameter which isn't listed in a preset will get its default value. Only parameter values can be set by presets, as well as the optional requiresCleanCache flag.

taskPreset elements and taskGroupPreset elements can contain optional attributes, which aren't available on the task and taskGroup elements:

displayName. Optional attribute and if specified it’s used for the name the task/taskgroup has in the runtime queue treeview.
additionalRootNamespace. For taskGroupPreset. Optional attribute. This rootnamespace is relative to the set rootnamespace for the complete code generation cycle (the base rootnamespace). So if the rootnamespace is set to “MyCompany.MyApp”, the rootnamespace of a taskgroup can be either empty or a string, which is then appended as a subnamespace inside the base rootnamespace set.
additionalDestinationFolder
performRule. This optional element is used to skip a task or taskgroup if the rule results to false. If the rule is disabled (isEnabled="false"), the rule is considered 'true' and the task or task group is always performed. It has the following attributes:
- isEnabled. If true, the performRule is examined, otherwise it's ignored and 'true' is used as the result
- settingName. The setting at the Project level (so editable in the Project properties) which value is examined in this rule. If the setting isn't found, the rule is considered true.
- operator. ** The operator to use for the value comparison. This is a numeric value of an enum: NoOp (0), Equals (1), NotEquals (2), In (3), NotIn (4)
- operand. This is the operand to use with the operator on the setting value. Comma separated value lists are supported. Strings are compared case insensitively.
elementSelectionRule. This optional element is used to select which elements participate in the task. If the rule is disabled (isEnabled="false"), no element filtering takes place and all elements offered by the project and the scope at hand (target DB, group etc.) will be available to the task. If isEnabled is set to true, filtering will take place on the elements with the targetElementType specified (see Defining and consuming custom settings for the list of types available. Only root elements are accepted (entity, value type etc.)): all elements which have a setting with the name specified set to the value specified, taking into account the operator specified, will be available to the task, all other elements are ignored. It has the following attributes:
- isEnabled. If true, the elementSelectionRule is examined, otherwise it's ignored and all elements are available to the task.
- settingName. The setting at the element level which value is examined in this rule. If the setting isn't found, the rule is considered true (so the element is available to the task)
- operator. ** The operator to use for the value comparison. This is a numeric value of an enum: NoOp (0), Equals (1), NotEquals (2), In (3), NotIn (4)
- operand. This is the operand to use with the operator on the setting value. Comma separated value lists are supported. Strings are compared case insensitively.
- targetElementType. This is a numeric value which specifies the element type to filter, and can be one of the following: 2 (entity), 4 (valueType), 8 (TypedList), 16 (TypedView), 32 (SPCall), 128 (TvfCall), 32768 (RootDerivedElement).

Ad-hoc templates definition XML format

Ad-hoc template definitions are defined in .adhoctemplates files which use the following format:

<adhocTemplates>
    <template filename="" outputFilename="" emitType=""/>
</adhocTemplates>

filename is relative to the .adhoctemplates file location, which is the same as with .templatebindings files. You can specify an absolute path if you want.
outputFilename can be relative to the Destination root folder specified in the code generation task in the designer, and it then has to start with .\ or ..\. All other paths are considered absolute paths. The outputFilename can contain macros like with presets: [elementName], [time], [containerName] and [groupName]. It has to contain the right file extension, as there's no output language directive.
emitType is optional, if omited the default is generic, which means the template is run once. Possible values are:
- 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.
- 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.
- 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 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.