Defining and consuming custom settings

LLBLGen Pro designer comes with a fine-grained flexible settings system. Settings are defined in .frameworksettingsfiles and are editable inside the designer in the Project Properties editor and also in the editors for the main elements on their code gen. info tabs.

Please see the LLBLGen Pro designer documentation about 'How to control per-element code-gen settings easily' for details about specifying setting values. For the specific file format of the .frameworksettings, please see Frameworksettings XML file format.

A .frameworksettings file has to be placed in one of the following folders:

  • The Frameworks folder in the LLBLGen Pro installation folder
  • The Additional Templates folder specified in the Preferences
  • The Additional Templates folder specified in the Project Properties of the project you want to use the settings with.

A .frameworksettings file can be used with more than one target framework. The settings defined in the settings file are showing up when the target framework of the project matches a target framework specification in the .frameworksettings file. Frameworksettings files are loaded on startup and when a project is loaded.

Frameworksettings files contain the definition of settings, edited inside the designer. The values specified by the user are stored in the project file.

Target types

To specify which element the setting is defined for (which also means: in which editor the setting is showing up), a target element type has to be specified, which is a numeric value. You can add multiple values together to specify that a setting is meant for multiple elements.

  • Project: 1
  • Entity: 2
  • ValueType: 4
  • TypedList: 8
  • TypedView: 16
  • SPCall: 32
  • Normal field: 64
  • TvfCall: 128
  • Navigator returning single value: 256
  • Navigator returning collection: 512
  • TypedList field: 1024
  • TypedView field: 2048
  • SPCall parameter: 4096
  • Field mapped onto related field (forf): 8192
  • TvfCall parameter: 16384
  • RootDerivedElement: 32768
  • EmbeddedDerivedElement: 65536
  • DerivedElementFieldScalar: 131072
  • DerivedElementFieldSetOfFields: 262144
  • DerivedElementFieldSingleElement: 524288
  • DerivedModel: 1048576

Defaults

To be able to specify settings for a large group of elements at once, the setting system uses the concept of defaults. Each setting definition has a default source specification which, if specified, directs the designer to obtain the initial default value from the setting specified as default source. A setting which is to be used as default always has to be defined on the project level, so has to have 1 specified as target element.

Value lists

Frameworksettings allow the specification of value lists, which result in a drop down list in the property grid. See the Frameworksettings XML file format specification for details how to define the value lists. Value lists are specified using the source specification of a setting definition.

If a setting has as type enum, an enum type can also be specified as the source, using the full assembly name with type specification. This means that the enum type and assembly have to be loadable using System.Type. It's in general easier to specify a value list with values instead of using an enum type.

Consuming settings

Settings defined in a .frameworksettings file which are edited in the designer result in values being stored in the project file and in the model elements. During code generation, these setting values are available to the template logic.

The following description assumes you're using the .lpt template system, as it's highly recommended you use .lpt templates instead of .template (TDL) templates. For the statements to obtain setting values using TDL, please see the TDL statement list in this documentation.

There are two kinds of objects which contain settings: the project itself and all other elements in the project (all targets specified in the list above). To obtain a setting value at the project level, call one of the following methods on the Project object available in the template: GetRealBoolSettingValue(settingName), GetRealStringSettingValue(settingName), GetRealSettingValue(settingName) and GetRealIntSettingValue(settingName). Names are case sensitive.

To obtain a setting value for a setting on an element level, e.g. at the field level, first obtain the element's OutputSettingValuesContainer, which is exposed by the element's method OutputSettingValues. This object exposes the same four methods as the Project does, but this time the methods also require to pass in the Project object itself. This way, the system can automatically obtain default values set at the project level.

See the shipped templates for NHibernate, Linq to Sql and Entity Framework for a wide range of examples how to consume settings in templates and how to utilize the values specified to control template logic to customize the generated output.