This section details some core templating concepts that will help you get started with creating your first custom code generation template.
Artefact Templates and Artefact Set Templates
Two types of templates are supported: Artefact Templates and Artefact Set Templates. Together, these are referred to as Code Generation Templates; if you see that term, we are talking about either or both of the individual types.
It is important to understand the difference between these two types of templates, so we will cover that next.
Artefact Templates
An Artefact Template is used as a template for a single type of artefact. During design, if you choose to add a single artefact, then you are choosing the template from the list of available Artefact Templates.
An Artefact Template is composed of two separate items: the definition of the template (its name, description and how it is recognised within the system, plus all of the custom properties that are available for editing) and the text of the template, which is used to create the output at the time of code generation.
The template definition includes the location of the file containing the template text; if you rename the file containing the template text or change its path, then you must update the template definition with that new path and name so that it can be found.
Artefact Set Templates
An Artefact Set Template is used to create multiple artefacts at once. During design, if you choose to add multiple artefacts, then you are choosing from the list of available Artefact Set Templates.
An Artefact Set Template consists of a single item, as instead of containing its own template text, it merely points to Artefact Templates, and it is those Artefact Templates that do the job of code generation.
The definition of an Artefact Set Template is somewhat complex. An Artefact Set is made up of multiple batches, where each batch shares the same parent and data structure. If an Artefact Set consists of items that are expected to be placed in different parts of a solution, or reference different data structures, then you should create multiple batches.
Each batch then contains multiple batch members. Batch members are the definitions of each of the artefacts that are to be created. Batch members are defined hierarchically; if you wish to create a parent and multiple children (such as a project with multiple files or folders created within it) then that structure must be reflected in the definition of the batch members.
As you may be able to tell from this brief description, Artefact Set Templates are more complex to create than Artefact Templates. It is better to create a few Artefact Templates, and a few designs, before you try to create your own Artefact Set Template.
Template Sources
If you want to create custom templates, then they must be contained within a template source. Out of the box, DesiGen has a single Template Source - it's own, built in source. To have DesiGen look for additional templates, you must tell it where to look, by creating a Template Source that points to the file or folder in which the additional templates reside. Use the 'Manage Template Sources' feature within the 'Templating' menu to do this.
Exporting Code Generation Templates - Your Faithful Friend
The file formats for the creation of custom code generation templates are somewhat complex. At the moment, these file formats are in flux; as we add more features, we may need to change the file formats slightly. As a result, the documentation on the file formats is not complete.
There is, however, a simple way to get started - and that is to export one or more Code Generation Templates using the 'Export Templates' feature from the 'Templating' menu. This creates all of the definitions in the format you need, so you can use the output from the export to understand the formats, and modify the output to define your own templates.
Custom Properties
Custom properties are defined as part of an Artefact Template. These are used to capture input from the user for use in outputting in specific locations within the generated code. If you need for the user to enter a piece of information to make your template more flexible, then do that by defining a Custom Property.
As an example, a lot of the C# templates have a custom property of 'namespace'. Namespaces are a required part of a C# class, so it is important that the user enter the namespace somewhere for the generated code to be valid.
Custom properties can be inherited from a parent Artefact. This is one of the main reasons why Artefacts can be defined in a hierarchical tree structure, rather than just a flat list. inheriting a property value from a parent can dramatically reduce the number of times the data needs to be entered, which speeds up the process of design significantly.
Referring back to our previous example, C# namespaces are generally inherited from their container. The top level default namespace in a C# project is the name of the project, and the default for a folder within the project is the project name plus the folder name. By allowing all of our classes to inherit their namespaces from their parent, we need enter the data in a single place - against the project - and have all of our classes inherit the value and 'do the right thing' automatically, following the defacto convention for C# throughout.
Although custom properties can be inherited, that default behaviour is overridable. A user simply need remove the expression in curly braces from the property textbox and add their own custom value.
Custom Helper Types
Sometimes, code generation template text can be made much simpler by leaning on .NET code to do conversions and generate fragments for output. Custom Helper Types exist to fulfil this role. These are specially-designed classes created in a way that they are compatible with the code generator which allows them to be called just like they were built in functions provided by the code generator.
At the moment, DesiGen is limited to built in types to fulfil this role. In the future, you will be able to create your own Custom Helper Types and import them alongside the Artefact Templates that make use of them.
Happy templating!