TeamCity Plugin Development Help
 

Kotlin DSL Extensions

Edit page Last modified: 08 July 2022

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:

  1. Inside the plugin's ZIP package, create the kotlin-dsl directory.

  2. Inside the kotlin-dsl directory, create an *.xml file 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 kotlin-dsl directory.
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. This means that your DSL code won't be available when a user clicks the 'View as code' button or when an initial commit is performed when enabling versioned settings in a project. Use this method only if the recommended approach lacks flexibility for your purposes.