Kotlin DSL Extensions
TeamCity allows writing custom Kotlin DSL extensions for plugins. Extensions define a plugin-specific DSL syntax for settings (for example, of a build runner or a project feature implemented by the plugin). This provides the following benefits for DSL-based projects:
typed parameters for each specific functionality;
autocompletion of parameters in IDE;
controlled validation and proper compilation;
DSL extensions are natively mapped onto the UI settings and displayed in the "View DSL" mode;
after each UI change, versioned settings are updated using the plugin-specific DSL syntax.
With extensions, you can create a custom class library for your plugin, and TeamCity will handle the DSL generation and conversion when the plugin functionality is used in DSL-based projects.
To add an extension to a plugin:
Inside the plugin's ZIP package, create the
kotlin-dsldirectory, create an
*.xmlfile and describe a specific extension. Refer to the sections below for more information on expected syntax.
This is a recommended approach which covers most use cases and can be properly processed by TeamCity.
If your plugin implements a major addition to the TeamCity functionality and requires an arbitrary DSL extension that cannot be expressed using the recommended approach, you have an option to write a completely custom extension. For this, add a
*.jar file with your code to the same
Note that TeamCity will not be able to generate DSL code using the syntax provided by your extension if you employ this approach; it will generate standard Kotlin DSL code instead. Use this method only if the recommended approach lacks flexibility for your purposes.
Declaring DSL Extension
To declare an extension in an XML file, use the following general syntax:
<kind_value> describes what kind of functionality is introduced by the extension. Supported values are:
<type_name> is a type of the build step, build feature, trigger or any other entity implemented by your plugin.
params block can include as many parameters as needed:
To create a composite parameter that includes other nested parameters, use the
Supported parameter attributes are:
Marks a parameter as required or optional.
A parameter name to be used in DSL.
For a boolean parameter, specify the
Refer the VCS root or build configuration object.
Parameters can have nested options, and these options can have nested parameters. Options are represented in the UI as values of the parameter's drop-down menu, and their nested parameters are displayed only if the parent option is selected.
In general, options of a parameter are declared as follows:
To add nested parameters to an option, use the following syntax:
You can introduce custom enum types with your extension. Types are usually specified after the parameters' declaration.
The following example code will add an enum type to your extension:
If you want to create a DSL extension that adds functionality over an existing extension of another plugin, use the
dsl-add-on functionality. Add-on files are stored in
.xml files in the